/*-------------------------------------------------------------*/
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_constring *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_DATAEND : 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)