lib/silcapputil/silcidcache.h

   1 /*
   2
   3   silcidcache.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2000 - 2008 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* silcapputil/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  * SILC ID Cache is not thread-safe.  If the same cache context must be
  29  * used in multithreaded environment concurrency control must be employed.
  30  *
  31  ***/
  32
  33 #ifndef SILCIDCACHE_H
  34 #define SILCIDCACHE_H
  35
  36 /****s* silcapputil/SilcIDCacheAPI/SilcIDCacheEntry
  37  *
  38  * NAME
  39  *
  40  *    typedef struct SilcIDCacheEntryStruct { ... } SilcIDCacheEntry;
  41  *
  42  * DESCRIPTION
  43  *
  44  *    This is an entry in the SILC ID Cache system.  This context is
  45  *    allocated by adding new entry to ID cache by calling silc_idcache_add.
  46  *    Each of the fields in the structure are allocated by the caller.
  47  *
  48  * SOURCE
  49  */
  50 typedef struct SilcIDCacheEntryStruct {
  51   struct SilcIDCacheEntryStruct *next;
  52   void *id;                            /* Associated ID */
  53   char *name;                          /* Associated entry name */
  54   void *context;                       /* Associated context */
  55 } *SilcIDCacheEntry;
  56 /***/
  57
  58 /****s* silcapputil/SilcIDCacheAPI/SilcIDCache
  59  *
  60  * NAME
  61  *
  62  *    typedef struct SilcIDCacheStruct *SilcIDCache;
  63  *
  64  * DESCRIPTION
  65  *
  66  *    This context is the actual ID Cache and is allocated by
  67  *    silc_idcache_alloc and given as argument usually to all
  68  *    silc_idcache_* functions.  It is freed by the
  69  *    silc_idcache_free function.
  70  *
  71  ***/
  72 typedef struct SilcIDCacheStruct *SilcIDCache;
  73
  74 /****f* silcapputil/SilcIDCacheAPI/SilcIDCacheDestructor
  75  *
  76  * SYNOPSIS
  77  *
  78  *    typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
  79  *                                          const SilcIDCacheEntry entry,
  80  *                                          void *destructor_context,
  81  *                                          void *app_context);
  82  *
  83  * DESCRIPTION
  84  *
  85  *    Destructor callback given as argument to silc_idcache_alloc.  This
  86  *    is called when an entry is deleted from the cache.  Application
  87  *    must free the contents of the `entry'.
  88  *
  89  ***/
  90 typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
  91                                       const SilcIDCacheEntry entry,
  92                                       void *destructor_context,
  93                                       void *app_context);
  94
  95 /* Prototypes */
  96
  97 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_alloc
  98  *
  99  * SYNOPSIS
 100  *
 101  *    SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
 102  *                                   SilcIDCacheDestructor destructor,
 103  *                                   void *destructor_context,
 104  *                                   SilcBool delete_id, SilcBool delete_name);
 105  *
 106  * DESCRIPTION
 107  *
 108  *    Allocates new ID cache object. The initial amount of allocated entries
 109  *    can be sent as argument. If `count' is 0 the system uses default values.
 110  *    The `id_type' defines the types of the ID's that will be saved to the
 111  *    cache.
 112  *
 113  ***/
 114 SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
 115                                SilcIDCacheDestructor destructor,
 116                                void *destructor_context);
 117
 118 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_free
 119  *
 120  * SYNOPSIS
 121  *
 122  *    void silc_idcache_free(SilcIDCache cache);
 123  *
 124  * DESCRIPTION
 125  *
 126  *    Frees ID cache context and all cache entries.
 127  *
 128  ***/
 129 void silc_idcache_free(SilcIDCache cache);
 130
 131 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_add
 132  *
 133  * SYNOPSIS
 134  *
 135  *    SilcIDCacheEntry
 136  *    silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Add new entry to the cache.  Returns the allocated cache entry if the
 141  *    entry was added successfully, or NULL if error occurred.  The `name' is
 142  *    the name associated with the ID, the `id' the actual ID and the
 143  *    `context' a caller specific context.  The caller is responsible of
 144  *    freeing the `name' and `id' when the entry is deleted.
 145  *
 146  ***/
 147 SilcIDCacheEntry
 148 silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
 149
 150 /****f* silcapputil/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* silcapputil/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* silcapputil/SilcIDCacheAPI/silc_idcache_del_by_context
 185  *
 186  * SYNOPSIS
 187  *
 188  *    SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context,
 189  *                                         void *app_context);
 190  *
 191  * DESCRIPTION
 192  *
 193  *    Deletes cachen entry by the user specified context.  Returns TRUE
 194  *    if the entry was deleted.  The destructor will be called for the
 195  *    entry.  The `app_context' is delivered to the destructor.
 196  *
 197  ***/
 198 SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context,
 199                                      void *app_context);
 200
 201 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_update
 202  *
 203  * SYNOPSIS
 204  *
 205  *    SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
 206  *                                 void *new_id, char *new_name,
 207  *                                 SilcBool free_old_name);
 208  *
 209  * DESCRIPTION
 210  *
 211  *    Updates cache `entry' with new values.  If the `new_id' is non-NULL
 212  *    then the new value will be copied over the old value in the `entry'
 213  *    unless the ID doesn't exist, when the `new_id' will be stored in `entry'.
 214  *    If the `new_name' is non-NULL then the `entry' will be updated with
 215  *    `new_name'.  The caller is responsible of freeing the old name if it
 216  *    was updated with new one.  The old ID value does not need to be freed
 217  *    as the new value is copied over the old value.  If the `free_old_name'
 218  *    is TRUE the library will free the old name from the entry.
 219  *
 220  ***/
 221 SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
 222                              void *new_id, char *new_name,
 223                              SilcBool free_old_name);
 224
 225 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_update_by_context
 226  *
 227  * SYNOPSIS
 228  *
 229  *    SilcBool
 230  *    silc_idcache_update_by_context(SilcIDCache cache, void *context,
 231  *                                   void *new_id, char *new_name,
 232  *                                   SilcBool free_old_name);
 233  *
 234  * DESCRIPTION
 235  *
 236  *    Same as silc_idcache_update but finds the corrent ID cache entry by
 237  *    the `context' added to the ID cache.
 238  *
 239  ***/
 240 SilcBool silc_idcache_update_by_context(SilcIDCache cache, void *context,
 241                                         void *new_id, char *new_name,
 242                                         SilcBool free_old_name);
 243
 244 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_move
 245  *
 246  * SYNOPSIS
 247  *
 248  *    SilcBool silc_idcache_move(SilcIDCache from_cache, SilcIDCache to_cache,
 249  *                               SilcIDCacheEntry entry);
 250  *
 251  * DESCRIPTION
 252  *
 253  *    Moves the ID cache entry indicated by `entry' from the `from_cache'
 254  *    to `to_cache'.  After this returns TRUE the `entry' is available only
 255  *    from the `to_cache'.  Return FALSE if `entry' is not in `from_cache'
 256  *    or system is out of memory.
 257  *
 258  ***/
 259 SilcBool silc_idcache_move(SilcIDCache from_cache, SilcIDCache to_cache,
 260                            SilcIDCacheEntry entry);
 261
 262 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_get_all
 263  *
 264  * SYNOPSIS
 265  *
 266  *    SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
 267  *
 268  * DESCRIPTION
 269  *
 270  *    Returns all cache entries into the SilcList `ret_list' pointer.  Each
 271  *    entry in the list is SilcIDCacheEntry.  Returns FALSE if the cache
 272  *    is empty.
 273  *
 274  ***/
 275 SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
 276
 277 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_id
 278  *
 279  * SYNOPSIS
 280  *
 281  *    SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
 282  *                                     SilcList *ret_list);
 283  *
 284  * DESCRIPTION
 285  *
 286  *    Find ID Cache entry by ID.  This may return multiple entries.
 287  *    The entires are returned into the `ret_list' SilcList context.
 288  *    Returns TRUE if entry was found.
 289  *
 290  * NOTES
 291  *
 292  *    If this function is used to find Client ID (SilcClientID), only the
 293  *    hash portion of the Client ID is compared.  Use the function
 294  *    silc_idcache_find_by_id_one to find exact match for Client ID (full
 295  *    ID is compared and not only the hash).
 296  *
 297  *    Comparing only the hash portion of Client ID allows searching of
 298  *    Client ID's by nickname, because the hash is based on the nickname.
 299  *    As nicknames are not unique, multiple entries may be found.
 300  *
 301  ***/
 302 SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
 303                                  SilcList *ret_list);
 304
 305 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_id_one
 306  *
 307  * SYNOPSIS
 308  *
 309  *     SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
 310  *                                          SilcIDCacheEntry *ret);
 311  *
 312  * DESCRIPTION
 313  *
 314  *    Find ID Cache entry by ID.  Returns only one entry from the cache
 315  *    and the found entry is considered to be exact match.  Returns TRUE
 316  *    if the entry was found.
 317  *
 318  ***/
 319 SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
 320                                      SilcIDCacheEntry *ret);
 321
 322 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_context
 323  *
 324  * SYNOPSIS
 325  *
 326  *    SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
 327  *                                      SilcIDCacheEntry *ret);
 328  *
 329  * DESCRIPTION
 330  *
 331  *    Find cache entry by user specified context. Returns TRUE if the
 332  *    entry was found.
 333  *
 334  ***/
 335 SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
 336                                       SilcIDCacheEntry *ret);
 337
 338 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_name
 339  *
 340  * SYNOPSIS
 341  *
 342  *    SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
 343  *                                       SilcList *ret_list);
 344  *
 345  * DESCRIPTION
 346  *
 347  *    Find cache entries by the name associated with the ID.  This may
 348  *    return multiple entries to the `ret_list' SilcList context.  Returns
 349  *    TRUE if the entry was found.
 350  *
 351  ***/
 352 SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
 353                                    SilcList *ret_list);
 354
 355 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_name_one
 356  *
 357  * SYNOPSIS
 358  *
 359  *    SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
 360  *                                       SilcIDCacheEntry *ret);
 361  *
 362  * DESCRIPTION
 363  *
 364  *    Find cache entry by the name associated with the ID.  This returns
 365  *    one entry and the found entry is considered to be exact match.
 366  *    Returns TRUE if the entry was found.
 367  *
 368  ***/
 369 SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
 370                                        SilcIDCacheEntry *ret);
 371
 372 #endif /* SILCIDCACHE_H */