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
32extern "C" {
33#endif /* __cplusplus */
34
35#include <stdbool.h>
36#include <stdlib.h>
37
38/** Linked List Return Codes */
39typedef 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}linked_list_err_type;
54
55/*===========================================================================
56FUNCTION    linked_list_init
57
58DESCRIPTION
59   Initializes internal structures for linked list.
60
61   list_data: State of list to be initialized.
62
63DEPENDENCIES
64   N/A
65
66RETURN VALUE
67   Look at error codes above.
68
69SIDE EFFECTS
70   N/A
71
72===========================================================================*/
73linked_list_err_type linked_list_init(void** list_data);
74
75/*===========================================================================
76FUNCTION    linked_list_destroy
77
78DESCRIPTION
79   Destroys internal structures for linked list.
80
81   p_list_data: State of list to be destroyed.
82
83DEPENDENCIES
84   N/A
85
86RETURN VALUE
87   Look at error codes above.
88
89SIDE EFFECTS
90   N/A
91
92===========================================================================*/
93linked_list_err_type linked_list_destroy(void** list_data);
94
95/*===========================================================================
96FUNCTION    linked_list_add
97
98DESCRIPTION
99   Adds an element to the head of the linked list. The passed in data pointer
100   is not modified or freed. Passed in data_obj is expected to live throughout
101   the use of the linked_list (i.e. data is not allocated internally)
102
103   p_list_data:  List to add data to the head of.
104   data_obj:     Pointer to data to add into list
105   dealloc:      Function used to deallocate memory for this element. Pass NULL
106                 if you do not want data deallocated during a flush operation
107
108DEPENDENCIES
109   N/A
110
111RETURN VALUE
112   Look at error codes above.
113
114SIDE EFFECTS
115   N/A
116
117===========================================================================*/
118linked_list_err_type linked_list_add(void* list_data, void *data_obj, void (*dealloc)(void*));
119
120/*===========================================================================
121FUNCTION    linked_list_remove
122
123DESCRIPTION
124   Retrieves data from the list tail. data_obj is the tail element from the list
125   passed in by linked_list_add.
126
127   p_list_data:  List to remove the tail from.
128   data_obj:     Pointer to data removed from list
129
130DEPENDENCIES
131   N/A
132
133RETURN VALUE
134   Look at error codes above.
135
136SIDE EFFECTS
137   N/A
138
139===========================================================================*/
140linked_list_err_type linked_list_remove(void* list_data, void **data_obj);
141
142/*===========================================================================
143FUNCTION    linked_list_empty
144
145DESCRIPTION
146   Tells whether the list currently contains any elements
147
148   p_list_data:  List to check if empty.
149
150DEPENDENCIES
151   N/A
152
153RETURN VALUE
154   0/FALSE : List contains elements
155   1/TRUE  : List is Empty
156   Otherwise look at error codes above.
157
158SIDE EFFECTS
159   N/A
160
161===========================================================================*/
162int linked_list_empty(void* list_data);
163
164/*===========================================================================
165FUNCTION    linked_list_flush
166
167DESCRIPTION
168   Removes all elements from the list and deallocates them using the provided
169   dealloc function while adding elements.
170
171   p_list_data:  List to remove all elements from.
172
173DEPENDENCIES
174   N/A
175
176RETURN VALUE
177   Look at error codes above.
178
179SIDE EFFECTS
180   N/A
181
182===========================================================================*/
183linked_list_err_type linked_list_flush(void* list_data);
184
185/*===========================================================================
186FUNCTION    linked_list_search
187
188DESCRIPTION
189   Searches for an element in the linked list.
190
191   p_list_data:  List handle.
192   data_p:       to be stored with the data found; NUll if no match.
193                 if data_p passed in as NULL, then no write to it.
194   equal:        Function ptr takes in a list element, and returns
195                 indication if this the one looking for.
196   data_0:       The data being compared against.
197   rm_if_found:  Should data be removed if found?
198
199DEPENDENCIES
200   N/A
201
202RETURN VALUE
203   Look at error codes above.
204
205SIDE EFFECTS
206   N/A
207
208===========================================================================*/
209linked_list_err_type linked_list_search(void* list_data, void **data_p,
210                                        bool (*equal)(void* data_0, void* data),
211                                        void* data_0, bool rm_if_found);
212
213#ifdef __cplusplus
214}
215#endif /* __cplusplus */
216
217#endif /* __LINKED_LIST_H__ */
218