/*-------------------------------------------------------------*/
/***************************************************************
* A netwib_hash is an associative array : data is related to *
* a key. It's not possible to have two identical keys. *
* *
* The hash contains pointers. *
* *
* When an item is removed from the hash, 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_hash_erase_pf has to be called *
* For example, a user might want to store allocated memory *
* containing a netwib_buf. Then when the hash is closed, the *
* netwib_buf_close function has to be called and the memory *
* has to be freed. *
***************************************************************/
/*-------------------------------------------------------------*/
typedef struct netwib_hash netwib_hash;
typedef const netwib_hash netwib_consthash;
/*-------------------------------------------------------------*/
/* This prototype defines a function erasing the item pitem */
typedef netwib_err (*netwib_hash_erase_pf)(netwib_ptr pitem);
/* This prototype defines a function duplicating an item */
typedef netwib_err (*netwib_hash_duplicate_pf)(netwib_constptr pitem,
netwib_ptr *pdupofitem);
/* 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_hash_criteria_pf)(netwib_constbuf *pkey,
netwib_constptr pitem,
netwib_ptr pinfos,
netwib_bool *pbool);
/*-------------------------------------------------------------*/
/* Name : netwib_hash_init
Description :
Initialize a netwib_hash.
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) :
**pphash : netwib_hash allocated and initialized
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_hash_init(netwib_hash_erase_pf pfunc_erase,
netwib_hash_duplicate_pf pfunc_duplicate,
netwib_hash **pphash);
/*-------------------------------------------------------------*/
/* Name : netwib_hash_close
Description :
Destroy a netwib_hash.
Input parameter(s) :
eraseitems : if true, function pfunc_erase (set in
netwib_hash_init) is called
Input/output parameter(s) :
**pphash : netwib_hash to destroy
Output parameter(s) :
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_hash_close(netwib_hash **pphash,
netwib_bool eraseitems);
/*-------------------------------------------------------------*/
/* Types to control a netwib_hash */
typedef enum {
NETWIB_HASH_CTLTYPE_COUNT = 1 /* count number of items */
} netwib_hash_ctltype;
netwib_err netwib_hash_ctl_set(netwib_hash *phash,
netwib_hash_ctltype type,
netwib_ptr p,
netwib_uint32 ui);
netwib_err netwib_hash_ctl_get(netwib_hash *phash,
netwib_hash_ctltype type,
netwib_ptr p,
netwib_uint32 *pui);
/*-------------------------------------------------------------*/
/* netwib_err f(netwib_hash *phash, netwib_uint32 *pnumberofitems); */
#define netwib_hash_ctl_get_count(phash,pnumberofitems) netwib_hash_ctl_get(phash,NETWIB_HASH_CTLTYPE_COUNT,NULL,pnumberofitems)
/*-------------------------------------------------------------*/
/* Name : netwib_hash_add
Description :
Add an item to the netwib_hash. Is the key already exists,
it is overwritten.
Input parameter(s) :
*pkey : key to store
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) :
*phash : netwib_hash where to work
Output parameter(s) :
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_hash_add(netwib_hash *phash,
netwib_constbuf *pkey,
netwib_constptr pitem,
netwib_bool erasepreviousitem);
/*-------------------------------------------------------------*/
/* Name : netwib_hash_add_hash_criteria
Description :
Add a hash into the netwib_hash. Existing keys
are overwritten.
Input parameter(s) :
pfunc_criteria : function used to decide to add an item
If this function is NULL, no criterion is
applied.
erasepreviousitems : if true, function pfunc_erase (set in
netwib_hash_init) is called to erase the
items previously located in the hash
Input/output parameter(s) :
*phash : netwib_hash where to work
*phashtoadd : netwib_hash to add
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_hash_add_hash_criteria(netwib_hash *phash,
netwib_hash *phashtoadd,
netwib_hash_criteria_pf pfunc_criteria,
netwib_ptr pinfos,
netwib_bool erasepreviousitems);
#define netwib_hash_add_hash_all(phash,phashtoadd,erasepreviousitems) netwib_hash_add_hash_criteria(phash,phashtoadd,NULL,NULL,erasepreviousitems)
/*-------------------------------------------------------------*/
/* Name : netwib_hash_contains
Description :
Check if a key is in the hash.
Input parameter(s) :
*phash : netwib_hash where to work
*pkey : key to obtain
Input/output parameter(s) :
Output parameter(s) :
*pyes : true if key is found
Normal return values :
NETWIB_ERR_OK : ok
*/
netwib_err netwib_hash_contains(netwib_hash *phash,
netwib_constbuf *pkey,
netwib_bool *pyes);
/*-------------------------------------------------------------*/
/* Name : netwib_hash_value
Description :
Get the value of an item.
Input parameter(s) :
*phash : netwib_hash where to work
*pkey : key to obtain
Input/output parameter(s) :
Output parameter(s) :
*ppitem : pointer to the memory containing the item
Normal return values :
NETWIB_ERR_OK : ok
NETWIB_ERR_NOTFOUND : key not found
*/
netwib_err netwib_hash_value(netwib_hash *phash,
netwib_constbuf *pkey,
netwib_ptr *ppitem);
/*-------------------------------------------------------------*/
/* Name : netwib_hash_del
Description :
Remove an item from the netwib_hash.
Input parameter(s) :
*pkey : key to del
eraseitem : if true, function pfunc_erase (set in
netwib_hash_init) is called to erase the
item located at position
Input/output parameter(s) :
*phash : netwib_hash where to work
Output parameter(s) :
Normal return values :
NETWIB_ERR_OK : ok
NETWIB_ERR_NOTFOUND : key not found
*/
netwib_err netwib_hash_del(netwib_hash *phash,
netwib_constbuf *pkey,
netwib_bool eraseitem);
/*-------------------------------------------------------------*/
/* Name : netwib_hash_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) :
*phash : netwib_hash 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_hash_del_criteria(netwib_hash *phash,
netwib_hash_criteria_pf pfunc_criteria,
netwib_ptr pinfos,
netwib_bool eraseitems);
#define netwib_hash_del_all(phash,eraseitems) netwib_hash_del_criteria(phash,NULL,NULL,eraseitems)