lib/silccore/silcidcache.h

   1 /*
   2
   3   silcidcache.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2000 - 2005 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silccore/SILC ID Cache Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC ID Cache is an cache for all kinds of ID's used in the SILC
  25  * protocol.  Application can save here the ID's it uses and the interface
  26  * provides fast retrieval of the ID's from the cache.
  27  *
  28  ***/
  29
  30 #ifndef SILCIDCACHE_H
  31 #define SILCIDCACHE_H
  32
  33 /****s* silccore/SilcIDCacheAPI/SilcIDCacheEntry
  34  *
  35  * NAME
  36  *
  37  *    typedef struct SilcIDCacheEntryStruct { ... } SilcIDCacheEntry;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This is an entry in the SILC ID Cache system.  This context is
  42  *    allocated by adding new entry to ID cache by calling silc_idcache_add.
  43  *    Each of the fields in the structure are allocated by the caller.
  44  *
  45  * SOURCE
  46  */
  47 typedef struct SilcIDCacheEntryStruct {
  48   struct SilcIDCacheEntryStruct *next;
  49   void *id;                            /* Associated ID */
  50   char *name;                          /* Associated entry name */
  51   void *context;                       /* Associated context */
  52 } *SilcIDCacheEntry;
  53 /***/
  54
  55 /****s* silccore/SilcIDCacheAPI/SilcIDCache
  56  *
  57  * NAME
  58  *
  59  *    typedef struct SilcIDCacheStruct *SilcIDCache;
  60  *
  61  * DESCRIPTION
  62  *
  63  *    This context is the actual ID Cache and is allocated by
  64  *    silc_idcache_alloc and given as argument usually to all
  65  *    silc_idcache_* functions.  It is freed by the
  66  *    silc_idcache_free function.
  67  *
  68  ***/
  69 typedef struct SilcIDCacheStruct *SilcIDCache;
  70
  71 /****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor
  72  *
  73  * SYNOPSIS
  74  *
  75  *    typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
  76  *                                          const SilcIDCacheEntry entry,
  77  *                                          void *destructor_context,
  78  *                                          void *app_context);
  79  *
  80  * DESCRIPTION
  81  *
  82  *    Destructor callback given as argument to silc_idcache_alloc.  This
  83  *    is called when an entry is deleted from the cache.  Application
  84  *    must free the contents of the `entry'.
  85  *
  86  ***/
  87 typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
  88                                       const SilcIDCacheEntry entry,
  89                                       void *destructor_context,
  90                                       void *app_context);
  91
  92 /* Prototypes */
  93
  94 /****f* silccore/SilcIDCacheAPI/silc_idcache_alloc
  95  *
  96  * SYNOPSIS
  97  *
  98  *    SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
  99  *                                   SilcIDCacheDestructor destructor,
 100  *                                   void *destructor_context,
 101  *                                   SilcBool delete_id, SilcBool delete_name);
 102  *
 103  * DESCRIPTION
 104  *
 105  *    Allocates new ID cache object. The initial amount of allocated entries
 106  *    can be sent as argument. If `count' is 0 the system uses default values.
 107  *    The `id_type' defines the types of the ID's that will be saved to the
 108  *    cache.
 109  *
 110  ***/
 111 SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
 112                                SilcIDCacheDestructor destructor,
 113                                void *destructor_context);
 114
 115 /****f* silccore/SilcIDCacheAPI/silc_idcache_free
 116  *
 117  * SYNOPSIS
 118  *
 119  *    void silc_idcache_free(SilcIDCache cache);
 120  *
 121  * DESCRIPTION
 122  *
 123  *    Frees ID cache context and all cache entries.
 124  *
 125  ***/
 126 void silc_idcache_free(SilcIDCache cache);
 127
 128 /****f* silccore/SilcIDCacheAPI/silc_idcache_add
 129  *
 130  * SYNOPSIS
 131  *
 132  *    SilcIDCacheEntry
 133  *    silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Add new entry to the cache.  Returns the allocated cache entry if the
 138  *    entry was added successfully, or NULL if error occurred.  The `name' is
 139  *    the name associated with the ID, the `id' the actual ID and the
 140  *    `context' a caller specific context.
 141  *
 142  *    The `name', `id' and `context' pointers will be stored in the cache,
 143  *    and if the caller frees these pointers the caller is also responsible
 144  *    of deleting the cache entry.
 145  *
 146  ***/
 147 SilcIDCacheEntry
 148 silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
 149
 150 /****f* silccore/SilcIDCacheAPI/silc_idcache_del
 151  *
 152  * SYNOPSIS
 153  *
 154  *    SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry,
 155  *                              void *app_context);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Delete cache entry from cache.  Returns TRUE if the entry was deleted.
 160  *    The destructor will be called for the entry.  The `app_context' is
 161  *    delivered to the destructor.
 162  *
 163  ***/
 164 SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry,
 165                           void *app_context);
 166
 167 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id
 168  *
 169  * SYNOPSIS
 170  *
 171  *    SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id,
 172  *                                    void *app_context);
 173  *
 174  * DESCRIPTION
 175  *
 176  *    Delete cache entry by ID.  Returns TRUE if the entry was deleted.
 177  *    The destructor will be called for the entry.  The `app_context' is
 178  *    delivered to the destructor.
 179  *
 180  ***/
 181 SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id,
 182                                 void *app_context);
 183
 184 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context
 185  *
 186  * SYNOPSIS
 187  *
 188  *    SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    Deletes cachen entry by the user specified context.  Returns TRUE
 193  *    if the entry was deleted.  The destructor will be called for the
 194  *    entry.  The `app_context' is delivered to the destructor.
 195  *
 196  ***/
 197 SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context,
 198                                      void *app_context);
 199
 200 /****f* silccore/SilcIDCacheAPI/silc_idcache_update_id
 201  *
 202  * SYNOPSIS
 203  *
 204  *    SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
 205  *                                 void *old_id, void *new_id,
 206  *                                 char *old_name, char *new_name);
 207  *
 208  * DESCRIPTION
 209  *
 210  *    Updates cache `entry' with new values.  If the `new_id' is non-NULL
 211  *    then the `entry' will be updated with `new_id'.  If the `new_name' is
 212  *    non-NULL then the `entry' will be updated with `new_name'.  The
 213  *    caller is responsible of freeing the old values that was added with
 214  *    silc_idcache_add.
 215  *
 216  ***/
 217 SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
 218                              void *old_id, void *new_id,
 219                              char *old_name, char *new_name);
 220
 221 /****f* silccore/SilcIDCacheAPI/silc_idcache_get_all
 222  *
 223  * SYNOPSIS
 224  *
 225  *    SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
 226  *
 227  * DESCRIPTION
 228  *
 229  *    Returns all cache entries into the SilcList `ret_list' pointer.  Each
 230  *    entry in the list is SilcIDCacheEntry.  Returns FALSE if the cache
 231  *    is empty.
 232  *
 233  ***/
 234 SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
 235
 236 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id
 237  *
 238  * SYNOPSIS
 239  *
 240  *    SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
 241  *                                     SilcList *ret_list);
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Find ID Cache entry by ID.  This may return multiple entries.
 246  *    The entires are returned into the `ret_list' SilcList context.
 247  *    Returns TRUE if entry was found.
 248  *
 249  * NOTES
 250  *
 251  *    If this function is used to find Client ID (SilcClientID), only the
 252  *    hash portion of the Client ID is compared.  Use the function
 253  *    silc_idcache_find_by_id_one to find exact match for Client ID (full
 254  *    ID is compared and not only the hash).
 255  *
 256  *    Comparing only the hash portion of Client ID allows searching of
 257  *    Client ID's by nickname, because the hash is based on the nickname.
 258  *    As nicknames are not unique, multiple entries may be found.
 259  *
 260  ***/
 261 SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
 262                                  SilcList *ret_list);
 263
 264 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one
 265  *
 266  * SYNOPSIS
 267  *
 268  *     SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
 269  *                                          SilcIDCacheEntry *ret);
 270  *
 271  * DESCRIPTION
 272  *
 273  *    Find ID Cache entry by ID.  Returns only one entry from the cache
 274  *    and the found entry is considered to be exact match.  Returns TRUE
 275  *    if the entry was found.
 276  *
 277  ***/
 278 SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
 279                                      SilcIDCacheEntry *ret);
 280
 281 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context
 282  *
 283  * SYNOPSIS
 284  *
 285  *    SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
 286  *                                      SilcIDCacheEntry *ret);
 287  *
 288  * DESCRIPTION
 289  *
 290  *    Find cache entry by user specified context. Returns TRUE if the
 291  *    entry was found.
 292  *
 293  ***/
 294 SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
 295                                       SilcIDCacheEntry *ret);
 296
 297 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name
 298  *
 299  * SYNOPSIS
 300  *
 301  *    SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
 302  *                                       SilcList *ret_list);
 303  *
 304  * DESCRIPTION
 305  *
 306  *    Find cache entries by the name associated with the ID.  This may
 307  *    return multiple entries to the `ret_list' SilcList context.  Returns
 308  *    TRUE if the entry was found.
 309  *
 310  ***/
 311 SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
 312                                    SilcList *ret_list);
 313
 314 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one
 315  *
 316  * SYNOPSIS
 317  *
 318  *    SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
 319  *                                       SilcIDCacheEntry *ret);
 320  *
 321  * DESCRIPTION
 322  *
 323  *    Find cache entry by the name associated with the ID.  This returns
 324  *    one entry and the found entry is considered to be exact match.
 325  *    Returns TRUE if the entry was found.
 326  *
 327  ***/
 328 SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
 329                                        SilcIDCacheEntry *ret);
 330
 331 #endif /* SILCIDCACHE_H */