X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilccore%2Fsilcidcache.h;h=c48fe0b6dd08daca75c9f00b7d0cf296ea11cd9c;hb=40f8443d8d3a6577336ee66d18e04d9ac4d956bb;hp=0e13f431444bbd4bc7b5c93de8e7fa6fa29d1b0f;hpb=10ded461617f165e52bc148b0dfa66a0fbca47ac;p=silc.git diff --git a/lib/silccore/silcidcache.h b/lib/silccore/silcidcache.h index 0e13f431..c48fe0b6 100644 --- a/lib/silccore/silcidcache.h +++ b/lib/silccore/silcidcache.h @@ -1,18 +1,15 @@ /* - + silcidcache.h - - COPYRIGHT - - Author: Pekka Riikonen - - Copyright (C) 2000 - 2001 Pekka Riikonen - + + Author: Pekka Riikonen + + Copyright (C) 2000 - 2005 Pekka Riikonen + This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - + the Free Software Foundation; version 2 of the License. + This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -20,10 +17,10 @@ */ -/****h* silccore/silcidcache.h +/****h* silccore/SILC ID Cache Interface * * DESCRIPTION - * + * * SILC ID Cache is an cache for all kinds of ID's used in the SILC * protocol. Application can save here the ID's it uses and the interface * provides fast retrieval of the ID's from the cache. @@ -36,98 +33,61 @@ /****s* silccore/SilcIDCacheAPI/SilcIDCacheEntry * * NAME - * - * typedef struct { ... } 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. * - * uint32 expire + * typedef struct SilcIDCacheEntryStruct { ... } SilcIDCacheEntry; * - * 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 + * DESCRIPTION * - * 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; - uint32 expire; - void *context; +typedef struct SilcIDCacheEntryStruct { + struct SilcIDCacheEntryStruct *next; + void *id; /* Associated ID */ + char *name; /* Associated entry name */ + void *context; /* Associated context */ } *SilcIDCacheEntry; /***/ /****s* silccore/SilcIDCacheAPI/SilcIDCache * * NAME - * + * * typedef struct SilcIDCacheStruct *SilcIDCache; * * DESCRIPTION * - * This context is the actual ID Cache and is allocated by - * silc_idcache_alloc and given as argument usually to all + * This context is the actual ID Cache and is allocated by + * silc_idcache_alloc and given as argument usually to all * silc_idcache_* functions. It is freed by the * silc_idcache_free function. * ***/ 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); + * 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); - -#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 */ @@ -135,19 +95,22 @@ typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, * * SYNOPSIS * - * SilcIDCache silc_idcache_alloc(uint32 count, SilcIdType id_type, - * SilcIDCacheDestructor destructor); + * SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type, + * SilcIDCacheDestructor destructor, + * void *destructor_context, + * SilcBool delete_id, SilcBool delete_name); * * DESCRIPTION * * Allocates new ID cache object. The initial amount of allocated entries - * can be sent as argument. If `count' is 0 the system uses default values. + * can be sent as argument. If `count' is 0 the system uses default values. * The `id_type' defines the types of the ID's that will be saved to the * cache. * ***/ -SilcIDCache silc_idcache_alloc(uint32 count, SilcIdType id_type, - SilcIDCacheDestructor destructor); +SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type, + SilcIDCacheDestructor destructor, + void *destructor_context); /****f* silccore/SilcIDCacheAPI/silc_idcache_free * @@ -157,7 +120,7 @@ SilcIDCache silc_idcache_alloc(uint32 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); @@ -166,211 +129,160 @@ void silc_idcache_free(SilcIDCache cache); * * SYNOPSIS * - * bool silc_idcache_add(SilcIDCache cache, char *name, void *id, - * void *context, int expire); + * 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 used specific context. - * If the `expire' is TRUE the entry expires in default time and if FALSE - * 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 stored in the cache, + * and if the caller frees these pointers the caller is also responsible + * of deleting the cache entry. * ***/ -bool silc_idcache_add(SilcIDCache cache, char *name, void *id, - void *context, int expire); +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); + * SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id, + * void *app_context); * * DESCRIPTION * - * Delete cache entry by ID. Returns TRUE if the entry was deleted. - * The destructor function is not 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(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); - * - * 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 - * not called. - * - ***/ -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. + * 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. * - ***/ -bool silc_idcache_find_by_id(SilcIDCache cache, void *id, - SilcIDCacheList *ret); - -/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one + * NOTES * - * SYNOPSIS + * 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). * - * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, - * SilcIDCacheEntry *ret); - * - * DESCRIPTION - * - * 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 @@ -379,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 */