/*-------------------------------------------------------------*/ /*************************************************************** * A netwib_hash_index is used to loop through a hash. * * * * When the hash is only read, several indexes * * can simultaneously loop through the hash. * * * * However, when the hash is edited, strange behavior can * * occur when a netwib_hash_index_xyz function is called, * * depending on function used to edit the hash: * * - netwib_hash_contains, * * netwib_hash_value, * * netwib_hash_index_next * * netwib_hash_index_this_value, * * netwib_hash_index_this_replace, * * netwib_hash_index_this_del: * * No problem. * * - netwib_hash_add, * * netwib_hash_add_hash_criteria: * * The added item(s) may be returned or not returned, * * depending on the (unpredictable) insertion position * * relative to the index position. * * - netwib_hash_del, * * netwib_hash_del_criteria: * * You should not use them because if the item pointed by * * the index is deleted, it will cause an access to freed * * memory. You may use them only if you are sure to not * * delete the current item. * * However, after netwib_hash_index_this_del, you must * * not use them because there is not way to know if they * * will delete internal items. * ***************************************************************/ /*-------------------------------------------------------------*/ typedef struct netwib_hash_index netwib_hash_index; /*-------------------------------------------------------------*/ /* Name : netwib_hash_index_init Description : Initialize a netwib_hash_index used to loop through a netwib_hash. Input parameter(s) : Input/output parameter(s) : Output parameter(s) : **pphashindex : netwib_hash_index allocated and initialized Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_hash_index_init(netwib_consthash *phash, netwib_hash_index **pphashindex); /*-------------------------------------------------------------*/ /* Name : netwib_hash_index_close Description : Close a netwib_hashindex. Input parameter(s) : Input/output parameter(s) : **pphashindex : netwib_hash_index closed Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_hash_index_close(netwib_hash_index **pphashindex); /*-------------------------------------------------------------*/ /* Types to control a netwib_hash_index */ typedef enum { NETWIB_HASH_INDEX_CTLTYPE_REWIND = 1, /* position at beginning */ NETWIB_HASH_INDEX_CTLTYPE_INDEX /* reset with index pos */ } netwib_hash_index_ctltype; /* Those functions permit to set/get parameters (pointer and integer) about a netwib_hash_index. It should not be used directly, but by the defines. */ netwib_err netwib_hash_index_ctl_set(netwib_hash_index *phashindex, netwib_hash_index_ctltype type, netwib_ptr p, netwib_uint32 ui); netwib_err netwib_hash_index_ctl_get(netwib_hash_index *phashindex, netwib_hash_index_ctltype type, netwib_ptr p, netwib_uint32 *pui); /*-------------------------------------------------------------*/ /* netwib_err f(netwib_hash_index *phashindex); */ #define netwib_hash_index_ctl_set_rewind(phashindex) netwib_hash_index_ctl_set(phashindex,NETWIB_HASH_INDEX_CTLTYPE_REWIND,NULL,0) /* netwib_err f(netwib_hash_index *phashindex,netwib_hash_index *phashindexref);*/ #define netwib_hash_index_ctl_set_index(phashindex,phashindexref) netwib_hash_index_ctl_set(phashindex,NETWIB_HASH_INDEX_CTLTYPE_INDEX,phashindexref,0) /*-------------------------------------------------------------*/ /* Name : netwib_hash_index_next_criteria Description : Get the next item in the hash. Input parameter(s) : pfunc_search : function used to match the item Input/output parameter(s) : *phashindex : netwib_hash_index pinfos : optional parameter (can be NULL) which will be used as the second parameter for *pfunc_search. This may be used to send information to *pfunc_search. Output parameter(s) : *pkey : found key *ppitem : found item Normal return values : NETWIB_ERR_OK : ok NETWIB_ERR_DATAEND : end of the hash reached */ netwib_err netwib_hash_index_next_criteria(netwib_hash_index *phashindex, netwib_hash_criteria_pf pfunc_search, netwib_ptr pinfos, netwib_buf *pkey, netwib_ptr *ppitem); #define netwib_hash_index_next(phashindex,pkey,ppitem) netwib_hash_index_next_criteria(phashindex,NULL,NULL,pkey,ppitem) /*-------------------------------------------------------------*/ /* Name : netwib_hash_index_this_value Description : Re-give the last value. Input parameter(s) : Input/output parameter(s) : *phashindex : netwib_hash_index Output parameter(s) : *pkey : found key *ppitem : found item Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_hash_index_this_value(netwib_hash_index *phashindex, netwib_buf *pkey, netwib_ptr *ppitem); /*-------------------------------------------------------------*/ /* Name : netwib_hash_index_this_del Description : Delete the last given value by a netwib_hash_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) : *phashindex : netwib_hash_index Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_hash_index_this_del(netwib_hash_index *phashindex, netwib_bool eraseitem); /*-------------------------------------------------------------*/ /* Name : netwib_hash_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_hash_init) is called to erase the item previously located in the hash Input/output parameter(s) : *phashindex : netwib_hash_index Output parameter(s) : Normal return values : NETWIB_ERR_OK : ok */ netwib_err netwib_hash_index_this_replace(netwib_hash_index *phashindex, netwib_constptr pitem, netwib_bool erasepreviousitem);