*
* 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;
/***/
***/
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 */
* 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
*
* 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
*
*
* DESCRIPTION
*
- * Frees ID cache object and all cache entries.
+ * Frees ID cache context and all cache entries.
*
***/
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
* 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 */
projects / silc.git / blobdiff