Merged silc_1_1_branch to trunk.

[silc.git] / lib / silcapputil / silcidcache.h

diff --git a/lib/silcapputil/silcidcache.h b/lib/silcapputil/silcidcache.h
index d01b2f5eda4d7ff21729a42ea35042e583de08c1..7d8e1427abfa2219e9b041185b6f475f6f6d3cba 100644 (file)
--- a/lib/silcapputil/silcidcache.h
+++ b/lib/silcapputil/silcidcache.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2000 - 2006 Pekka Riikonen
+  Copyright (C) 2000 - 2007 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
@@ -17,7 +17,7 @@
 
 */
 
-/****h* silcidcache/SILC ID Cache Interface
+/****h* silcapputil/SILC ID Cache Interface
  *
  * DESCRIPTION
  *
@@ -25,7 +25,7 @@
  * 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 is not thread-safe.  If the same cache context must be 
+ * SILC ID Cache is not thread-safe.  If the same cache context must be
  * used in multithreaded environment concurrency control must be employed.
  *
  ***/
@@ -33,7 +33,7 @@
 #ifndef SILCIDCACHE_H
 #define SILCIDCACHE_H
 
-/****s* silcidcache/SilcIDCacheAPI/SilcIDCacheEntry
+/****s* silcapputil/SilcIDCacheAPI/SilcIDCacheEntry
  *
  * NAME
  *
@@ -55,7 +55,7 @@ typedef struct SilcIDCacheEntryStruct {
 } *SilcIDCacheEntry;
 /***/
 
-/****s* silcidcache/SilcIDCacheAPI/SilcIDCache
+/****s* silcapputil/SilcIDCacheAPI/SilcIDCache
  *
  * NAME
  *
@@ -71,7 +71,7 @@ typedef struct SilcIDCacheEntryStruct {
  ***/
 typedef struct SilcIDCacheStruct *SilcIDCache;
 
-/****f* silcidcache/SilcIDCacheAPI/SilcIDCacheDestructor
+/****f* silcapputil/SilcIDCacheAPI/SilcIDCacheDestructor
  *
  * SYNOPSIS
  *
@@ -94,7 +94,7 @@ typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
 
 /* Prototypes */
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_alloc
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_alloc
  *
  * SYNOPSIS
  *
@@ -115,7 +115,7 @@ SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
                               SilcIDCacheDestructor destructor,
                               void *destructor_context);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_free
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_free
  *
  * SYNOPSIS
  *
@@ -128,7 +128,7 @@ SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
  ***/
 void silc_idcache_free(SilcIDCache cache);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_add
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_add
  *
  * SYNOPSIS
  *
@@ -140,17 +140,14 @@ void silc_idcache_free(SilcIDCache 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.
+ *    `context' a caller specific context.  The caller is responsible of
+ *    freeing the `name' and `id' when the entry is deleted.
  *
  ***/
 SilcIDCacheEntry
 silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_del
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_del
  *
  * SYNOPSIS
  *
@@ -167,7 +164,7 @@ silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
 SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry,
                          void *app_context);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_del_by_id
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_del_by_id
  *
  * SYNOPSIS
  *
@@ -184,7 +181,7 @@ SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry,
 SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id,
                                void *app_context);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_del_by_context
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_del_by_context
  *
  * SYNOPSIS
  *
@@ -200,29 +197,68 @@ SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id,
 SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context,
                                     void *app_context);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_update_id
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_update
  *
  * SYNOPSIS
  *
  *    SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
- *                                 void *old_id, void *new_id,
- *                                 char *old_name, char *new_name);
+ *                                 void *new_id, char *new_name,
+ *                                 SilcBool free_old_name);
  *
  * DESCRIPTION
  *
  *    Updates cache `entry' with new values.  If the `new_id' is non-NULL
- *    then the new value will be copied over the old value in the `entry'.
+ *    then the new value will be copied over the old value in the `entry'
+ *    unless the ID doesn't exist, when the `new_id' will be stored in `entry'.
  *    If the `new_name' is non-NULL then the `entry' will be updated with
  *    `new_name'.  The caller is responsible of freeing the old name if it
  *    was updated with new one.  The old ID value does not need to be freed
- *    as the new value is copied over the old value.
+ *    as the new value is copied over the old value.  If the `free_old_name'
+ *    is TRUE the library will free the old name from the entry.
  *
  ***/
 SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
-                            void *old_id, void *new_id,
-                            char *old_name, char *new_name);
+                            void *new_id, char *new_name,
+                            SilcBool free_old_name);
+
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_update_by_context
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool
+ *    silc_idcache_update_by_context(SilcIDCache cache, void *context,
+ *                                   void *new_id, char *new_name,
+ *                                   SilcBool free_old_name);
+ *
+ * DESCRIPTION
+ *
+ *    Same as silc_idcache_update but finds the corrent ID cache entry by
+ *    the `context' added to the ID cache.
+ *
+ ***/
+SilcBool silc_idcache_update_by_context(SilcIDCache cache, void *context,
+                                       void *new_id, char *new_name,
+                                       SilcBool free_old_name);
+
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_move
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_idcache_move(SilcIDCache from_cache, SilcIDCache to_cache,
+ *                               SilcIDCacheEntry entry);
+ *
+ * DESCRIPTION
+ *
+ *    Moves the ID cache entry indicated by `entry' from the `from_cache'
+ *    to `to_cache'.  After this returns TRUE the `entry' is available only
+ *    from the `to_cache'.  Return FALSE if `entry' is not in `from_cache'
+ *    or system is out of memory.
+ *
+ ***/
+SilcBool silc_idcache_move(SilcIDCache from_cache, SilcIDCache to_cache,
+                          SilcIDCacheEntry entry);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_get_all
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_get_all
  *
  * SYNOPSIS
  *
@@ -237,7 +273,7 @@ SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
  ***/
 SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_find_by_id
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_id
  *
  * SYNOPSIS
  *
@@ -265,7 +301,7 @@ SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
 SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
                                 SilcList *ret_list);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_find_by_id_one
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_id_one
  *
  * SYNOPSIS
  *
@@ -282,7 +318,7 @@ SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
 SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
                                     SilcIDCacheEntry *ret);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_find_by_context
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_context
  *
  * SYNOPSIS
  *
@@ -298,7 +334,7 @@ SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
 SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
                                      SilcIDCacheEntry *ret);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_find_by_name
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_name
  *
  * SYNOPSIS
  *
@@ -315,7 +351,7 @@ SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
 SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
                                   SilcList *ret_list);
 
-/****f* silcidcache/SilcIDCacheAPI/silc_idcache_find_by_name_one
+/****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_name_one
  *
  * SYNOPSIS
  *