Merged silc_1_0_branch to trunk.

[silc.git] / lib / silcutil / silchashtable.h

diff --git a/lib/silcutil/silchashtable.h b/lib/silcutil/silchashtable.h
index 2b186c957301757bb095b634dfc95d7aa0b58c1d..478ea184a6a23128f8d710c899bb26a4de2a151b 100644 (file)
--- a/lib/silcutil/silchashtable.h
+++ b/lib/silcutil/silchashtable.h
@@ -17,7 +17,7 @@
 
 */
 
-/****h* silcutil/SilcHashTableAPI
+/****h* silcutil/SILC Hash Table Interface
  *
  * DESCRIPTION
  *
@@ -33,7 +33,7 @@
  * an extended interface where caller can specify its own hash and comparison
  * functions.
  *
- * There are two ways tro traverse the entire hash table if this feature
+ * There are two ways to traverse the entire hash table if this feature
  * is needed. There exists a foreach function that calls a foreach
  * callback for each entry in the hash table. Other way is to use
  * SilcHashTableList structure and traverse the hash table inside while()
@@ -89,8 +89,8 @@ typedef struct SilcHashTableListStruct SilcHashTableList;
 struct SilcHashTableListStruct {
   SilcHashTable ht;
   void *entry;
-  SilcUInt32 index;
-  bool auto_rehash;
+  unsigned int index        : 31;
+  unsigned int auto_rehash  : 1;
 };
 /***/
 
@@ -138,7 +138,7 @@ typedef bool (*SilcHashCompare)(void *key1, void *key2, void *user_context);
  * DESCRIPTION
  *
  *    A destructor callback that the library will call to destroy the 
- *    `key' and `context'.  The appliation provides the function when
+ *    `key' and `context'.  The application provides the function when
  *    allocating a new hash table. The `user_context' is application
  *    specific context and is delivered to the callback.
  *
@@ -324,6 +324,27 @@ bool silc_hash_table_del_by_context(SilcHashTable ht, void *key,
 bool silc_hash_table_find(SilcHashTable ht, void *key,
                          void **ret_key, void **ret_context);
 
+/****f* silcutil/SilcHashTableAPI/silc_hash_table_find_by_context
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_hash_table_find_by_context(SilcHashTable ht, void *key,
+ *                                         void *context, void **ret_key);
+ *
+ * DESCRIPTION
+ *
+ *    Finds the entry in the hash table by the provided `key' and
+ *    `context' as fast as possible.  This is handy function when there
+ *    can be multiple same keys in the hash table.  By using this function
+ *    the specific key with specific context can be found.  Return
+ *    TRUE if the entry with the key and context was found and FALSE
+ *    otherwise.  The function returns only the key to `ret_key' since
+ *    the caller already knows the context.
+ *
+ ***/
+bool silc_hash_table_find_by_context(SilcHashTable ht, void *key,
+                                    void *context, void **ret_key);
+
 /****f* silcutil/SilcHashTableAPI/silc_hash_table_find_foreach
  *
  * SYNOPSIS
@@ -337,7 +358,9 @@ bool silc_hash_table_find(SilcHashTable ht, void *key,
  *    As the hash table is collision resistant it is possible to save duplicate
  *    keys to the hash table. This function can be used to find all keys
  *    and contexts from the hash table that are found using the `key'. The
- *    `foreach' is called for every found key.
+ *    `foreach' is called for every found key. If no entries can be found
+ *    the `foreach' will be called once with the context set NULL and
+ *    `key' and `user_context' sent to the function.
  *
  * NOTES
  *
@@ -609,7 +632,9 @@ bool silc_hash_table_find_ext(SilcHashTable ht, void *key,
  *    As the hash table is collision resistant it is possible to save duplicate
  *    keys to the hash table. This function can be used to find all keys
  *    and contexts from the hash table that are found using the `key'. The
- *    `foreach' is called for every found key.
+ *    `foreach' is called for every found key. If no entries can be found
+ *    the `foreach' will be called once with the context set NULL and
+ *    `key' and `user_context' sent to the function.
  *
  *    The `hash' and `hash_user_context' are application specified hash
  *    function. If not provided the hash table's default is used.