linked_list.h 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219
  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. #ifdef __cplusplus
  31. extern "C" {
  32. #endif /* __cplusplus */
  33. #include <stdbool.h>
  34. #include <stdlib.h>
  35. /** Linked List Return Codes */
  36. typedef enum
  37. {
  38. eLINKED_LIST_SUCCESS = 0,
  39. /**< Request was successful. */
  40. eLINKED_LIST_FAILURE_GENERAL = -1,
  41. /**< Failed because of a general failure. */
  42. eLINKED_LIST_INVALID_PARAMETER = -2,
  43. /**< Failed because the request contained invalid parameters. */
  44. eLINKED_LIST_INVALID_HANDLE = -3,
  45. /**< Failed because an invalid handle was specified. */
  46. eLINKED_LIST_UNAVAILABLE_RESOURCE = -4,
  47. /**< Failed because an there were not enough resources. */
  48. eLINKED_LIST_INSUFFICIENT_BUFFER = -5,
  49. /**< Failed because an the supplied buffer was too small. */
  50. eLINKED_LIST_EMPTY = -6
  51. /**< Failed because list is empty. */
  52. }linked_list_err_type;
  53. /*===========================================================================
  54. FUNCTION linked_list_init
  55. DESCRIPTION
  56. Initializes internal structures for linked list.
  57. list_data: State of list to be initialized.
  58. DEPENDENCIES
  59. N/A
  60. RETURN VALUE
  61. Look at error codes above.
  62. SIDE EFFECTS
  63. N/A
  64. ===========================================================================*/
  65. linked_list_err_type linked_list_init(void** list_data);
  66. /*===========================================================================
  67. FUNCTION linked_list_destroy
  68. DESCRIPTION
  69. Destroys internal structures for linked list.
  70. p_list_data: State of list to be destroyed.
  71. DEPENDENCIES
  72. N/A
  73. RETURN VALUE
  74. Look at error codes above.
  75. SIDE EFFECTS
  76. N/A
  77. ===========================================================================*/
  78. linked_list_err_type linked_list_destroy(void** list_data);
  79. /*===========================================================================
  80. FUNCTION linked_list_add
  81. DESCRIPTION
  82. Adds an element to the head of the linked list. The passed in data pointer
  83. is not modified or freed. Passed in data_obj is expected to live throughout
  84. the use of the linked_list (i.e. data is not allocated internally)
  85. p_list_data: List to add data to the head of.
  86. data_obj: Pointer to data to add into list
  87. dealloc: Function used to deallocate memory for this element. Pass NULL
  88. if you do not want data deallocated during a flush operation
  89. DEPENDENCIES
  90. N/A
  91. RETURN VALUE
  92. Look at error codes above.
  93. SIDE EFFECTS
  94. N/A
  95. ===========================================================================*/
  96. linked_list_err_type linked_list_add(void* list_data, void *data_obj, void (*dealloc)(void*));
  97. /*===========================================================================
  98. FUNCTION linked_list_remove
  99. DESCRIPTION
  100. Retrieves data from the list tail. data_obj is the tail element from the list
  101. passed in by linked_list_add.
  102. p_list_data: List to remove the tail from.
  103. data_obj: Pointer to data removed from list
  104. DEPENDENCIES
  105. N/A
  106. RETURN VALUE
  107. Look at error codes above.
  108. SIDE EFFECTS
  109. N/A
  110. ===========================================================================*/
  111. linked_list_err_type linked_list_remove(void* list_data, void **data_obj);
  112. /*===========================================================================
  113. FUNCTION linked_list_empty
  114. DESCRIPTION
  115. Tells whether the list currently contains any elements
  116. p_list_data: List to check if empty.
  117. DEPENDENCIES
  118. N/A
  119. RETURN VALUE
  120. 0/FALSE : List contains elements
  121. 1/TRUE : List is Empty
  122. Otherwise look at error codes above.
  123. SIDE EFFECTS
  124. N/A
  125. ===========================================================================*/
  126. int linked_list_empty(void* list_data);
  127. /*===========================================================================
  128. FUNCTION linked_list_flush
  129. DESCRIPTION
  130. Removes all elements from the list and deallocates them using the provided
  131. dealloc function while adding elements.
  132. p_list_data: List to remove all elements from.
  133. DEPENDENCIES
  134. N/A
  135. RETURN VALUE
  136. Look at error codes above.
  137. SIDE EFFECTS
  138. N/A
  139. ===========================================================================*/
  140. linked_list_err_type linked_list_flush(void* list_data);
  141. /*===========================================================================
  142. FUNCTION linked_list_search
  143. DESCRIPTION
  144. Searches for an element in the linked list.
  145. p_list_data: List handle.
  146. data_p: to be stored with the data found; NUll if no match.
  147. if data_p passed in as NULL, then no write to it.
  148. equal: Function ptr takes in a list element, and returns
  149. indication if this the one looking for.
  150. data_0: The data being compared against.
  151. rm_if_found: Should data be removed if found?
  152. DEPENDENCIES
  153. N/A
  154. RETURN VALUE
  155. Look at error codes above.
  156. SIDE EFFECTS
  157. N/A
  158. ===========================================================================*/
  159. linked_list_err_type linked_list_search(void* list_data, void **data_p,
  160. bool (*equal)(void* data_0, void* data),
  161. void* data_0, bool rm_if_found);
  162. #ifdef __cplusplus
  163. }
  164. #endif /* __cplusplus */
  165. #endif /* __LINKED_LIST_H__ */