5 Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
7 Copyright (C) 2000 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
26 /****h* silcutil/SILC Dynamic List Interface
30 * SILC Dynamic List API can be used to add opaque contexts to list that
31 * will automatically allocate list entries. Normal SILC List API cannot
32 * be used for this purpose because in that case the context passed to the
33 * list must be defined as list structure already. This is not the case in
36 * This is slower than SilcList because this requires one extra memory
37 * allocation when adding new entries to the list. The context is probably
38 * allocated already and the new list entry requires one additional memory
39 * allocation. The memory allocation and freeing is done automatically in
40 * the API and does not show to the caller.
44 /****s* silcutil/SilcDListAPI/SilcDList
48 * typedef struct { ... } *SilcDList;
52 * This is the actual SilcDList object that is used by application.
53 * Application defines this object and adds contexts to this list with
54 * Dynamic List Interface functions.
63 /****s* silcutil/SilcDListAPI/SilcDListEntry
67 * typedef struct SilcDListEntryStruct { ... } *SilcDListEntry;
71 * SilcDListEntry structure, one entry in the list. This MUST NOT be used
72 * directly by the application.
76 typedef struct SilcDListEntryStruct {
78 struct SilcDListEntryStruct *next;
82 /****f* silcutil/SilcDListAPI/silc_dlist_init
87 * SilcDList silc_dlist_init();
91 * Initializes SilcDList.
96 SilcDList silc_dlist_init()
100 list = (SilcDList)silc_calloc(1, sizeof(*list));
101 silc_list_init(list->list, struct SilcDListEntryStruct, next);
106 /****f* silcutil/SilcDListAPI/silc_dlist_uninit
111 * void silc_dlist_uninit(SilcDList list);
115 * Uninits and frees all memory. Must be called to free memory. Does NOT
116 * free the contexts saved by caller.
121 void silc_dlist_uninit(SilcDList list)
125 silc_list_start(list->list);
126 while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
127 silc_list_del(list->list, e);
134 /****f* silcutil/SilcDListAPI/silc_dlist_count
139 * int silc_dlist_count(SilcDList list);
143 * Return the number of entries in the list.
148 int silc_dlist_count(SilcDList list)
150 return silc_list_count(list->list);
153 /****f* silcutil/SilcDListAPI/silc_dlist_start
158 * void silc_dlist_start(SilcDList list);
162 * Set the start of the list. This prepares the list for traversing entries
163 * from the start of the list.
168 void silc_dlist_start(SilcDList list)
170 silc_list_start(list->list);
173 /****f* silcutil/SilcDListAPI/silc_dlist_add
178 * void silc_dlist_add(SilcDList list, void *context);
182 * Adds new entry to the list. This is the default function to add new
183 * entries to the list.
188 void silc_dlist_add(SilcDList list, void *context)
190 SilcDListEntry e = (SilcDListEntry)silc_calloc(1, sizeof(*e));
191 e->context = context;
192 silc_list_add(list->list, e);
195 /****f* silcutil/SilcDListAPI/silc_dlist_del
200 * void silc_dlist_del(SilcDList list, void *context);
204 * Remove entry from the list. Returns < 0 on error, 0 otherwise.
209 void silc_dlist_del(SilcDList list, void *context)
213 silc_list_start(list->list);
214 while ((e = (SilcDListEntry)silc_list_get(list->list)) != SILC_LIST_END) {
215 if (e->context == context) {
216 silc_list_del(list->list, e);
223 /****f* silcutil/SilcDListAPI/silc_dlist_get
228 * void *silc_dlist_get(SilcDList list);
232 * Returns current entry from the list and moves the list pointer forward
233 * so that calling this next time returns the next entry from the list.
234 * This can be used to traverse the list. Return SILC_LIST_END when the
235 * entire list has been traversed. Later, silc_list_start must be called
236 * again when re-starting list traversing.
240 * // Traverse the list from the beginning to the end
241 * silc_dlist_start(list)
242 * while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
249 void *silc_dlist_get(SilcDList list)
251 SilcDListEntry e = (SilcDListEntry)silc_list_get(list->list);
252 if (e != SILC_LIST_END)
254 return SILC_LIST_END;