X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilccore%2Fsilcidcache.h;h=e445b0a4035e9bda852ef0893efd2e40a7fc60fc;hb=d1e71f42379e8b5cd0748a7aeae8561b02cfe53d;hp=0e13f431444bbd4bc7b5c93de8e7fa6fa29d1b0f;hpb=10ded461617f165e52bc148b0dfa66a0fbca47ac;p=silc.git diff --git a/lib/silccore/silcidcache.h b/lib/silccore/silcidcache.h index 0e13f431..e445b0a4 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,13 +33,13 @@ /****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 + * 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. * @@ -54,7 +51,7 @@ * * A name associated with the ID. * - * uint32 expire + * SilcUInt32 expire * * Time when this cache entry expires. This is normal time() value * plus the validity. Cache entry has expired if current time is @@ -70,7 +67,7 @@ typedef struct { void *id; char *name; - uint32 expire; + SilcUInt32 expire; void *context; } *SilcIDCacheEntry; /***/ @@ -78,13 +75,13 @@ typedef struct { /****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. * @@ -94,12 +91,12 @@ 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 + * 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 @@ -113,7 +110,8 @@ typedef struct SilcIDCacheListStruct *SilcIDCacheList; * SYNOPSIS * * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, - * SilcIDCacheEntry entry); + * SilcIDCacheEntry entry, + * void *context); * * DESCRIPTION * @@ -124,7 +122,8 @@ typedef struct SilcIDCacheListStruct *SilcIDCacheList; * ***/ typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, - SilcIDCacheEntry entry); + SilcIDCacheEntry entry, + void *context); #define SILC_ID_CACHE_EXPIRE 3600 #define SILC_ID_CACHE_EXPIRE_DEF (time(NULL) + SILC_ID_CACHE_EXPIRE) @@ -135,19 +134,27 @@ 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, + * bool delete_id, bool 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. * + * 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(uint32 count, SilcIdType id_type, - SilcIDCacheDestructor destructor); +SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type, + SilcIDCacheDestructor destructor, + void *destructor_context, + bool delete_id, bool delete_name); /****f* silccore/SilcIDCacheAPI/silc_idcache_free * @@ -166,20 +173,28 @@ void silc_idcache_free(SilcIDCache cache); * * SYNOPSIS * - * bool silc_idcache_add(SilcIDCache cache, char *name, void *id, - * void *context, int expire); + * bool silc_idcache_add(SilcIDCache cache, char *name, void *id, + * void *context, int expire, SilcIDCacheEntry *ret); * * 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. + * 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. + * + * The `name', `id' and `context' pointers will be saved 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. * ***/ -bool silc_idcache_add(SilcIDCache cache, char *name, void *id, - void *context, int expire); +bool silc_idcache_add(SilcIDCache cache, char *name, void *id, + void *context, int expire, SilcIDCacheEntry *ret); /****f* silccore/SilcIDCacheAPI/silc_idcache_del * @@ -214,9 +229,9 @@ bool silc_idcache_del_by_id(SilcIDCache cache, void *id); * SYNOPSIS * * bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id, - * SilcHashFunction hash, + * SilcHashFunction hash, * void *hash_context, - * SilcHashCompare compare, + * SilcHashCompare compare, * void *compare_context); * * DESCRIPTION @@ -224,13 +239,13 @@ bool silc_idcache_del_by_id(SilcIDCache cache, void *id); * 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. + * called. * ***/ bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id, - SilcHashFunction hash, + SilcHashFunction hash, void *hash_context, - SilcHashCompare compare, + SilcHashCompare compare, void *compare_context); /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context @@ -284,7 +299,7 @@ bool silc_idcache_purge(SilcIDCache cache); * * DESCRIPTION * - * Purges the cache by context and removes expired cache entires. + * 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. * @@ -310,7 +325,7 @@ bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret); * * SYNOPSIS * - * bool silc_idcache_find_by_id(SilcIDCache cache, void *id, + * bool silc_idcache_find_by_id(SilcIDCache cache, void *id, * SilcIDCacheList *ret); * * DESCRIPTION @@ -320,14 +335,14 @@ bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret); * found. The caller must free the returned SilcIDCacheList. * ***/ -bool silc_idcache_find_by_id(SilcIDCache cache, void *id, +bool silc_idcache_find_by_id(SilcIDCache cache, void *id, SilcIDCacheList *ret); /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one * * SYNOPSIS * - * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, + * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, * SilcIDCacheEntry *ret); * * DESCRIPTION @@ -337,17 +352,17 @@ bool silc_idcache_find_by_id(SilcIDCache cache, void *id, * if the entry was found. * ***/ -bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, +bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, SilcIDCacheEntry *ret); /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one_ext * * SYNOPSIS * - * bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, - * SilcHashFunction hash, + * bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, + * SilcHashFunction hash, * void *hash_context, - * SilcHashCompare compare, + * SilcHashCompare compare, * void *compare_context, * SilcIDCacheEntry *ret); * @@ -359,10 +374,10 @@ bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, * is used. Returns TRUE if the entry was found. * ***/ -bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, - SilcHashFunction hash, +bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, + SilcHashFunction hash, void *hash_context, - SilcHashCompare compare, + SilcHashCompare compare, void *compare_context, SilcIDCacheEntry *ret); @@ -370,7 +385,7 @@ bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, * * SYNOPSIS * - * bool silc_idcache_find_by_context(SilcIDCache cache, void *context, + * bool silc_idcache_find_by_context(SilcIDCache cache, void *context, * SilcIDCacheEntry *ret); * * DESCRIPTION @@ -379,14 +394,14 @@ 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, +bool 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, + * bool silc_idcache_find_by_name(SilcIDCache cache, char *name, * SilcIDCacheList *ret); * * DESCRIPTION @@ -396,7 +411,7 @@ bool silc_idcache_find_by_context(SilcIDCache cache, void *context, * TRUE if the entry was found. The caller must free the SIlcIDCacheList. * ***/ -bool silc_idcache_find_by_name(SilcIDCache cache, char *name, +bool silc_idcache_find_by_name(SilcIDCache cache, char *name, SilcIDCacheList *ret); /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one @@ -434,7 +449,7 @@ int silc_idcache_list_count(SilcIDCacheList list); * * SYNOPSIS * - * bool silc_idcache_list_first(SilcIDCacheList list, + * bool silc_idcache_list_first(SilcIDCacheList list, * SilcIDCacheEntry *ret); * * DESCRIPTION