From: Pekka Riikonen Date: Sat, 19 Oct 2002 11:33:42 +0000 (+0000) Subject: ROBODoc documented. Patch by Ville Räsänen. X-Git-Tag: silc.client.0.9.7~13 X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=commitdiff_plain;h=ed68d9851468f6d64cef0354edaae09e4b690455 ROBODoc documented. Patch by Ville Räsänen. --- diff --git a/CHANGES b/CHANGES index ce6d0da9..4b4dec21 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,9 @@ +Sat Oct 19 13:32:15 CEST 2002 Pekka Riikonen + + * ROBODoc documented lib/silcutil/silcbuffer.h and + lib/silcutil/silcdlist.h. Patch by Ville Räsänen + . + Fri Oct 18 10:51:04 EEST 2002 Pekka Riikonen * Added support for auto-passphrase authentication from the diff --git a/TODO b/TODO index 3adaf961..b9dac745 100644 --- a/TODO +++ b/TODO @@ -54,10 +54,6 @@ TODO in Toolkit Documentation Stuff that needs to be done in order to complete the Tooolkit Reference Manual (Do these to 0.9.x). - o ROBOdoc documenting missing from lib/silcutil/silcbuffer.h. - - o ROBOdoc documenting missing from lib/silcutil/silcdlist.h. - o ROBOdoc documenting missing from lib/silccrypt/silccipher.h. o ROBOdoc documenting missing from lib/silccrypt/silcpkcs.h. diff --git a/lib/silcutil/silcbuffer.h b/lib/silcutil/silcbuffer.h index e0214337..6aa197fd 100644 --- a/lib/silcutil/silcbuffer.h +++ b/lib/silcutil/silcbuffer.h @@ -22,94 +22,109 @@ #ifndef SILCBUFFER_H #define SILCBUFFER_H -/* - SILC Buffer object. - - SilcBuffer is very simple and easy to use, yet you can do to the - buffer almost anything you want with its method functions. The buffer - is constructed of four different data sections that in whole creates - the allocated data area. Following short description of the fields - of the buffer. - - SilcUInt32 truelen; - - True length of the buffer. This is set at the allocation of the - buffer and it should not be touched after that. This field should - be considered read-only. - - SilcUInt32 len; - - Length of the currently valid data area. Tells the length of the - data at the buffer. This is set to zero at the allocation of the - buffer and should not be updated by hand. Method functions of the - buffer automatically updates this field. However, it is not - read-only field and can be updated manually if necessary. - - unsiged char *head; - - Head of the allocated buffer. This is the start of the allocated - data area and remains as same throughout the lifetime of the buffer. - However, the end of the head area or the start of the currently valid - data area is variable. - - -------------------------------- - | head | data | tail | - -------------------------------- - ^ ^ - - Current head section in the buffer is sb->data - sb->head. - - unsigned char *data; - - Currently valid data area. This is the start of the currently valid - main data area. The data area is variable in all directions. - - -------------------------------- - | head | data | tail | - -------------------------------- - ^ ^ - - Current valid data area in the buffer is sb->tail - sb->data. - - unsigned char *tail; - - Tail of the buffer. This is the end of the currently valid data area - or start of the tail area. The start of the tail area is variable. - - -------------------------------- - | head | data | tail | - -------------------------------- - ^ ^ - - Current tail section in the buffer is sb->end - sb->tail. - - unsigned char *end; - - End of the allocated buffer. This is the end of the allocated data - area and remains as same throughout the lifetime of the buffer. - Usually this field is not needed except when checking the size - of the buffer. - - -------------------------------- - | head | data | tail | - -------------------------------- - ^ - - Length of the entire buffer is (ie. truelen) sb->end - sb->head. - - Currently valid data area is considered to be the main data area in - the buffer. However, the entire buffer is of course valid data and can - be used as such. Usually head section of the buffer includes different - kind of headers or similar. Data section includes the main data of - the buffer. Tail section can be seen as a reserve space of the data - section. Tail section can be pulled towards end thus the data section - becomes larger. - - This buffer scheme is based on Linux kernel's Socket Buffer, the - idea were taken directly from there and credits should go there. - -*/ - +/****h* silcutil/SILC Buffer Interface + * + * DESCRIPTION + * + * SilcBuffer is very simple and easy to use, yet you can do to the + * buffer almost anything you want with its method functions. The buffer + * is constructed of four different data sections that in whole creates + * the allocated data area. + * + * This buffer scheme is based on Linux kernel's Socket Buffer, the + * idea were taken directly from there and credits should go there. + * + ***/ + +/****s* silcutil/SilcBufferAPI/SilcBuffer + * + * NAME + * + * typedef struct { ... } *SilcBuffer, SilcBufferStruct; + * + * DESCRIPTION + * + * SILC Buffer object. Following short description of the fields + * of the buffer. + * + * EXAMPLE + * + * SilcUInt32 truelen; + * + * True length of the buffer. This is set at the allocation of the + * buffer and it should not be touched after that. This field should + * be considered read-only. + * + * SilcUInt32 len; + * + * Length of the currently valid data area. Tells the length of the + * data at the buffer. This is set to zero at the allocation of the + * buffer and should not be updated by hand. Method functions of the + * buffer automatically updates this field. However, it is not + * read-only field and can be updated manually if necessary. + * + * unsiged char *head; + * + * Head of the allocated buffer. This is the start of the allocated + * data area and remains as same throughout the lifetime of the buffer. + * However, the end of the head area or the start of the currently valid + * data area is variable. + * + * -------------------------------- + * | head | data | tail | + * -------------------------------- + * ^ ^ + * + * Current head section in the buffer is sb->data - sb->head. + * + * unsigned char *data; + * + * Currently valid data area. This is the start of the currently valid + * main data area. The data area is variable in all directions. + * + * -------------------------------- + * | head | data | tail | + * -------------------------------- + * ^ ^ + * + * Current valid data area in the buffer is sb->tail - sb->data. + * + * unsigned char *tail; + * + * Tail of the buffer. This is the end of the currently valid data area + * or start of the tail area. The start of the tail area is variable. + * + * -------------------------------- + * | head | data | tail | + * -------------------------------- + * ^ ^ + * + * Current tail section in the buffer is sb->end - sb->tail. + * + * unsigned char *end; + * + * End of the allocated buffer. This is the end of the allocated data + * area and remains as same throughout the lifetime of the buffer. + * Usually this field is not needed except when checking the size + * of the buffer. + * + * -------------------------------- + * | head | data | tail | + * -------------------------------- + * ^ + * + * Length of the entire buffer is (ie. truelen) sb->end - sb->head. + * + * Currently valid data area is considered to be the main data area in + * the buffer. However, the entire buffer is of course valid data and can + * be used as such. Usually head section of the buffer includes different + * kind of headers or similar. Data section includes the main data of + * the buffer. Tail section can be seen as a reserve space of the data + * section. Tail section can be pulled towards end, and thus the data + * section becomes larger. + * + * SOURCE + */ typedef struct { SilcUInt32 truelen; SilcUInt32 len; @@ -118,15 +133,41 @@ typedef struct { unsigned char *tail; unsigned char *end; } *SilcBuffer, SilcBufferStruct; +/***/ /* Macros */ -/* Returns the true length of the buffer. This is used to pull - the buffer area to the end of the buffer. */ +/****d* silcutil/SilcBufferAPI/SILC_BUFFER_END + * + * NAME + * + * #define SILC_BUFFER_END(...) + * + * DESCRIPTION + * + * Returns the true length of the buffer. This is used to pull + * the buffer area to the end of the buffer. + * + * SOURCE + */ #define SILC_BUFFER_END(x) ((x)->end - (x)->head) +/***/ /* Inline functions */ +/****f* silcutil/SilcBufferAPI/silc_buffer_alloc + * + * SYNOPSIS + * + * static inline + * SilcBuffer silc_buffer_alloc(SilcUInt32 len); + * + * DESCRIPTION + * + * Allocates new SilcBuffer and returns it. + * + ***/ + static inline SilcBuffer silc_buffer_alloc(SilcUInt32 len) { @@ -151,7 +192,18 @@ SilcBuffer silc_buffer_alloc(SilcUInt32 len) return sb; } -/* Free's a SilcBuffer */ +/****f* silcutil/SilcBufferAPI/silc_buffer_free + * + * SYNOPSIS + * + * static inline + * void silc_buffer_free(SilcBuffer sb); + * + * DESCRIPTION + * + * Frees SilcBuffer. + * + ***/ static inline void silc_buffer_free(SilcBuffer sb) @@ -165,10 +217,23 @@ void silc_buffer_free(SilcBuffer sb) } } -/* Sets the `data' and `data_len' to the buffer pointer sent as argument. - The data area is automatically set to the `data_len'. This function - can be used to set the data to static buffer without needing any - memory allocations. The `data' will not be copied to the buffer. */ +/****f* silcutil/SilcBufferAPI/silc_buffer_set + * + * SYNOPSIS + * + * static inline + * void silc_buffer_set(SilcBuffer sb, + * unsigned char *data, + * SilcUInt32 data_len); + * + * DESCRIPTION + * + * Sets the `data' and `data_len' to the buffer pointer sent as argument. + * The data area is automatically set to the `data_len'. This function + * can be used to set the data to static buffer without needing any + * memory allocations. The `data' will not be copied to the buffer. + * + ***/ static inline void silc_buffer_set(SilcBuffer sb, unsigned char *data, SilcUInt32 data_len) @@ -178,24 +243,34 @@ void silc_buffer_set(SilcBuffer sb, unsigned char *data, SilcUInt32 data_len) sb->len = sb->truelen = data_len; } -/* Pulls current data area towards end. The length of the currently - valid data area is also decremented. Returns pointer to the data - area before pulling. - - Example: - --------------------------------- - | head | data | tail | - --------------------------------- - ^ - Pulls the start of the data area. - - --------------------------------- - | head | data | tail | - --------------------------------- - ^ -*/ +/****f* silcutil/SilcBufferAPI/silc_buffer_pull + * + * SYNOPSIS + * + * static inline + * unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len); + * + * DESCRIPTION + * + * Pulls current data area towards end. The length of the currently + * valid data area is also decremented. Returns pointer to the data + * area before pulling. + * + * EXAMPLE + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * Pulls the start of the data area. + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + ***/ -static inline +static inline unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len) { unsigned char *old_data = sb->data; @@ -210,24 +285,35 @@ unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len) return old_data; } -/* Pushes current data area towards beginning. Length of the currently - valid data area is also incremented. Returns a pointer to the - data area before pushing. - - Example: - --------------------------------- - | head | data | tail | - --------------------------------- - ^ - Pushes the start of the data area. - - --------------------------------- - | head | data | tail | - --------------------------------- - ^ -*/ +/****f* silcutil/SilcBufferAPI/silc_buffer_push + * + * SYNOPSIS + * + * static inline + * unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len); + * + * DESCRIPTION + * + * Pushes current data area towards beginning. Length of the currently + * valid data area is also incremented. Returns a pointer to the + * data area before pushing. + * + * EXAMPLE + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * Pushes the start of the data area. + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * + ***/ -static inline +static inline unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len) { unsigned char *old_data = sb->data; @@ -242,24 +328,35 @@ unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len) return old_data; } -/* Pulls current tail section towards end. Length of the current valid - data area is also incremented. Returns a pointer to the data area - before pulling. - - Example: - --------------------------------- - | head | data | tail | - --------------------------------- - ^ - Pulls the start of the tail section. - - --------------------------------- - | head | data | tail | - --------------------------------- - ^ -*/ +/****f* silcutil/SilcBufferAPI/silc_buffer_pull_tail + * + * SYNOPSIS + * + * static inline + * unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len); + * + * DESCRIPTION + * + * Pulls current tail section towards end. Length of the current valid + * data area is also incremented. Returns a pointer to the data area + * before pulling. + * + * EXAMPLE + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * Pulls the start of the tail section. + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * + ***/ -static inline +static inline unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len) { unsigned char *old_tail = sb->tail; @@ -274,22 +371,33 @@ unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len) return old_tail; } -/* Pushes current tail section towards beginning. Length of the current - valid data area is also decremented. Returns a pointer to the - tail section before pushing. - - Example: - --------------------------------- - | head | data | tail | - --------------------------------- - ^ - Pushes the start of the tail section. - - --------------------------------- - | head | data | tail | - --------------------------------- - ^ -*/ +/****f* silcutil/SilcBufferAPI/silc_buffer_push_tail + * + * SYNOPSIS + * + * static inline + * unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len); + * + * DESCRIPTION + * + * Pushes current tail section towards beginning. Length of the current + * valid data area is also decremented. Returns a pointer to the + * tail section before pushing. + * + * EXAMPLE + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * Pushes the start of the tail section. + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * + ***/ static inline unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len) @@ -306,19 +414,32 @@ unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len) return old_tail; } -/* Puts data at the head of the buffer. Returns pointer to the copied - data area. - - Example: - --------------------------------- - | head | data | tail | - --------------------------------- - ^ - Puts data to the head section. -*/ +/****f* silcutil/SilcBufferAPI/silc_buffer_put_head + * + * SYNOPSIS + * + * static inline + * unsigned char *silc_buffer_put_head(SilcBuffer sb, + * const unsigned char *data, + * SilcUInt32 len); + * + * DESCRIPTION + * + * Puts data at the head of the buffer. Returns pointer to the copied + * data area. + * + * EXAMPLE + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * Puts data to the head section. + * + ***/ static inline -unsigned char *silc_buffer_put_head(SilcBuffer sb, +unsigned char *silc_buffer_put_head(SilcBuffer sb, const unsigned char *data, SilcUInt32 len) { @@ -328,19 +449,32 @@ unsigned char *silc_buffer_put_head(SilcBuffer sb, return (unsigned char *)memcpy(sb->head, data, len); } -/* Puts data at the start of the valid data area. Returns a pointer - to the copied data area. - - Example: - --------------------------------- - | head | data | tail | - --------------------------------- - ^ - Puts data to the data section. -*/ +/****f* silcutil/SilcBufferAPI/silc_buffer_put + * + * SYNOPSIS + * + * static inline + * unsigned char *silc_buffer_put(SilcBuffer sb, + * const unsigned char *data, + * SilcUInt32 len); + * + * DESCRIPTION + * + * Puts data at the start of the valid data area. Returns a pointer + * to the copied data area. + * + * EXAMPLE + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * Puts data to the data section. + * + ***/ static inline -unsigned char *silc_buffer_put(SilcBuffer sb, +unsigned char *silc_buffer_put(SilcBuffer sb, const unsigned char *data, SilcUInt32 len) { @@ -350,19 +484,32 @@ unsigned char *silc_buffer_put(SilcBuffer sb, return (unsigned char *)memcpy(sb->data, data, len); } -/* Puts data at the tail of the buffer. Returns pointer to the copied - data area. - - Example: - --------------------------------- - | head | data | tail | - --------------------------------- - ^ - Puts data to the tail section. -*/ +/****f* silcutil/SilcBufferAPI/silc_buffer_put_tail + * + * SYNOPSIS + * + * static inline + * unsigned char *silc_buffer_put_tail(SilcBuffer sb, + * const unsigned char *data, + * SilcUInt32 len); + * + * DESCRIPTION + * + * Puts data at the tail of the buffer. Returns pointer to the copied + * data area. + * + * EXAMPLE + * + * --------------------------------- + * | head | data | tail | + * --------------------------------- + * ^ + * Puts data to the tail section. + * + ***/ static inline -unsigned char *silc_buffer_put_tail(SilcBuffer sb, +unsigned char *silc_buffer_put_tail(SilcBuffer sb, const unsigned char *data, SilcUInt32 len) { @@ -372,9 +519,20 @@ unsigned char *silc_buffer_put_tail(SilcBuffer sb, return (unsigned char *)memcpy(sb->tail, data, len); } -/* Allocates `len' bytes size buffer and moves the tail area automaticlly - `len' bytes so that the buffer is ready to use without calling the - silc_buffer_pull_tail. */ +/****f* silcutil/SilcBufferAPI/silc_buffer_alloc_size + * + * SYNOPSIS + * + * static inline + * SilcBuffer silc_buffer_alloc_size(SilcUInt32 len); + * + * DESCRIPTION + * + * Allocates `len' bytes size buffer and moves the tail area automatically + * `len' bytes so that the buffer is ready to use without calling the + * silc_buffer_pull_tail. + * + ***/ static inline SilcBuffer silc_buffer_alloc_size(SilcUInt32 len) @@ -386,8 +544,19 @@ SilcBuffer silc_buffer_alloc_size(SilcUInt32 len) return sb; } -/* Clears and initialiazes the buffer to the state as if it was just - allocated by silc_buffer_alloc. */ +/****f* silcutil/SilcBufferAPI/silc_buffer_clear + * + * SYNOPSIS + * + * static inline + * void silc_buffer_clear(SilcBuffer sb); + * + * DESCRIPTION + * + * Clears and initialiazes the buffer to the state as if it was just + * allocated by silc_buffer_alloc. + * + ***/ static inline void silc_buffer_clear(SilcBuffer sb) @@ -398,9 +567,20 @@ void silc_buffer_clear(SilcBuffer sb) sb->len = 0; } -/* Generates copy of a SilcBuffer. This copies everything inside the - currently valid data area, nothing more. Use silc_buffer_clone to - copy entire buffer. */ +/****f* silcutil/SilcBufferAPI/silc_buffer_copy + * + * SYNOPSIS + * + * static inline + * SilcBuffer silc_buffer_copy(SilcBuffer sb); + * + * DESCRIPTION + * + * Generates copy of a SilcBuffer. This copies everything inside the + * currently valid data area, nothing more. Use silc_buffer_clone to + * copy entire buffer. + * + ***/ static inline SilcBuffer silc_buffer_copy(SilcBuffer sb) @@ -415,9 +595,20 @@ SilcBuffer silc_buffer_copy(SilcBuffer sb) return sb_new; } -/* Clones SilcBuffer. This generates new SilcBuffer and copies - everything from the source buffer. The result is exact clone of - the original buffer. */ +/****f* silcutil/SilcBufferAPI/silc_buffer_clone + * + * SYNOPSIS + * + * static inline + * SilcBuffer silc_buffer_clone(SilcBuffer sb); + * + * DESCRIPTION + * + * Clones SilcBuffer. This generates new SilcBuffer and copies + * everything from the source buffer. The result is exact clone of + * the original buffer. + * + ***/ static inline SilcBuffer silc_buffer_clone(SilcBuffer sb) @@ -435,9 +626,20 @@ SilcBuffer silc_buffer_clone(SilcBuffer sb) return sb_new; } -/* Reallocates buffer. Old data is saved into the new buffer. Returns - new SilcBuffer pointer. The buffer is exact clone of the old one - except that there is now more space at the end of buffer. */ +/****f* silcutil/SilcBufferAPI/silc_buffer_realloc + * + * SYNOPSIS + * + * static inline + * SilcBuffer silc_buffer_realloc(SilcBuffer sb, SilcUInt32 newsize); + * + * DESCRIPTION + * + * Reallocates buffer. Old data is saved into the new buffer. Returns + * new SilcBuffer pointer. The buffer is exact clone of the old one + * except that there is now more space at the end of buffer. + * + ***/ static inline SilcBuffer silc_buffer_realloc(SilcBuffer sb, SilcUInt32 newsize) diff --git a/lib/silcutil/silcdlist.h b/lib/silcutil/silcdlist.h index 8ea683b8..2457ab89 100644 --- a/lib/silcutil/silcdlist.h +++ b/lib/silcutil/silcdlist.h @@ -22,37 +22,75 @@ #define SILDCLIST_H #include "silclist.h" + +/****h* silcutil/SILC Dynamic List Interface + * + * DESCRIPTION + * + * SILC Dynamic List API can be used to add opaque contexts to list that + * will automatically allocate list entries. Normal SILC List API cannot + * be used for this purpose because in that case the context passed to the + * list must be defined as list structure already. This is not the case in + * SilcDList. + * + * This is slower than SilcList because this requires one extra memory + * allocation when adding new entries to the list. The context is probably + * allocated already and the new list entry requires one additional memory + * allocation. The memory allocation and freeing is done automatically in + * the API and does not show to the caller. + * + ***/ -/* - SILC Dynamic List API - - SILC Dynamic List API can be used to add opaque contexts to list that will - automatically allocate list entries. Normal SILC List API cannot be used - for this purpose because in that case the context passed to the list must - be defined as list structure already. This is not the case in SilcDList. - - This is slower than SilcList because this requires one extra memory - allocation when adding new entries to the list. The context is probably - allocated already and the new list entry requires one additional memory - allocation. The memory allocation and free'ing is done automatically in - the API and does not show to the caller. -*/ - -/* SilcDList object. This is the actual SilcDList object that is used by - application. Application defines this object and adds context's to this - list with functions defined below. */ +/****s* silcutil/SilcDListAPI/SilcDList + * + * NAME + * + * typedef struct { ... } *SilcDList; + * + * DESCRIPTION + * + * This is the actual SilcDList object that is used by application. + * Application defines this object and adds contexts to this list with + * Dynamic List Interface functions. + * + * SOURCE + */ typedef struct { SilcList list; } *SilcDList; +/***/ -/* SilcDListEntry structure, one entry in the list. This MUST NOT be used - directly by the application. */ +/****s* silcutil/SilcDListAPI/SilcDListEntry + * + * NAME + * + * typedef struct SilcDListEntryStruct { ... } *SilcDListEntry; + * + * DESCRIPTION + * + * SilcDListEntry structure, one entry in the list. This MUST NOT be used + * directly by the application. + * + * SOURCE + */ typedef struct SilcDListEntryStruct { void *context; struct SilcDListEntryStruct *next; } *SilcDListEntry; +/***/ -/* Initializes SilcDList. */ +/****f* silcutil/SilcDListAPI/silc_dlist_init + * + * SYNOPSIS + * + * static inline + * SilcDList silc_dlist_init(); + * + * DESCRIPTION + * + * Initializes SilcDList. + * + ***/ static inline SilcDList silc_dlist_init() @@ -65,8 +103,19 @@ SilcDList silc_dlist_init() return list; } -/* Uninits and free's all memory. Must be called to free memory. Does NOT - free the contexts saved by caller. */ +/****f* silcutil/SilcDListAPI/silc_dlist_uninit + * + * SYNOPSIS + * + * static inline + * void silc_dlist_uninit(SilcDList list); + * + * DESCRIPTION + * + * Uninits and frees all memory. Must be called to free memory. Does NOT + * free the contexts saved by caller. + * + ***/ static inline void silc_dlist_uninit(SilcDList list) @@ -82,7 +131,18 @@ void silc_dlist_uninit(SilcDList list) } } -/* Return the number of entries in the list */ +/****f* silcutil/SilcDListAPI/silc_dlist_count + * + * SYNOPSIS + * + * static inline + * int silc_dlist_count(SilcDList list); + * + * DESCRIPTION + * + * Return the number of entries in the list. + * + ***/ static inline int silc_dlist_count(SilcDList list) @@ -90,8 +150,19 @@ int silc_dlist_count(SilcDList list) return silc_list_count(list->list); } -/* Set the start of the list. This prepares the list for traversing entries - from the start of the list. */ +/****f* silcutil/SilcDListAPI/silc_dlist_start + * + * SYNOPSIS + * + * static inline + * void silc_dlist_start(SilcDList list); + * + * DESCRIPTION + * + * Set the start of the list. This prepares the list for traversing entries + * from the start of the list. + * + ***/ static inline void silc_dlist_start(SilcDList list) @@ -99,8 +170,19 @@ void silc_dlist_start(SilcDList list) silc_list_start(list->list); } -/* Adds new entry to the list. This is the default function to add new - entries to the list. */ +/****f* silcutil/SilcDListAPI/silc_dlist_add + * + * SYNOPSIS + * + * static inline + * void silc_dlist_add(SilcDList list, void *context); + * + * DESCRIPTION + * + * Adds new entry to the list. This is the default function to add new + * entries to the list. + * + ***/ static inline void silc_dlist_add(SilcDList list, void *context) @@ -110,7 +192,18 @@ void silc_dlist_add(SilcDList list, void *context) silc_list_add(list->list, e); } -/* Remove entry from the list. Returns < 0 on error, 0 otherwise. */ +/****f* silcutil/SilcDListAPI/silc_dlist_del + * + * SYNOPSIS + * + * static inline + * void silc_dlist_del(SilcDList list, void *context); + * + * DESCRIPTION + * + * Remove entry from the list. Returns < 0 on error, 0 otherwise. + * + ***/ static inline void silc_dlist_del(SilcDList list, void *context) @@ -127,19 +220,31 @@ void silc_dlist_del(SilcDList list, void *context) } } -/* Returns current entry from the list and moves the list pointer forward - so that calling this next time returns the next entry from the list. This - can be used to traverse the list. Return SILC_LIST_END when the entire - list has ben traversed. Later, silc_list_start must be called again when - re-starting list traversing. Example: - - // Traverse the list from the beginning to the end - silc_dlist_start(list) - while ((entry = silc_dlist_get(list)) != SILC_LIST_END) { - ... - } - -*/ +/****f* silcutil/SilcDListAPI/silc_dlist_get + * + * SYNOPSIS + * + * static inline + * void *silc_dlist_get(SilcDList list); + * + * DESCRIPTION + * + * Returns current entry from the list and moves the list pointer forward + * so that calling this next time returns the next entry from the list. + * This can be used to traverse the list. Return SILC_LIST_END when the + * entire list has been traversed. Later, silc_list_start must be called + * again when re-starting list traversing. + * + * EXAMPLE + * + * // Traverse the list from the beginning to the end + * silc_dlist_start(list) + * while ((entry = silc_dlist_get(list)) != SILC_LIST_END) { + * ... + * } + * + ***/ + static inline void *silc_dlist_get(SilcDList list) {