Merge anthm's monitor fixes (better default path, set variable for monitor) (bug...
[asterisk/asterisk.git] / doc / linkedlists.README
1 As of 2004-12-23, this documentation is no longer maintained. The doxygen documentation
2 generated from linkedlists.h should be referred to in its place, as it is more complete
3 and better maintained.
4
5 2nd version, implemented as macros.
6
7         include <asterisk/linkedlists.h>
8
9 AST_LIST_ENTRY declares pointers inside the object structure : 
10
11         struct ast_var_t {
12                 char *name;
13                 char *value;
14                 AST_LIST_ENTRY(ast_var_t) listpointers;
15         };
16
17 AST_LIST_HEAD declares a head structure, which is initialized
18 to AST_LIST_HEAD_NULL : 
19
20         AST_LIST_HEAD(head, ast_var_t) head 
21
22 Next, we declare a pointer to this structure : 
23
24         struct headtype *headp = head;
25
26 AST_LIST_INIT initializes the head pointer to a null value
27
28         AST_LIST_INIT(headp);
29
30 AST_LIST_INSERT_HEAD inserts an element to the head of the list : 
31
32         struct ast_var_t *node; 
33
34         node=malloc(sizeof(struct ast_var_t));
35         (...we fill data in struct....)
36         data->name=malloc(100);
37         strcpy(data->name,"lalalalaa");
38         etc etc
39
40         (then we insert the node in the head of the list :)
41
42         AST_LIST_INSERT_HEAD(headp,node,listpointers);
43
44 AST_LIST_INSERT_HEAD_AFTER inserts an element after another : 
45
46         struct ast_var_t *node1;
47         ...
48         AST_LIST_INSERT_AFTER(node,node1,listpointers);
49
50 AST_LIST_REMOVE removes an arbitrary element from the head:
51
52         AST_LIST_REMOVE(headp,node1,ast_var_t,listpointers);
53
54 AST_LIST_REMOVE_HEAD removes the entry at the head of the list and
55 returns a pointer to the removed entry: 
56
57         AST_LIST_REMOVE_HEAD(headp,node,listpointers);
58
59 AST_LIST_FIRST returns a pointer to the first element of the list;
60
61         struct ast_var_t *firstnode;
62         firstnode=AST_LIST_FIRST(headp);
63
64 AST_LIST_NEXT returns a pointer to the next element : 
65
66         struct ast_var_t *nextnode;
67         nextnode=AST_LIST_NEXT(firstnode,listpointers);
68
69 AST_LIST_TRAVERSE traverses all elements of the list : 
70
71         struct ast_var_t *node;
72
73         AST_LIST_TRAVERSE(headp,node,listpointers) {
74                 printf("%s\n",node->name);
75         }
76
77 AST_LIST_EMPTY evaluates to a true condition if there are no elements on 
78 the list. 
79
80 To completely delete a list : 
81
82         struct ast_var_t *vardata;
83
84         while (!AST_LIST_EMPTY(headp)) {           /* List Deletion. */
85                     vardata = AST_LIST_REMOVE_HEAD(head, ast_var_t, listpointers);
86                     free(vardata->name);
87                     free(vardata->value);
88         }
89
90 AST_LIST_LOCK returns true if it can lock the list, AST_LIST_UNLOCK unlocks
91 the list : 
92
93 if (AST_LIST_LOCK(headp)) {
94         ...do all list operations here...
95         AST_LIST_UNLOCK(headp);
96 } else {
97         ast_log(LOG_WARNING,"List locked bla bla bla\n");
98 }