79663d99931be222a00a0398ff39f19907b7a302
[asterisk/asterisk.git] / addons / ooh323c / src / dlist.h
1 /*
2  * Copyright (C) 1997-2005 by Objective Systems, Inc.
3  *
4  * This software is furnished under an open source license and may be 
5  * used and copied only in accordance with the terms of this license. 
6  * The text of the license may generally be found in the root 
7  * directory of this installation in the COPYING file.  It 
8  * can also be viewed online at the following URL:
9  *
10  *   http://www.obj-sys.com/open/license.html
11  *
12  * Any redistributions of this file including modified versions must 
13  * maintain this copyright notice.
14  *
15  *****************************************************************************/
16 /** 
17  * @file dlist.h 
18  * Doubly-linked list structures and utility functions.
19  */
20 #ifndef _OODLIST_H_
21 #define _OODLIST_H_
22
23 struct OOCTXT;
24
25 /**
26  * @defgroup llfuns Doubly-linked list structures and utility functions.
27  * @{
28  */
29 typedef struct _DListNode {
30    void* data;
31    struct _DListNode* next;
32    struct _DListNode* prev;
33 } DListNode;
34
35 typedef struct _DList {
36    unsigned int count;
37    DListNode* head;
38    DListNode* tail;
39 } DList;
40
41 #define ALLOC_ASN1ELEMDNODE(pctxt,type) \
42 (type*) (((char*)memHeapAllocZ (&(pctxt)->pTypeMemHeap, sizeof(type) + \
43 sizeof(DListNode))) + sizeof(DListNode))
44
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48
49 #ifndef EXTERN
50 #if defined (MAKE_DLL)
51 #define EXTERN __declspec(dllexport)
52 #elif defined (USEASN1DLL)
53 #define EXTERN __declspec(dllimport)
54 #else
55 #define EXTERN
56 #endif /* MAKE_DLL */
57 #endif /* EXTERN */
58
59 /**
60  * This function appends an item to the linked list structure. The data item is
61  * passed into the function as a void pointer that can point to any object of
62  * any type. The memAlloc function is used to allocated the memory for the
63  * list node structure; therefore, all internal list memory will be released
64  * whenever memFree is called. The pointer to the data item itself is stored
65  * in the node structure - a copy is not made.
66  *
67  * @param pctxt        A pointer to a context structure. This provides a
68  *                     storage area for the function to store all working
69  *                     variables that must be maintained between function
70  *                     calls.
71  * @param pList        A pointer to a linked list structure onto which the data
72  *                     item is to be appended. A pointer to an updated linked
73  *                     list structure.
74  * @param pData        A pointer to a data item to be appended to the list.
75  * @return             A pointer to an allocated node structure used to link
76  *                     the given data value into the list.
77  */ 
78 EXTERN DListNode* dListAppend 
79 (struct OOCTXT* pctxt, DList* pList, void* pData);
80
81 EXTERN DListNode* dListAppendNode 
82 (struct OOCTXT* pctxt, DList* pList, void* pData);
83
84 /**
85  * This function delete the head item from the list and returns a pointer 
86  * the data item stored in that node.  The memory for the node structure 
87  * is released.
88  *
89  * @param pctxt        A pointer to a context structure. This provides a
90  *                     storage area for the function to store all working
91  *                     variables that must be maintained between function
92  *                     calls.
93  * @param pList        A pointer to the linked list structure from which 
94  *                     the node will be deleted.
95  * @return             A pointer to the data item stored in the deleted node.
96  */ 
97 EXTERN void* dListDeleteHead (struct OOCTXT* pctxt, DList* pList);
98
99 EXTERN DListNode* dListFindByIndex (DList* pList, int index);
100
101 /**
102  * This function initializes a doubly linked list structure. It sets the number
103  * of elements to zero and sets all internal pointer values to NULL. A doubly
104  * linked-list structure is described by the DList type. Nodes of the list 
105  * are of type DListNode.
106  *
107  * Memory for the structures is allocated using the memAlloc run-time
108  * function and is maintained within the context structure that is a required
109  * parameter to all dList functions. This memory is released when memFree
110  * is called or the Context is released. Unless otherwise noted, all data
111  * passed into the list functions is simply stored on the list by value (i.e. a
112  * deep-copy of the data is not done).
113  *
114  * @param pList        A pointer to a linked list structure to be initialized.
115  */
116 EXTERN void dListInit (DList* pList);
117
118 /**
119  * This function removes all nodes from the linked list and releases the memory
120  * that was allocated for storing the node structures (DListNode). The data
121  * will not be released.
122  *
123  * @param pctxt        A pointer to a context structure. This provides a
124  *                     storage area for the function to store all working
125  *                     variables that must be maintained between function
126  *                     calls.
127  * @param pList        A pointer to a linked list structure onto which the data
128  *                     item is to be appended. A pointer to an updated linked
129  *                     list structure.
130  */
131 EXTERN void dListFreeNodes (struct OOCTXT* pctxt, DList* pList);
132
133 /** 
134  * This function removes all nodes from the linked list structure and releases
135  * the memory that was allocated for storing the node structures
136  * (DListNode) and for data. The memory for data in each node must have
137  * been previously allocated with calls to memAlloc, memAllocZ, or
138  * memRealloc functions.
139  *
140  * @param pctxt        Pointer to a context structure. This provides a
141  *                     storage area for the function to store all working
142  *                     variables that must be maintained between function
143  *                     calls.
144  * @param pList        Pointer to a linked list structure.
145  */
146 EXTERN void dListFreeAll (struct OOCTXT* pctxt, DList* pList);
147
148 /**
149  * This function inserts an item into the linked list structure before the 
150  * specified element.
151  * 
152  * @param pctxt         Pointer to a context structure.
153  * @param pList         A pointer to a linked list structure into which the 
154  *                        data item is to be inserted.
155  * @param node          The position in the list where the item is to be 
156  *                        inserted.  The item will be inserted before this 
157  *                        node or appended to the list if node is null.
158  * @param pData         A pointer to the data item to be inserted to the list.
159  * @return              A pointer to an allocated node structure used to 
160  *                        link the given data value into the list.
161  */
162 EXTERN DListNode* dListInsertBefore 
163 (struct OOCTXT* pctxt, DList* pList, DListNode* node, const void* pData);
164
165 /**
166  * This function inserts an item into the linked list structure after the 
167  * specified element.
168  * 
169  * @param pctxt         Pointer to a context structure.
170  * @param pList         A pointer to a linked list structure into which the 
171  *                        data item is to be inserted.
172  * @param node          The position in the list where the item is to be 
173  *                        inserted.  The item will be inserted after this 
174  *                        node or added as the head element if node is null.
175  * @param pData         A pointer to the data item to be inserted to the list.
176  * @return              A pointer to an allocated node structure used to 
177  *                        link the given data value into the list.
178  */
179 EXTERN DListNode* dListInsertAfter 
180 (struct OOCTXT* pctxt, DList* pList, DListNode* node, const void* pData);
181
182 /**
183  * This function removes a node from the linked list structure. The memAlloc
184  * function was used to allocate the memory for the list node structure,
185  * therefore, all internal list memory will be released whenever memFree or
186  * memFreePtr is called.
187  *
188  * @param pList        A pointer to a linked list structure onto which the data
189  *                     item is to be removed. A pointer to an updated linked
190  *                     list structure.
191  * @param node         A pointer to the node that is to be removed. It should
192  *                     already be in the linked list structure.
193  */
194 EXTERN void  dListRemove (DList* pList, DListNode* node);
195 void dListFindAndRemove(DList* pList, void* data);
196
197 /** 
198  * @}
199  */
200 #ifdef __cplusplus
201 }
202 #endif
203
204 #endif