doc/linkedlists.txt

   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 }