X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=lib%2Fsilccore%2Fsilcidcache.h;h=c48fe0b6dd08daca75c9f00b7d0cf296ea11cd9c;hp=e445b0a4035e9bda852ef0893efd2e40a7fc60fc;hb=40f8443d8d3a6577336ee66d18e04d9ac4d956bb;hpb=6210937137137fe4019e808686dd1fcf99360af6 diff --git a/lib/silccore/silcidcache.h b/lib/silccore/silcidcache.h index e445b0a4..c48fe0b6 100644 --- a/lib/silccore/silcidcache.h +++ b/lib/silccore/silcidcache.h @@ -34,41 +34,21 @@ * * NAME * - * typedef struct { ... } SilcIDCacheEntry; + * typedef struct SilcIDCacheEntryStruct { ... } SilcIDCacheEntry; * * DESCRIPTION * - * This is one entry in the SILC ID Cache system. Contents of this is - * allocated outside the ID cache system, however, all the fields are - * filled with ID cache utility functions. The ID cache system does not - * allocate any of these fields nor free them. - * - * void *id - * - * The actual ID. - * - * char name - * - * A name associated with the ID. - * - * SilcUInt32 expire - * - * Time when this cache entry expires. This is normal time() value - * plus the validity. Cache entry has expired if current time is - * more than value in this field. If this value is zero (0) the - * entry never expires. - * - * void *context - * - * Any caller specified context. + * This is an entry in the SILC ID Cache system. This context is + * allocated by adding new entry to ID cache by calling silc_idcache_add. + * Each of the fields in the structure are allocated by the caller. * * SOURCE */ -typedef struct { - void *id; - char *name; - SilcUInt32 expire; - void *context; +typedef struct SilcIDCacheEntryStruct { + struct SilcIDCacheEntryStruct *next; + void *id; /* Associated ID */ + char *name; /* Associated entry name */ + void *context; /* Associated context */ } *SilcIDCacheEntry; /***/ @@ -88,45 +68,26 @@ typedef struct { ***/ typedef struct SilcIDCacheStruct *SilcIDCache; -/****s* silccore/SilcIDCacheAPI/SilcIDCacheList - * - * NAME - * - * typedef struct SilcIDCacheListStruct *SilcIDCacheList; - * - * DESCRIPTION - * - * This context is the ID Cache List and is allocated by - * some of the silc_idcache_* functions. Functions that may return - * multiple entries from the cache allocate the entries in to the - * SilcIDCacheList. The context is freed by silc_idcache_list_free - * function. - * - ***/ -typedef struct SilcIDCacheListStruct *SilcIDCacheList; - /****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor * * SYNOPSIS * * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, - * SilcIDCacheEntry entry, - * void *context); + * const SilcIDCacheEntry entry, + * void *destructor_context, + * void *app_context); * * DESCRIPTION * - * Destructor callback that is called when an cache entry expires or is - * purged from the ID cache. The application must not free cache entry - * because the library will do it automatically. The appliation, however, - * is responsible of freeing any data in the entry. + * Destructor callback given as argument to silc_idcache_alloc. This + * is called when an entry is deleted from the cache. Application + * must free the contents of the `entry'. * ***/ typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, - SilcIDCacheEntry entry, - void *context); - -#define SILC_ID_CACHE_EXPIRE 3600 -#define SILC_ID_CACHE_EXPIRE_DEF (time(NULL) + SILC_ID_CACHE_EXPIRE) + const SilcIDCacheEntry entry, + void *destructor_context, + void *app_context); /* Prototypes */ @@ -137,7 +98,7 @@ typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, * SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type, * SilcIDCacheDestructor destructor, * void *destructor_context, - * bool delete_id, bool delete_name); + * SilcBool delete_id, SilcBool delete_name); * * DESCRIPTION * @@ -146,15 +107,10 @@ typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, * The `id_type' defines the types of the ID's that will be saved to the * cache. * - * If 'delete_id' is TRUE then library will free the ID when a - * cache entry is deleted. If 'delete_name' is TRUE then library - * will delete the associated name when a cache entry is deleted. - * ***/ SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type, SilcIDCacheDestructor destructor, - void *destructor_context, - bool delete_id, bool delete_name); + void *destructor_context); /****f* silccore/SilcIDCacheAPI/silc_idcache_free * @@ -164,7 +120,7 @@ SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type, * * DESCRIPTION * - * Frees ID cache object and all cache entries. + * Frees ID cache context and all cache entries. * ***/ void silc_idcache_free(SilcIDCache cache); @@ -173,219 +129,160 @@ void silc_idcache_free(SilcIDCache cache); * * SYNOPSIS * - * bool silc_idcache_add(SilcIDCache cache, char *name, void *id, - * void *context, int expire, SilcIDCacheEntry *ret); + * SilcIDCacheEntry + * silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context); * * DESCRIPTION * - * Add new entry to the cache. Returns TRUE if the entry was added and - * FALSE if it could not be added. The `name' is the name associated with - * the ID, the `id' the actual ID and the `context' a user specific context. - * If the `expire' is non-zero the entry expires in that specified time. - * If zero the entry never expires from the cache. + * Add new entry to the cache. Returns the allocated cache entry if the + * entry was added successfully, or NULL if error occurred. The `name' is + * the name associated with the ID, the `id' the actual ID and the + * `context' a caller specific context. * - * The `name', `id' and `context' pointers will be saved in the cache, + * The `name', `id' and `context' pointers will be stored in the cache, * and if the caller frees these pointers the caller is also responsible - * of deleting the cache entry. Otherwise the cache will have the freed - * pointers stored. - * - * If the `ret' is non-NULL the created ID Cache entry is returned to - * that pointer. + * of deleting the cache entry. * ***/ -bool silc_idcache_add(SilcIDCache cache, char *name, void *id, - void *context, int expire, SilcIDCacheEntry *ret); +SilcIDCacheEntry +silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context); /****f* silccore/SilcIDCacheAPI/silc_idcache_del * * SYNOPSIS * - * bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old); + * SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry, + * void *app_context); * * DESCRIPTION * - * Delete cache entry from cache. Returns TRUE if the entry was deleted. - * The destructor function is not called. + * Delete cache entry from cache. Returns TRUE if the entry was deleted. + * The destructor will be called for the entry. The `app_context' is + * delivered to the destructor. * ***/ -bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old); +SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry, + void *app_context); /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id * * SYNOPSIS * - * bool silc_idcache_del_by_id(SilcIDCache cache, void *id); - * - * DESCRIPTION - * - * Delete cache entry by ID. Returns TRUE if the entry was deleted. - * The destructor function is not called. - * - ***/ -bool silc_idcache_del_by_id(SilcIDCache cache, void *id); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id_ext - * - * SYNOPSIS - * - * bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id, - * SilcHashFunction hash, - * void *hash_context, - * SilcHashCompare compare, - * void *compare_context); + * SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id, + * void *app_context); * * DESCRIPTION * - * Same as silc_idcache_del_by_id but with specific hash and comparison - * functions. If the functions are NULL then default values are used. - * Returns TRUE if the entry was deleted. The destructor function is - * called. + * Delete cache entry by ID. Returns TRUE if the entry was deleted. + * The destructor will be called for the entry. The `app_context' is + * delivered to the destructor. * ***/ -bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id, - SilcHashFunction hash, - void *hash_context, - SilcHashCompare compare, - void *compare_context); +SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id, + void *app_context); /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context * * SYNOPSIS * - * bool silc_idcache_del_by_context(SilcIDCache cache, void *context); - * - * DESCRIPTION - * - * Deletes cachen entry by the user specified context. Returns TRUE - * if the entry was deleted. The destructor function is not called. - * - ***/ -bool silc_idcache_del_by_context(SilcIDCache cache, void *context); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_del_all - * - * SYNOPSIS - * - * bool silc_idcache_del_all(SilcIDCache cache); - * - * DESCRIPTION - * - * Deletes all cache entries from the cache and frees all memory. - * The destructor function is not called. - * - ***/ -bool silc_idcache_del_all(SilcIDCache cache); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_purge - * - * SYNOPSIS - * - * bool silc_idcache_purge(SilcIDCache cache); + * SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context); * * DESCRIPTION * - * Purges the cache by removing expired cache entires. Note that this - * may be very slow operation. Returns TRUE if the purging was successful. - * The destructor function is called for each purged cache entry. + * Deletes cachen entry by the user specified context. Returns TRUE + * if the entry was deleted. The destructor will be called for the + * entry. The `app_context' is delivered to the destructor. * ***/ -bool silc_idcache_purge(SilcIDCache cache); +SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context, + void *app_context); -/****f* silccore/SilcIDCacheAPI/silc_idcache_by_context +/****f* silccore/SilcIDCacheAPI/silc_idcache_update_id * * SYNOPSIS * - * bool silc_idcache_purge_by_context(SilcIDCache cache, void *context); + * SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry, + * void *old_id, void *new_id, + * char *old_name, char *new_name); * * DESCRIPTION * - * Purges the cache by context and removes expired cache entires. - * Returns TRUE if the puring was successful. The destructor function - * is called for the purged cache entry. + * Updates cache `entry' with new values. If the `new_id' is non-NULL + * then the `entry' will be updated with `new_id'. If the `new_name' is + * non-NULL then the `entry' will be updated with `new_name'. The + * caller is responsible of freeing the old values that was added with + * silc_idcache_add. * ***/ -bool silc_idcache_purge_by_context(SilcIDCache cache, void *context); +SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry, + void *old_id, void *new_id, + char *old_name, char *new_name); /****f* silccore/SilcIDCacheAPI/silc_idcache_get_all * * SYNOPSIS * - * bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret); + * SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list); * * DESCRIPTION * - * Returns all cache entries from the ID cache to the `ret' SilcIDCacheList. - * Returns TRUE if the retrieval was successful. The caller must free - * the returned SilcIDCacheList. + * Returns all cache entries into the SilcList `ret_list' pointer. Each + * entry in the list is SilcIDCacheEntry. Returns FALSE if the cache + * is empty. * ***/ -bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret); +SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list); /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id * * SYNOPSIS * - * bool silc_idcache_find_by_id(SilcIDCache cache, void *id, - * SilcIDCacheList *ret); + * SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id, + * SilcList *ret_list); * * DESCRIPTION * - * Find ID Cache entry by ID. This may return multiple entry and the - * `ret' SilcIDCacheList is allocated. Returns TRUE if the entry was - * found. The caller must free the returned SilcIDCacheList. - * - ***/ -bool silc_idcache_find_by_id(SilcIDCache cache, void *id, - SilcIDCacheList *ret); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one + * Find ID Cache entry by ID. This may return multiple entries. + * The entires are returned into the `ret_list' SilcList context. + * Returns TRUE if entry was found. * - * SYNOPSIS - * - * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, - * SilcIDCacheEntry *ret); + * NOTES * - * DESCRIPTION + * If this function is used to find Client ID (SilcClientID), only the + * hash portion of the Client ID is compared. Use the function + * silc_idcache_find_by_id_one to find exact match for Client ID (full + * ID is compared and not only the hash). * - * Find ID Cache entry by ID. Returns only one entry from the cache - * and the found entry is considered to be exact match. Returns TRUE - * if the entry was found. + * Comparing only the hash portion of Client ID allows searching of + * Client ID's by nickname, because the hash is based on the nickname. + * As nicknames are not unique, multiple entries may be found. * ***/ -bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, - SilcIDCacheEntry *ret); +SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id, + SilcList *ret_list); -/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one_ext +/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one * * SYNOPSIS * - * bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, - * SilcHashFunction hash, - * void *hash_context, - * SilcHashCompare compare, - * void *compare_context, - * SilcIDCacheEntry *ret); + * SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, + * SilcIDCacheEntry *ret); * * DESCRIPTION * - * Same as silc_idcache_find_by_id_one but with specific hash and - * comparison functions. If `hash' is NULL then the default hash - * funtion is used and if `compare' is NULL default comparison function - * is used. Returns TRUE if the entry was found. + * Find ID Cache entry by ID. Returns only one entry from the cache + * and the found entry is considered to be exact match. Returns TRUE + * if the entry was found. * ***/ -bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, - SilcHashFunction hash, - void *hash_context, - SilcHashCompare compare, - void *compare_context, +SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, SilcIDCacheEntry *ret); /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context * * SYNOPSIS * - * bool silc_idcache_find_by_context(SilcIDCache cache, void *context, + * SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context, * SilcIDCacheEntry *ret); * * DESCRIPTION @@ -394,98 +291,41 @@ bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, * entry was found. * ***/ -bool silc_idcache_find_by_context(SilcIDCache cache, void *context, - SilcIDCacheEntry *ret); +SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context, + SilcIDCacheEntry *ret); /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name * * SYNOPSIS * - * bool silc_idcache_find_by_name(SilcIDCache cache, char *name, - * SilcIDCacheList *ret); + * SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name, + * SilcList *ret_list); * * DESCRIPTION * - * Find cache entries by the name associated with the ID. This may - * return muliptle entries allocated to the SilcIDCacheList. Returns - * TRUE if the entry was found. The caller must free the SIlcIDCacheList. + * Find cache entries by the name associated with the ID. This may + * return multiple entries to the `ret_list' SilcList context. Returns + * TRUE if the entry was found. * ***/ -bool silc_idcache_find_by_name(SilcIDCache cache, char *name, - SilcIDCacheList *ret); +SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name, + SilcList *ret_list); /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one * * SYNOPSIS * - * bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name, + * SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name, * SilcIDCacheEntry *ret); * * DESCRIPTION * - * Find cache entry by the name associated with the ID. This returns + * Find cache entry by the name associated with the ID. This returns * one entry and the found entry is considered to be exact match. - * return muliptle entries allocated to the SilcIDCacheList. Returns - * TRUE if the entry was found. - * - ***/ -bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name, - SilcIDCacheEntry *ret); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_list_count - * - * SYNOPSIS - * - * int silc_idcache_list_count(SilcIDCacheList list); - * - * DESCRIPTION - * - * Returns the number of cache entries in the ID cache list. - * - ***/ -int silc_idcache_list_count(SilcIDCacheList list); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_list_first - * - * SYNOPSIS - * - * bool silc_idcache_list_first(SilcIDCacheList list, - * SilcIDCacheEntry *ret); - * - * DESCRIPTION - * - * Returns the first cache entry from the ID cache list. Returns FALSE - * If the entry could not be retrieved. - * - ***/ -bool silc_idcache_list_first(SilcIDCacheList list, SilcIDCacheEntry *ret); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_list_next - * - * SYNOPSIS - * - * bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret); - * - * DESCRIPTION - * - * Returns the next cache entry from the ID Cache list. Returns FALSE - * when there are not anymore entries in the list. - * - ***/ -bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_list_free - * - * SYNOPSIS - * - * void silc_idcache_list_free(SilcIDCacheList list); - * - * DESCRIPTION - * - * Frees ID cache list. User must free the list context returned by - * any of the searching functions. + * Returns TRUE if the entry was found. * ***/ -void silc_idcache_list_free(SilcIDCacheList list); +SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name, + SilcIDCacheEntry *ret); -#endif +#endif /* SILCIDCACHE_H */