/*-------------------------------------------------------------*/ /*************************************************************** * A netwib_ring is a double linked ring containing pointers. * * For example, a ring containing 3 items looks like this : * * * * ,________________________________________________________. * * | ,----------------------------------------------------. | * * | | ._______. .________. .________. .________. | | * * | `->| |-->| |-->| |-->| |--' | * * | | start | | ptr1 | | ptr2 | | ptr3 | | * * `----|_______|<--|________|<--|________|<--|________|<---' * * * * The ring contains pointers (ptr1, ptr2 and ptr3 in the * * example). * * * * When an item is removed from the ring, its associated * * information stored in the pointer can be : * * - left untouched : user will have to free the pointer and * * its information * * - erased : the information is lost : a function of type * * netwib_ring_erase_pf has to be called * * For example, a user might want to store allocated memory * * containing a netwib_buf. Then when the ring is closed, the * * netwib_buf_close function has to be called and the memory * * has to be freed. * ***************************************************************/ /*-------------------------------------------------------------*/ typedef struct netwib_ring netwib_ring; typedef const netwib_ring netwib_constring; /*-------------------------------------------------------------*/ /* This prototype defines a function erasing the item pitem */ typedef netwib_err (*netwib_ring_erase_pf)(netwib_ptr pitem); /* This prototype defines a function duplicating an item */ typedef netwib_err (*netwib_ring_duplicate_pf)(netwib_constptr pitem, netwib_ptr *pdupofitem); /* This prototype defines a function comparing two items - if iteminf<itemsup, *pcmp is set to NETWIB_CMP_LT - if iteminf>itemsup, *pcmp is set to NETWIB_CMP_GT - if iteminf==itemsup, *pcmp is set to NETWIB_CMP_EQ The parameter pinfos will be set with optional information given when calling the function. */ typedef netwib_err (*netwib_ring_compare_pf)(netwib_constptr piteminf, netwib_constptr pitemsup, netwib_ptr pinfos, netwib_cmp *pcmp); /* This prototype defines a function detecting if an item matches a criteria - if it matches, *pbool is set to NETWIB_TRUE - if it does not matches, *pbool is set to NETWIB_FALSE The parameter pinfos will be set with optional information given when calling the function. */ typedef netwib_err (*netwib_ring_criteria_pf)(netwib_constptr pitem, netwib_ptr pinfos, netwib_bool *pbool); /*-------------------------------------------------------------*/ /* Name : netwib_ring_init Description : Initialize a netwib_ring. Input parameter(s) : *pfunc_erase : function needed to erase items This can be NULL *pfunc_duplicate : function needed to duplicate items This can be NULL Input/output parameter(s) : Output parameter(s) : **ppring : netwib_ring allocated and initialized Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_init(netwib_ring_erase_pf pfunc_erase, netwib_ring_duplicate_pf pfunc_duplicate, netwib_ring **ppring); /*-------------------------------------------------------------*/ /* Name : netwib_ring_close Description : Destroy a netwib_ring. Input parameter(s) : eraseitems : if true, function pfunc_erase (set in netwib_ring_init) is called Input/output parameter(s) : **ppring : netwib_ring to destroy Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_close(netwib_ring **ppring, netwib_bool eraseitems); /*-------------------------------------------------------------*/ /* Types to control a netwib_ring */ typedef enum { NETWIB_RING_CTLTYPE_COUNT = 1 /* count number of items */ } netwib_ring_ctltype; netwib_err netwib_ring_ctl_set(netwib_ring *pring, netwib_ring_ctltype type, netwib_ptr p, netwib_uint32 ui); netwib_err netwib_ring_ctl_get(netwib_ring *pring, netwib_ring_ctltype type, netwib_ptr p, netwib_uint32 *pui); /*-------------------------------------------------------------*/ /* netwib_err f(netwib_ring *pring, netwib_uint32 *pnumberofitems); */ #define netwib_ring_ctl_get_count(pring,pnumberofitems) netwib_ring_ctl_get(pring,NETWIB_RING_CTLTYPE_COUNT,NULL,pnumberofitems) /*-------------------------------------------------------------*/ /* Name : netwib_ring_add_first Description : Add an item to the netwib_ring. Input parameter(s) : pitem : pointer to an allocated memory containing the item Input/output parameter(s) : *pring : netwib_ring where to work Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_add_first(netwib_ring *pring, netwib_constptr pitem); netwib_err netwib_ring_add_last(netwib_ring *pring, netwib_constptr pitem); /*-------------------------------------------------------------*/ /* Name : netwib_ring_del_criteria Description : Del items matching a criterion. Input parameter(s) : pfunc_criteria : function used to decide to del an item If this function is NULL, no criterion is applied. 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 */ netwib_err netwib_ring_del_criteria(netwib_ring *pring, netwib_ring_criteria_pf pfunc_criteria, netwib_ptr pinfos, netwib_bool eraseitems); #define netwib_ring_del_all(pring,eraseitems) netwib_ring_del_criteria(pring,NULL,NULL,eraseitems) /*-------------------------------------------------------------*/ /* Name : netwib_ring_del_duplicate Description : Del duplicate items from a netwib_ring. Input parameter(s) : pfunc_compare : function used to compare two 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_compare. This may be used to send information to *pfunc_compare. Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_del_duplicate(netwib_ring *pring, netwib_ring_compare_pf pfunc_compare, netwib_ptr pinfos, netwib_bool eraseitems); /*-------------------------------------------------------------*/ /* Name : netwib_ring_sort Description : Sort items of the netwib_ring. Input parameter(s) : pfunc_compare : function used to compare two 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_compare. This may be used to send information to *pfunc_compare. Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_sort(netwib_ring *pring, netwib_ring_compare_pf pfunc_compare, netwib_ptr pinfos); /*-------------------------------------------------------------*/ /* Name : netwib_ring_group Description : Group items of the netwib_ring. Input parameter(s) : pfunc_compare : function used to compare two 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_compare. This may be used to send information to *pfunc_compare. Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_ring_group(netwib_ring *pring, netwib_ring_compare_pf pfunc_compare, netwib_ptr pinfos);