/*-------------------------------------------------------------*/ typedef struct netwib_ring_index netwib_ring_index; /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_init Description : Initialize a netwib_ring_index used to loop through a netwib_ring. Input parameter(s) : Input/output parameter(s) : Output parameter(s) : **ppringindex : netwib_ring_index allocated and initialized Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_index_init(netwib_ring *pring, netwib_ring_index **ppringindex); /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_close Description : Close a netwib_ringindex. Input parameter(s) : Input/output parameter(s) : **ppringindex : netwib_ring_index closed Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_index_close(netwib_ring_index **ppringindex); /*-------------------------------------------------------------*/ /* Types to control a netwib_ring_index */ typedef enum { NETWIB_RING_INDEX_CTLTYPE_REWIND = 1, /* position at beginning */ NETWIB_RING_INDEX_CTLTYPE_INDEX /* reset with index pos */ } netwib_ring_index_ctltype; /* Those functions permit to set/get parameters (pointer and integer) about a netwib_ring_index. It should not be used directly, but by the defines. */ netwib_err netwib_ring_index_ctl_set(netwib_ring_index *pringindex, netwib_ring_index_ctltype type, netwib_ptr p, netwib_uint32 ui); netwib_err netwib_ring_index_ctl_get(netwib_ring_index *pringindex, netwib_ring_index_ctltype type, netwib_ptr p, netwib_uint32 *pui); /*-------------------------------------------------------------*/ /* netwib_err f(netwib_ring_index *pringindex); */ #define netwib_ring_index_ctl_set_rewind(pringindex) netwib_ring_index_ctl_set(pringindex,NETWIB_RING_INDEX_CTLTYPE_REWIND,NULL,0) /* netwib_err f(netwib_ring_index *pringindex,netwib_ring_index *pringindexref);*/ #define netwib_ring_index_ctl_set_index(pringindex,pringindexref) netwib_ring_index_ctl_set(pringindex,NETWIB_RING_INDEX_CTLTYPE_INDEX,pringindexref,0) /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_next_criteria Description : Get the next item in the ring. Input parameter(s) : pfunc_criteria : function used to decide to remove an item If this function is NULL, no criterion is applied. Input/output parameter(s) : *pringindex : netwib_ring_index pinfos : optional parameter (can be NULL) which will be used as the parameter for pfunc_criteria. This may be used to send information to *pfunc_criteria. Output parameter(s) : *ppitem : pointer to the memory containing the item Normal return values : NETWIB_ERR_OK : ok NETWIB_ERR_OKDATAEND : end of the ring reached Note : If one thread changes the netwib_ring between two calls, the next result might be incorrect. Moreover, if current item is suppressed, it's not possible to obtain its next, and this can lead to a memory violation error (because access to uninitialized memory is done). Developer have to lock the entire loop (going through each item), or to copy the netwib_ring and to loop on the copy. */ netwib_err netwib_ring_index_next_criteria(netwib_ring_index *pringindex, netwib_ring_criteria_pf pfunc_criteria, netwib_ptr pinfos, netwib_ptr *ppitem); #define netwib_ring_index_next(pringindex,ppitem) netwib_ring_index_next_criteria(pringindex,NULL, NULL,ppitem) netwib_err netwib_ring_index_previous_criteria(netwib_ring_index *pringindex, netwib_ring_criteria_pf pfunc_criteria, netwib_ptr pinfos, netwib_ptr *ppitem); #define netwib_ring_index_previous(pringindex,ppitem) netwib_ring_index_previous_criteria(pringindex,NULL, NULL,ppitem) /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_add_before Description : Add an item in the ring. Input parameter(s) : Input/output parameter(s) : *pringindex : netwib_ring_index Output parameter(s) : *ppitem : pointer to the memory containing the item Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_index_add_before(netwib_ring_index *pringindex, netwib_constptr pitem); netwib_err netwib_ring_index_add_after(netwib_ring_index *pringindex, netwib_constptr pitem); /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_this_value Description : Re-give the last value. Input parameter(s) : Input/output parameter(s) : *pringindex : netwib_ring_index Output parameter(s) : *ppitem : pointer to the memory containing the item Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_index_this_value(netwib_ring_index *pringindex, netwib_ptr *ppitem); /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_this_del Description : Delete the last given value by a netwib_ring_index_next function. Input parameter(s) : eraseitem : if true, function pfunc_erase (set in netwib_hash_init) is called to erase the item located at position Input/output parameter(s) : *pringindex : netwib_ring_index Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_index_this_del(netwib_ring_index *pringindex, netwib_bool eraseitem); /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_this_replace Description : Replace value, but keep the same key. Input parameter(s) : pitem : pointer to an allocated memory containing the item erasepreviousitem : if true, function pfunc_erase (set in netwib_ring_init) is called to erase the item previously located in the ring Input/output parameter(s) : *pringindex : netwib_ring_index Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_index_this_replace(netwib_ring_index *pringindex, netwib_constptr pitem, netwib_bool erasepreviousitem); /*-------------------------------------------------------------*/ /* Name : netwib_ring_index_add_ring_criteria Description : Add a ring within another ring. Only items matching a criterion are added. Input parameter(s) : *pringindex : ring is added after this index *pringtoadd : netwib_ring to add in pring pfunc_criteria : function used to decide to add an item If this function is NULL, no criterion is applied. duplicateitems : if true, function pfunc_duplicate (set in netwib_ring_init) is called to duplicate items Input/output parameter(s) : *pring : netwib_ring where to work pinfos : optional parameter (can be NULL) which will be used as the parameter for pfunc_criteria. This may be used to send information to *pfunc_criteria. Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok Note : If an error occurs during addition, ring will only contain partial data. It's developer's job to use a temporary ring to deal with such errors. */ netwib_err netwib_ring_index_add_ring_criteria(netwib_ring_index *pringindex, netwib_ring *pringtoadd, netwib_ring_criteria_pf pfunc_criteria, netwib_ptr pinfos, netwib_bool duplicateitems); #define netwib_ring_index_add_ring_all(pringindex,pringtoadd,duplicateitems) netwib_ring_index_add_ring_criteria(pringindex,pringtoadd,NULL,NULL,duplicateitems)