1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 /** 17 * @defgroup list_base Raw bidirectional linked list 18 * @ingroup bsl 19 */ 20 21 #ifndef LIST_BASE_H 22 #define LIST_BASE_H 23 24 #include "hitls_build.h" 25 #ifdef HITLS_BSL_HASH 26 27 #include <stdint.h> 28 #include <stddef.h> 29 #include <stdbool.h> 30 #include "bsl_hash_list.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * @ingroup bsl_base 38 * This struct is used to store the forward pointer and backward pointer of the node in the bidirectional linked list. 39 * This linked list does not contain a substantial data area and is generally used to organize (concatenate) data nodes. 40 */ 41 struct ListTagRawListNode { 42 struct ListTagRawListNode *next; /* points to the next node */ 43 struct ListTagRawListNode *prev; /* points to the previous node */ 44 }; 45 46 /** 47 * @ingroup bsl_base 48 * list node 49 */ 50 typedef struct ListTagRawListNode ListRawNode; 51 52 /** 53 * @ingroup bsl_base 54 * Linked list header, which cannot store data. 55 */ 56 typedef struct { 57 ListRawNode head; /* list node */ 58 /* Node memory release function, which needs to release nodes and other private resources on node */ 59 ListFreeFunc freeFunc; 60 } RawList; 61 62 /** 63 * @ingroup bsl_base 64 * Linked list header, which can apply for data memory and is used by external functions. 65 */ 66 struct BslListSt { 67 RawList rawList; /* Linked list header */ 68 ListDupFreeFuncPair dataFunc; /* used to store data */ 69 }; 70 71 /** 72 * @ingroup bsl_base 73 * Bidirectional linked list node. 74 * This structure is used to store the forward pointer and backward pointer of the nodes in the bidirectional list, 75 * and a small amount of user data or pointers. 76 */ 77 struct BslListNodeSt { 78 ListRawNode rawNode; 79 uintptr_t userdata; 80 }; 81 82 /** 83 * @ingroup bsl_base 84 * @brief Initialize the linked list. 85 * @par Description: Initializes the list, registers the private resource release function in user data as required. 86 * This function does not apply for resources. 87 * @attention 88 * 1: The linked list nodes in the crawlist module are encapsulated and memory is applied for by users. 89 * The rawlist is only used to maintain the linked list, and its resources are released by users in freeFunc. 90 * 2: When a user adds data, the parameter transferred to the rawlist is the ListRawNode node. 91 * Therefore, the parameter transferred to the freeFunc by the rawlist is also the ListRawNode node. 92 * @param list [IN] Linked list. 93 * @param freeFunc [IN] User resource release function. 94 * @retval #BSL_SUCCESS 0. The linked list is successfully initialized. 95 */ 96 int32_t ListRawInit(RawList *list, ListFreeFunc freeFunc); 97 98 /** 99 * @ingroup bsl_base 100 * @brief Clear the node in the linked list and delete all nodes. 101 * @par Description: Clear the linked list node, delete all nodes, 102 * invoke the free function registered by the user to release private resources, 103 * and return to the status after initialization of the linked list. 104 * @param list [IN] Linked list 105 * @retval #BSL_SUCCESS 0. The linked list is cleared successfully. 106 */ 107 int32_t ListRawClear(RawList *list); 108 109 /** 110 * @ingroup bsl_base 111 * @brief Deinitialize the linked list. 112 * @par Description: Deinitialize the linked list: 113 * Delete all nodes, invoke the free function registered by the user to release private resources, 114 * and deregister the hook function. But the list head is still there. 115 * @param list [IN] Linked list 116 * @retval #BSL_SUCCESS 0. The linked list is successfully deinitialized. 117 */ 118 int32_t ListRawDeinit(RawList *list); 119 120 /** 121 * @ingroup bsl_base 122 * @brief Check whether the linked list is empty. 123 * @param list [IN] Linked list to be checked 124 * @retval #true 1. The linked list is empty or has no data. 125 * @retval #false 0. The linked list is not empty. 126 * @li bsl_base.h: header file where the function declaration is located. 127 */ 128 bool ListRawEmpty(const RawList *list); 129 130 /** 131 * @ingroup bsl_base 132 * @brief Obtain the number of nodes in the linked list. 133 * @param list [IN] Linked list 134 * @retval Number of linked list nodes 135 * @li bsl_base.h: header file where the function declaration is located. 136 */ 137 size_t ListRawSize(const RawList *list); 138 139 /** 140 * @ingroup bsl_base 141 * @brief Insert a node at the header of the linked list. 142 * @param list [IN] Linked list 143 * @param node [IN] Node to be inserted 144 * @retval #BSL_SUCCESS 0. Inserted successfully in the header of the linked list. 145 */ 146 int32_t ListRawPushFront(RawList *list, ListRawNode *node); 147 148 /** 149 * @ingroup bsl_base 150 * @brief Insert a node at the end of the linked list. 151 * @param list [IN] Linked list 152 * @param node [IN] Node to be inserted 153 * @retval #BSL_SUCCESS 0. Inserted successfully in the tail of the linked list. 154 */ 155 int32_t ListRawPushBack(RawList *list, ListRawNode *node); 156 157 /** 158 * @ingroup bsl_base 159 * @brief Insert a node before a specified node. 160 * @param curNode [IN] Specified node 161 * @param newNode [IN] Node to be inserted 162 * @retval #BSL_SUCCESS 0 indicates that the linked list is inserted successfully. 163 */ 164 int32_t ListIRawnsert(const ListRawNode *curNode, ListRawNode *newNode); 165 166 /** 167 * @ingroup bsl_base 168 * @brief POP a node from the header of the linked list. 169 * @par Description: Removes the head node from the linked list. 170 * If the free function is registered during initialization, the hook function is also called to release user resources. 171 * If the linked list is empty, nothing will be done. 172 * @param list [IN] Linked list 173 * @retval #BSL_SUCCESS 0. The header of the linked list is popped successfully. 174 */ 175 int32_t ListRawPopFront(RawList *list); 176 177 /** 178 * @ingroup bsl_base 179 * @brief POP a node from the end of the linked list. 180 * @par Description: Remove the tail node from the linked list. 181 * If the free function is registered during initialization, the hook function is also called to release user resources. 182 * If the linked list is empty, nothing will be done. 183 * @param list [IN] Linked list 184 * @retval #BSL_SUCCESS 0. The tail of the linked list is popped successfully. 185 */ 186 int32_t ListRawPopBack(RawList *list); 187 188 /** 189 * @ingroup bsl_base 190 * @brief Delete a specified node from the linked list. 191 * @par Description: 192 * 1. If the list is NULL and the node is in the linked list, only the node is removed from the linked list. 193 * 2. If the list is not null and the node is in the linked list, the node is removed from the linked list. 194 * If the free function is registered during initialization, the hook function is invoked to release user resources. 195 * @param list [IN] Linked list 196 * @param node [IN] Node to be deleted 197 * @retval #BSL_SUCCESS 0. The linked list is deleted successfully. 198 * @li bsl_base.h: header file where the function declaration is located. 199 */ 200 int32_t ListRawRemove(RawList *list, ListRawNode *node); 201 202 /** 203 * @ingroup bsl_base 204 * @brief Return the head node pointer. 205 * @par Description: It is used only to access the head node and will not delete the node. 206 * If the linked list is NULL, NULL is returned. 207 * @param list [IN] Linked list 208 * @attention If the input parameter is incorrect, NULL is returned. The user needs to use the correct parameter. 209 * @retval not NULL Pointer to the head node. 210 * @retval NULL The linked list is NULL. 211 * @li bsl_base.h: header file where the function declaration is located. 212 */ 213 ListRawNode *ListRawFront(const RawList *list); 214 215 /** 216 * @ingroup bsl_base 217 * @brief Return the tail node pointer. 218 * @par Description: It is used only to access the tail node and will not delete the tail node. 219 * If the linked list is NULL, NULL is returned. 220 * @param list [IN] Linked list 221 * @attention If the input parameter is incorrect, NULL is returned. The user needs to use the correct parameter. 222 * @retval not NULL Pointer to the tail node. 223 * @retval NULL The linked list is NULL. 224 * @li bsl_base.h: header file where the function declaration is located. 225 */ 226 ListRawNode *ListRawBack(const RawList *list); 227 228 /** 229 * @ingroup bsl_base 230 * @brief Obtain the previous node of the current node. 231 * @par Description: Obtains the pointer of the previous node of the current node. 232 * If the current node is the head node, NULL is returned. 233 * @param list [IN] Linked list 234 * @param node [IN] Current node 235 * @attention If the input parameter is incorrect, NULL is returned. The user needs to use the correct parameter. 236 * @retval Non-NULL Previous node of the current node 237 * @retval NULL The previous node of the head node is empty. 238 * @li bsl_base.h: header file where the function declaration is located. 239 */ 240 ListRawNode *ListRawGetPrev(const RawList *list, const ListRawNode *node); 241 242 /** 243 * @ingroup bsl_base 244 * @brief Obtain the next node of the current node. 245 * @par Description: Obtains the pointer to the next node of the current node. 246 * If the current node is the tail node, NULL is returned. 247 * @param list [IN] Linked list 248 * @param node [IN] Current node 249 * @attention If the input parameter is incorrect, NULL is returned. The user needs to use the correct parameter. 250 * @retval: non-NULL node next to the current node 251 * @retval: NULL The next node of the tail node is null. 252 * @li bsl_base.h: header file where the function declaration is located. 253 */ 254 ListRawNode *ListRawGetNext(const RawList *list, const ListRawNode *node); 255 256 /** 257 * @ingroup bsl_base 258 * @brief Searches for the desired node based on the node matching function defined by the user. 259 * @par Description: Searches for the desired node based on the node matching function defined by the user. 260 * @attention 261 * 1. Traverse from the header of the linked list and call the matching function for each node in turn 262 * until the first matching node is found or the traversal ends at the tail of the linked list. 263 * 2. Hook of the matching function entered by the user. 264 * Its first input parameter address is the value of each node to be searched. 265 * The input parameter type is ListRawNode *. 266 * 3. For the implementation in the matching hook, 267 * needs to be offset to the user structure information according to the node address before matching and comparison. 268 * 4. If the input parameter is incorrect, NULL is returned. The user needs to use the correct parameter. 269 * @param list [IN] Linked list 270 * @param nodeMatchFunc [IN] hook of match function. 271 * @param data [IN] critical information 272 * @retval non-NULL The query is successful, the node pointer is returned. 273 * @retval NULL Query failed. No matching node is found. 274 * @li bsl_base.h: header file where the function declaration is located. 275 */ 276 ListRawNode *ListRawFindNode(const RawList *list, ListMatchFunc nodeMatchFunc, uintptr_t data); 277 278 /** 279 * @ingroup bsl_base 280 * @brief This API obtains the start address of the structure through a member variable of the structure. 281 * @par Description: 282 * This API obtains the start address of the structure through a member variable of the structure. 283 * This API is a special macro, and the input parameters depend on the implementation of the macro. 284 * @attention 285 * @param ptr [IN] The address of a member on a node. The value range is Data Type. 286 * @param type [IN] The node type structure to which the transferred member belongs. The value range is Data Type. 287 * @param member [IN] The name of a member variable in the structure. The value range is Data Type. 288 * @retval Address of the same structure as the input parameter type. 289 * @see none. 290 */ 291 #define BSL_CONTAINER_OF(ptr, type, member) \ 292 ((type *)((uintptr_t)(ptr) - (uintptr_t)(&(((type *)0)->member)))) 293 294 #ifdef __cplusplus 295 } 296 #endif 297 298 #endif /* HITLS_BSL_HASH */ 299 300 #endif // LIST_BASE_H 301