silcidcache.h
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 2000 - 2001 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
*/
-#ifndef IDCACHE_H
-#define IDCACHE_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.
+ *
+ ***/
-/*
- Silc ID Cache Entry object.
+#ifndef SILCIDCACHE_H
+#define SILCIDCACHE_H
- 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.
+/****s* silccore/SilcIDCacheAPI/SilcIDCacheEntry
+ *
+ * NAME
+ *
+ * typedef struct SilcIDCacheEntryStruct { ... } SilcIDCacheEntry;
+ *
+ * DESCRIPTION
+ *
+ * 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 SilcIDCacheEntryStruct {
+ struct SilcIDCacheEntryStruct *next;
+ void *id; /* Associated ID */
+ char *name; /* Associated entry name */
+ void *context; /* Associated context */
+} *SilcIDCacheEntry;
+/***/
- void *id
+/****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
+ * silc_idcache_* functions. It is freed by the
+ * silc_idcache_free function.
+ *
+ ***/
+typedef struct SilcIDCacheStruct *SilcIDCache;
- The actual ID.
+/****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
+ * const SilcIDCacheEntry entry,
+ * void *destructor_context,
+ * void *app_context);
+ *
+ * DESCRIPTION
+ *
+ * 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,
+ const SilcIDCacheEntry entry,
+ void *destructor_context,
+ void *app_context);
- char name
+/* Prototypes */
- A name associated with the ID.
+/****f* silccore/SilcIDCacheAPI/silc_idcache_alloc
+ *
+ * SYNOPSIS
+ *
+ * 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.
+ * The `id_type' defines the types of the ID's that will be saved to the
+ * cache.
+ *
+ ***/
+SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
+ SilcIDCacheDestructor destructor,
+ void *destructor_context);
- uint32 expire
+/****f* silccore/SilcIDCacheAPI/silc_idcache_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_idcache_free(SilcIDCache cache);
+ *
+ * DESCRIPTION
+ *
+ * Frees ID cache context and all cache entries.
+ *
+ ***/
+void silc_idcache_free(SilcIDCache cache);
- 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.
+/****f* silccore/SilcIDCacheAPI/silc_idcache_add
+ *
+ * SYNOPSIS
+ *
+ * SilcIDCacheEntry
+ * silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
+ *
+ * DESCRIPTION
+ *
+ * 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.
+ *
+ ***/
+SilcIDCacheEntry
+silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
- void *context
+/****f* silccore/SilcIDCacheAPI/silc_idcache_del
+ *
+ * SYNOPSIS
+ *
+ * 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 will be called for the entry. The `app_context' is
+ * delivered to the destructor.
+ *
+ ***/
+SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry,
+ void *app_context);
- Any caller specified context.
+/****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id
+ *
+ * SYNOPSIS
+ *
+ * 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 will be called for the entry. The `app_context' is
+ * delivered to the destructor.
+ *
+ ***/
+SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id,
+ void *app_context);
-*/
-typedef struct {
- void *id;
- char *name;
- uint32 expire;
- void *context;
-} *SilcIDCacheEntry;
+/****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context
+ *
+ * SYNOPSIS
+ *
+ * SilcBool 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 will be called for the
+ * entry. The `app_context' is delivered to the destructor.
+ *
+ ***/
+SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context,
+ void *app_context);
-/* Forward declaration for SILC ID Cache object. */
-typedef struct SilcIDCacheStruct *SilcIDCache;
+/****f* silccore/SilcIDCacheAPI/silc_idcache_update_id
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
+ * void *old_id, void *new_id,
+ * char *old_name, char *new_name);
+ *
+ * DESCRIPTION
+ *
+ * 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.
+ *
+ ***/
+SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
+ void *old_id, void *new_id,
+ char *old_name, char *new_name);
-/* Forward declaration for ID Cache List */
-typedef struct SilcIDCacheListStruct *SilcIDCacheList;
+/****f* silccore/SilcIDCacheAPI/silc_idcache_get_all
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
+ *
+ * DESCRIPTION
+ *
+ * Returns all cache entries into the SilcList `ret_list' pointer. Each
+ * entry in the list is SilcIDCacheEntry. Returns FALSE if the cache
+ * is empty.
+ *
+ ***/
+SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
-/* 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. */
-typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
- SilcIDCacheEntry entry);
+/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
+ * SilcList *ret_list);
+ *
+ * DESCRIPTION
+ *
+ * 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.
+ *
+ * NOTES
+ *
+ * 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).
+ *
+ * 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.
+ *
+ ***/
+SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
+ SilcList *ret_list);
-#define SILC_ID_CACHE_ANY ((void *)1)
+/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one
+ *
+ * SYNOPSIS
+ *
+ * SilcBool 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.
+ *
+ ***/
+SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
+ SilcIDCacheEntry *ret);
-#define SILC_ID_CACHE_EXPIRE 3600
-#define SILC_ID_CACHE_EXPIRE_DEF (time(NULL) + SILC_ID_CACHE_EXPIRE)
+/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
+ * SilcIDCacheEntry *ret);
+ *
+ * DESCRIPTION
+ *
+ * Find cache entry by user specified context. Returns TRUE if the
+ * entry was found.
+ *
+ ***/
+SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
+ SilcIDCacheEntry *ret);
-/* Prototypes */
-SilcIDCache silc_idcache_alloc(uint32 count, SilcIdType id_type,
- SilcIDCacheDestructor destructor);
-void silc_idcache_free(SilcIDCache cache);
-bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
- void *context, int expire);
-bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
-bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
-bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id,
- SilcHashFunction hash,
- void *hash_context,
- SilcHashCompare compare,
- void *compare_context);
-bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
-bool silc_idcache_del_all(SilcIDCache cache);
-bool silc_idcache_purge(SilcIDCache cache);
-bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
-bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
-bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
- SilcIDCacheList *ret);
-bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
- SilcIDCacheEntry *ret);
-bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id,
- SilcHashFunction hash,
- void *hash_context,
- SilcHashCompare compare,
- void *compare_context,
- SilcIDCacheEntry *ret);
-bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
- SilcIDCacheEntry *ret);
-bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
- SilcIDCacheList *ret);
-bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
- SilcIDCacheEntry *ret);
-int silc_idcache_list_count(SilcIDCacheList list);
-bool silc_idcache_list_first(SilcIDCacheList list, SilcIDCacheEntry *ret);
-bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
-void silc_idcache_list_free(SilcIDCacheList list);
-
-#endif
+/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name
+ *
+ * SYNOPSIS
+ *
+ * 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 multiple entries to the `ret_list' SilcList context. Returns
+ * TRUE if the entry was found.
+ *
+ ***/
+SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
+ SilcList *ret_list);
+
+/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one
+ *
+ * SYNOPSIS
+ *
+ * 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
+ * one entry and the found entry is considered to be exact match.
+ * Returns TRUE if the entry was found.
+ *
+ ***/
+SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
+ SilcIDCacheEntry *ret);
+
+#endif /* SILCIDCACHE_H */
projects / silc.git / blobdiff