src/app/util/esi-management.h

   1 /**
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *
  20  *    Copyright (c) 2020 Silicon Labs
  21  *
  22  *    Licensed under the Apache License, Version 2.0 (the "License");
  23  *    you may not use this file except in compliance with the License.
  24  *    You may obtain a copy of the License at
  25  *
  26  *        http://www.apache.org/licenses/LICENSE-2.0
  27  *
  28  *    Unless required by applicable law or agreed to in writing, software
  29  *    distributed under the License is distributed on an "AS IS" BASIS,
  30  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31  *    See the License for the specific language governing permissions and
  32  *    limitations under the License.
  33  */
  34 /***************************************************************************/
  35 /**
  36  * @file
  37  * @brief It implements and manages the ESI table. The
  38  *ESI table is shared among other plugins.
  39  *******************************************************************************
  40  ******************************************************************************/
  41
  42 #pragma once
  43
  44 #include "af.h"
  45
  46 #ifndef EMBER_AF_PLUGIN_ESI_MANAGEMENT_ESI_TABLE_SIZE
  47 #define EMBER_AF_PLUGIN_ESI_MANAGEMENT_ESI_TABLE_SIZE 3
  48 #endif // EMBER_AF_PLUGIN_ESI_MANAGEMENT_ESI_TABLE_SIZE
  49
  50 #ifndef EMBER_AF_PLUGIN_ESI_MANAGEMENT_MIN_ERASING_AGE
  51 #define EMBER_AF_PLUGIN_ESI_MANAGEMENT_MIN_ERASING_AGE 3
  52 #endif // EMBER_AF_PLUGIN_ESI_MANAGEMENT_MIN_ERASING_AGE
  53
  54 #ifndef EMBER_AF_PLUGIN_ESI_MANAGEMENT_PLUGIN_CALLBACK_TABLE_SIZE
  55 #define EMBER_AF_PLUGIN_ESI_MANAGEMENT_PLUGIN_CALLBACK_TABLE_SIZE 5
  56 #endif // EMBER_AF_PLUGIN_ESI_MANAGEMENT_PLUGIN_CALLBACK_TABLE_SIZE
  57
  58 typedef struct
  59 {
  60     EmberEUI64 eui64;
  61     chip::NodeId nodeId;
  62     uint8_t networkIndex;
  63     chip::EndpointId endpoint;
  64     uint8_t age; // The number of discovery cycles the ESI has not been discovered.
  65 } EmberAfPluginEsiManagementEsiEntry;
  66
  67 typedef void (*EmberAfEsiManagementDeletionCallback)(uint8_t);
  68
  69 /**
  70  * Searches in the ESI table by the pair node (short ID, endopoint).
  71  *
  72  * Returns a pointer to the entry if a matching entry was found, otherwise it
  73  * returns NULL.
  74  */
  75 EmberAfPluginEsiManagementEsiEntry * emberAfPluginEsiManagementEsiLookUpByShortIdAndEndpoint(EmberNodeId shortId,
  76                                                                                              chip::EndpointId endpoint);
  77
  78 /**
  79  * Searches in the ESI table by the pair node (long ID, endopoint).
  80  *
  81  * Returns a pointer to the entry if a matching entry was found, otherwise it
  82  * returns NULL.
  83  */
  84 EmberAfPluginEsiManagementEsiEntry * emberAfPluginEsiManagementEsiLookUpByLongIdAndEndpoint(EmberEUI64 longId,
  85                                                                                             chip::EndpointId endpoint);
  86
  87 /**
  88  * Allows retrieving the index of an entry that matches the passed short ID
  89  * and endpoint.
  90  *
  91  * It returns the index of the matching entry if a matching entry was found,
  92  * otherwise it returns 0xFF.
  93  */
  94 uint8_t emberAfPluginEsiManagementIndexLookUpByShortIdAndEndpoint(EmberNodeId shortId, chip::EndpointId endpoint);
  95
  96 /**
  97  * Allows retrieving the index of an entry that matches the passed long ID
  98  * and endpoint.
  99  *
 100  * It returns the index of the matching entry if a matching entry was found,
 101  * otherwise it returns 0xFF.
 102  */
 103 uint8_t emberAfPluginEsiManagementIndexLookUpByLongIdAndEndpoint(EmberEUI64 longId, chip::EndpointId endpoint);
 104
 105 /**
 106  * Searches in the ESI table by the table index.
 107  *
 108  * Returns a pointer to the ESI entry stored at the index passed as
 109  * parameter.
 110  */
 111 EmberAfPluginEsiManagementEsiEntry * emberAfPluginEsiManagementEsiLookUpByIndex(uint8_t index);
 112
 113 /**
 114  * Iterates through the entries in the
 115  * table that are within a certain age threshold.
 116  *
 117  * If the passed pointer is NULL, it returns the first active entry with age
 118  * lesser or equal than the passed age parameter (if any). Otherwise, it returns
 119  * the next active entry that satisfy the age requirement. If the are no entries
 120  * after the passed entry that satisfy the age requirement, it returns NULL.
 121  */
 122 EmberAfPluginEsiManagementEsiEntry * emberAfPluginEsiManagementGetNextEntry(EmberAfPluginEsiManagementEsiEntry * entry,
 123                                                                             uint8_t age);
 124
 125 /**
 126  * Allows obtaining a free entry in the ESI table. It is the
 127  * requester responsibility to properly set all the fields in the obtained free
 128  * entry such as nodeId, age, and so on to avoid inconsistencies in the
 129  * table.
 130  *
 131  * Returns a free entry (if any), otherwise it clears the oldest entry whose age
 132  * is at least EMBER_AF_PLUGIN_ESI_MANAGEMENT_MIN_ERASING_AGE (if any) and
 133  * returns it, otherwise it returns NULL.
 134  */
 135 EmberAfPluginEsiManagementEsiEntry * emberAfPluginEsiManagementGetFreeEntry(void);
 136
 137 /**
 138  * Deletes the entry indicated by the parameter 'index' from the
 139  * ESI table.
 140  */
 141 void emberAfPluginEsiManagementDeleteEntry(uint8_t index);
 142
 143 /**
 144  * Increases the age of all the active entries in the table. A
 145  * non-active entry is an entry whose short ID is set to EMBER_NULL_NODE_ID.
 146  */
 147 void emberAfPluginEsiManagementAgeAllEntries(void);
 148
 149 /**
 150  * Clears the ESI table, i.e., it sets the short ID of each entry
 151  * to EMBER_NULL_NODE_ID.
 152  */
 153 void emberAfPluginEsiManagementClearTable(void);
 154
 155 /**
 156  * Allows a plugin to subscribe to ESI entries deletion
 157  * announcements by passing its own deletion callback function. Upon an entry
 158  * deletion, all the deletion callback function are called passing the index
 159  * of the deleted entry.
 160  *
 161  * It returns true if the subscription was successful, false otherwise.
 162  */
 163 bool emberAfPluginEsiManagementSubscribeToDeletionAnnouncements(EmberAfEsiManagementDeletionCallback callback);
 164
 165 /**
 166  * Performs the following steps:
 167  *  - Search for the source node of the passed command in the ESI table.
 168  *  - Adds a new entry in the ESI table if the source node is not present in the
 169  *    ESI table yet, or updates the current entry if needed.
 170  *
 171  *  @return The index of the source node of the passed command in the ESI
 172  *  table, or it returns 0xFF if the ESI was not present in the table and a new
 173  *  entry could not be added since the table was full.
 174  **/
 175 uint8_t emberAfPluginEsiManagementUpdateEsiAndGetIndex(const EmberAfClusterCommand * cmd);