1 /* Copyright (c) 2011, The Linux Foundation. All rights reserved. 2 * 3 * Redistribution and use in source and binary forms, with or without 4 * modification, are permitted provided that the following conditions are 5 * met: 6 * * Redistributions of source code must retain the above copyright 7 * notice, this list of conditions and the following disclaimer. 8 * * Redistributions in binary form must reproduce the above 9 * copyright notice, this list of conditions and the following 10 * disclaimer in the documentation and/or other materials provided 11 * with the distribution. 12 * * Neither the name of The Linux Foundation nor the names of its 13 * contributors may be used to endorse or promote products derived 14 * from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 20 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 26 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 */ 28 #ifndef __LINKED_LIST_H__ 29 #define __LINKED_LIST_H__ 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif /* __cplusplus */ 34 35 #include <stdbool.h> 36 #include <stdlib.h> 37 38 /** Linked List Return Codes */ 39 typedef enum 40 { 41 eLINKED_LIST_SUCCESS = 0, 42 /**< Request was successful. */ 43 eLINKED_LIST_FAILURE_GENERAL = -1, 44 /**< Failed because of a general failure. */ 45 eLINKED_LIST_INVALID_PARAMETER = -2, 46 /**< Failed because the request contained invalid parameters. */ 47 eLINKED_LIST_INVALID_HANDLE = -3, 48 /**< Failed because an invalid handle was specified. */ 49 eLINKED_LIST_UNAVAILABLE_RESOURCE = -4, 50 /**< Failed because an there were not enough resources. */ 51 eLINKED_LIST_INSUFFICIENT_BUFFER = -5, 52 /**< Failed because an the supplied buffer was too small. */ 53 eLINKED_LIST_EMPTY = -6 54 /**< Failed because list is empty. */ 55 }linked_list_err_type; 56 57 /*=========================================================================== 58 FUNCTION linked_list_init 59 60 DESCRIPTION 61 Initializes internal structures for linked list. 62 63 list_data: State of list to be initialized. 64 65 DEPENDENCIES 66 N/A 67 68 RETURN VALUE 69 Look at error codes above. 70 71 SIDE EFFECTS 72 N/A 73 74 ===========================================================================*/ 75 linked_list_err_type linked_list_init(void** list_data); 76 77 /*=========================================================================== 78 FUNCTION linked_list_destroy 79 80 DESCRIPTION 81 Destroys internal structures for linked list. 82 83 p_list_data: State of list to be destroyed. 84 85 DEPENDENCIES 86 N/A 87 88 RETURN VALUE 89 Look at error codes above. 90 91 SIDE EFFECTS 92 N/A 93 94 ===========================================================================*/ 95 linked_list_err_type linked_list_destroy(void** list_data); 96 97 /*=========================================================================== 98 FUNCTION linked_list_add 99 100 DESCRIPTION 101 Adds an element to the head of the linked list. The passed in data pointer 102 is not modified or freed. Passed in data_obj is expected to live throughout 103 the use of the linked_list (i.e. data is not allocated internally) 104 105 p_list_data: List to add data to the head of. 106 data_obj: Pointer to data to add into list 107 dealloc: Function used to deallocate memory for this element. Pass NULL 108 if you do not want data deallocated during a flush operation 109 110 DEPENDENCIES 111 N/A 112 113 RETURN VALUE 114 Look at error codes above. 115 116 SIDE EFFECTS 117 N/A 118 119 ===========================================================================*/ 120 linked_list_err_type linked_list_add(void* list_data, void *data_obj, void (*dealloc)(void*)); 121 122 /*=========================================================================== 123 FUNCTION linked_list_remove 124 125 DESCRIPTION 126 Retrieves data from the list tail. data_obj is the tail element from the list 127 passed in by linked_list_add. 128 129 p_list_data: List to remove the tail from. 130 data_obj: Pointer to data removed from list 131 132 DEPENDENCIES 133 N/A 134 135 RETURN VALUE 136 Look at error codes above. 137 138 SIDE EFFECTS 139 N/A 140 141 ===========================================================================*/ 142 linked_list_err_type linked_list_remove(void* list_data, void **data_obj); 143 144 /*=========================================================================== 145 FUNCTION linked_list_empty 146 147 DESCRIPTION 148 Tells whether the list currently contains any elements 149 150 p_list_data: List to check if empty. 151 152 DEPENDENCIES 153 N/A 154 155 RETURN VALUE 156 0/FALSE : List contains elements 157 1/TRUE : List is Empty 158 Otherwise look at error codes above. 159 160 SIDE EFFECTS 161 N/A 162 163 ===========================================================================*/ 164 int linked_list_empty(void* list_data); 165 166 /*=========================================================================== 167 FUNCTION linked_list_flush 168 169 DESCRIPTION 170 Removes all elements from the list and deallocates them using the provided 171 dealloc function while adding elements. 172 173 p_list_data: List to remove all elements from. 174 175 DEPENDENCIES 176 N/A 177 178 RETURN VALUE 179 Look at error codes above. 180 181 SIDE EFFECTS 182 N/A 183 184 ===========================================================================*/ 185 linked_list_err_type linked_list_flush(void* list_data); 186 187 /*=========================================================================== 188 FUNCTION linked_list_search 189 190 DESCRIPTION 191 Searches for an element in the linked list. 192 193 p_list_data: List handle. 194 data_p: to be stored with the data found; NUll if no match. 195 if data_p passed in as NULL, then no write to it. 196 equal: Function ptr takes in a list element, and returns 197 indication if this the one looking for. 198 data_0: The data being compared against. 199 rm_if_found: Should data be removed if found? 200 201 DEPENDENCIES 202 N/A 203 204 RETURN VALUE 205 Look at error codes above. 206 207 SIDE EFFECTS 208 N/A 209 210 ===========================================================================*/ 211 linked_list_err_type linked_list_search(void* list_data, void **data_p, 212 bool (*equal)(void* data_0, void* data), 213 void* data_0, bool rm_if_found); 214 215 #ifdef __cplusplus 216 } 217 #endif /* __cplusplus */ 218 219 #endif /* __LINKED_LIST_H__ */ 220