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 { ... } SilcIDCacheEntry;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This is one entry in the SILC ID Cache system. Contents of this is
  42  *    allocated outside the ID cache system, however, all the fields are
  43  *    filled with ID cache utility functions. The ID cache system does not
  44  *    allocate any of these fields nor free them.
  45  *
  46  *    void *id
  47  *
  48  *      The actual ID.
  49  *
  50  *    char name
  51  *
  52  *      A name associated with the ID.
  53  *
  54  *    SilcUInt32 expire
  55  *
  56  *      Time when this cache entry expires.  This is normal time() value
  57  *      plus the validity.  Cache entry has expired if current time is
  58  *      more than value in this field.  If this value is zero (0) the
  59  *      entry never expires.
  60  *
  61  *    void *context
  62  *
  63  *      Any caller specified context.
  64  *
  65  * SOURCE
  66  */
  67 typedef struct {
  68   void *id;
  69   char *name;
  70   SilcUInt32 expire;
  71   void *context;
  72 } *SilcIDCacheEntry;
  73 /***/
  74
  75 /****s* silccore/SilcIDCacheAPI/SilcIDCache
  76  *
  77  * NAME
  78  *
  79  *    typedef struct SilcIDCacheStruct *SilcIDCache;
  80  *
  81  * DESCRIPTION
  82  *
  83  *    This context is the actual ID Cache and is allocated by
  84  *    silc_idcache_alloc and given as argument usually to all
  85  *    silc_idcache_* functions.  It is freed by the
  86  *    silc_idcache_free function.
  87  *
  88  ***/
  89 typedef struct SilcIDCacheStruct *SilcIDCache;
  90
  91 /****s* silccore/SilcIDCacheAPI/SilcIDCacheList
  92  *
  93  * NAME
  94  *
  95  *    typedef struct SilcIDCacheListStruct *SilcIDCacheList;
  96  *
  97  * DESCRIPTION
  98  *
  99  *    This context is the ID Cache List and is allocated by
 100  *    some of the silc_idcache_* functions. Functions that may return
 101  *    multiple entries from the cache allocate the entries in to the
 102  *    SilcIDCacheList. The context is freed by silc_idcache_list_free
 103  *    function.
 104  *
 105  ***/
 106 typedef struct SilcIDCacheListStruct *SilcIDCacheList;
 107
 108 /****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor
 109  *
 110  * SYNOPSIS
 111  *
 112  *    typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
 113  *                                          SilcIDCacheEntry entry,
 114  *                                          void *context);
 115  *
 116  * DESCRIPTION
 117  *
 118  *    Destructor callback that is called when an cache entry expires or is
 119  *    purged from the ID cache. The application must not free cache entry
 120  *    because the library will do it automatically. The appliation, however,
 121  *    is responsible of freeing any data in the entry.
 122  *
 123  ***/
 124 typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
 125                                       SilcIDCacheEntry entry,
 126                                       void *context);
 127
 128 #define SILC_ID_CACHE_EXPIRE 3600
 129 #define SILC_ID_CACHE_EXPIRE_DEF (time(NULL) + SILC_ID_CACHE_EXPIRE)
 130
 131 /* Prototypes */
 132
 133 /****f* silccore/SilcIDCacheAPI/silc_idcache_alloc
 134  *
 135  * SYNOPSIS
 136  *
 137  *    SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
 138  *                                   SilcIDCacheDestructor destructor,
 139  *                                   void *destructor_context,
 140  *                                   bool delete_id, bool delete_name);
 141  *
 142  * DESCRIPTION
 143  *
 144  *    Allocates new ID cache object. The initial amount of allocated entries
 145  *    can be sent as argument. If `count' is 0 the system uses default values.
 146  *    The `id_type' defines the types of the ID's that will be saved to the
 147  *    cache.
 148  *
 149  *    If 'delete_id' is TRUE then library will free the ID when a
 150  *    cache entry is deleted.  If 'delete_name' is TRUE then library
 151  *    will delete the associated name when a cache entry is deleted.
 152  *
 153  ***/
 154 SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
 155                                SilcIDCacheDestructor destructor,
 156                                void *destructor_context,
 157                                bool delete_id, bool delete_name);
 158
 159 /****f* silccore/SilcIDCacheAPI/silc_idcache_free
 160  *
 161  * SYNOPSIS
 162  *
 163  *    void silc_idcache_free(SilcIDCache cache);
 164  *
 165  * DESCRIPTION
 166  *
 167  *    Frees ID cache object and all cache entries.
 168  *
 169  ***/
 170 void silc_idcache_free(SilcIDCache cache);
 171
 172 /****f* silccore/SilcIDCacheAPI/silc_idcache_add
 173  *
 174  * SYNOPSIS
 175  *
 176  *    bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
 177  *                          void *context, int expire, SilcIDCacheEntry *ret);
 178  *
 179  * DESCRIPTION
 180  *
 181  *    Add new entry to the cache. Returns TRUE if the entry was added and
 182  *    FALSE if it could not be added. The `name' is the name associated with
 183  *    the ID, the `id' the actual ID and the `context' a user specific context.
 184  *    If the `expire' is non-zero the entry expires in that specified time.
 185  *    If zero the entry never expires from the cache.
 186  *
 187  *    The `name', `id' and `context' pointers will be saved in the cache,
 188  *    and if the caller frees these pointers the caller is also responsible
 189  *    of deleting the cache entry.  Otherwise the cache will have the freed
 190  *    pointers stored.
 191  *
 192  *    If the `ret' is non-NULL the created ID Cache entry is returned to
 193  *    that pointer.
 194  *
 195  ***/
 196 bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
 197                       void *context, int expire, SilcIDCacheEntry *ret);
 198
 199 /****f* silccore/SilcIDCacheAPI/silc_idcache_del
 200  *
 201  * SYNOPSIS
 202  *
 203  *    bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Delete cache entry from cache. Returns TRUE if the entry was deleted.
 208  *    The destructor function is not called.
 209  *
 210  ***/
 211 bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
 212
 213 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id
 214  *
 215  * SYNOPSIS
 216  *
 217  *    bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
 218  *
 219  * DESCRIPTION
 220  *
 221  *    Delete cache entry by ID. Returns TRUE if the entry was deleted.
 222  *    The destructor function is not called.
 223  *
 224  ***/
 225 bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
 226
 227 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id_ext
 228  *
 229  * SYNOPSIS
 230  *
 231  *    bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id,
 232  *                                    SilcHashFunction hash,
 233  *                                    void *hash_context,
 234  *                                    SilcHashCompare compare,
 235  *                                    void *compare_context);
 236  *
 237  * DESCRIPTION
 238  *
 239  *    Same as silc_idcache_del_by_id but with specific hash and comparison
 240  *    functions. If the functions are NULL then default values are used.
 241  *    Returns TRUE if the entry was deleted. The destructor function is
 242  *    called.
 243  *
 244  ***/
 245 bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id,
 246                                 SilcHashFunction hash,
 247                                 void *hash_context,
 248                                 SilcHashCompare compare,
 249                                 void *compare_context);
 250
 251 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context
 252  *
 253  * SYNOPSIS
 254  *
 255  *    bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
 256  *
 257  * DESCRIPTION
 258  *
 259  *    Deletes cachen entry by the user specified context. Returns TRUE
 260  *    if the entry was deleted. The destructor function is not called.
 261  *
 262  ***/
 263 bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
 264
 265 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_all
 266  *
 267  * SYNOPSIS
 268  *
 269  *    bool silc_idcache_del_all(SilcIDCache cache);
 270  *
 271  * DESCRIPTION
 272  *
 273  *    Deletes all cache entries from the cache and frees all memory.
 274  *    The destructor function is not called.
 275  *
 276  ***/
 277 bool silc_idcache_del_all(SilcIDCache cache);
 278
 279 /****f* silccore/SilcIDCacheAPI/silc_idcache_purge
 280  *
 281  * SYNOPSIS
 282  *
 283  *    bool silc_idcache_purge(SilcIDCache cache);
 284  *
 285  * DESCRIPTION
 286  *
 287  *    Purges the cache by removing expired cache entires. Note that this
 288  *    may be very slow operation. Returns TRUE if the purging was successful.
 289  *    The destructor function is called for each purged cache entry.
 290  *
 291  ***/
 292 bool silc_idcache_purge(SilcIDCache cache);
 293
 294 /****f* silccore/SilcIDCacheAPI/silc_idcache_by_context
 295  *
 296  * SYNOPSIS
 297  *
 298  *    bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
 299  *
 300  * DESCRIPTION
 301  *
 302  *    Purges the cache by context and removes expired cache entires.
 303  *    Returns TRUE if the puring was successful. The destructor function
 304  *    is called for the purged cache entry.
 305  *
 306  ***/
 307 bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
 308
 309 /****f* silccore/SilcIDCacheAPI/silc_idcache_get_all
 310  *
 311  * SYNOPSIS
 312  *
 313  *    bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
 314  *
 315  * DESCRIPTION
 316  *
 317  *    Returns all cache entries from the ID cache to the `ret' SilcIDCacheList.
 318  *    Returns TRUE if the retrieval was successful. The caller must free
 319  *    the returned SilcIDCacheList.
 320  *
 321  ***/
 322 bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
 323
 324 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id
 325  *
 326  * SYNOPSIS
 327  *
 328  *    bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
 329  *                                 SilcIDCacheList *ret);
 330  *
 331  * DESCRIPTION
 332  *
 333  *    Find ID Cache entry by ID. This may return multiple entry and the
 334  *    `ret' SilcIDCacheList is allocated. Returns TRUE if the entry was
 335  *    found. The caller must free the returned SilcIDCacheList.
 336  *
 337  ***/
 338 bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
 339                              SilcIDCacheList *ret);
 340
 341 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one
 342  *
 343  * SYNOPSIS
 344  *
 345  *     bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
 346  *                                      SilcIDCacheEntry *ret);
 347  *
 348  * DESCRIPTION
 349  *
 350  *    Find ID Cache entry by ID. Returns only one entry from the cache
 351  *    and the found entry is considered to be exact match. Returns TRUE
 352  *    if the entry was found.
 353  *
 354  ***/
 355 bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
 356                                  SilcIDCacheEntry *ret);
 357
 358 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one_ext
 359  *
 360  * SYNOPSIS
 361  *
 362  *    bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id,
 363  *                                         SilcHashFunction hash,
 364  *                                         void *hash_context,
 365  *                                         SilcHashCompare compare,
 366  *                                         void *compare_context,
 367  *                                         SilcIDCacheEntry *ret);
 368  *
 369  * DESCRIPTION
 370  *
 371  *    Same as silc_idcache_find_by_id_one but with specific hash and
 372  *    comparison functions. If `hash' is NULL then the default hash
 373  *    funtion is used and if `compare' is NULL default comparison function
 374  *    is used. Returns TRUE if the entry was found.
 375  *
 376  ***/
 377 bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id,
 378                                      SilcHashFunction hash,
 379                                      void *hash_context,
 380                                      SilcHashCompare compare,
 381                                      void *compare_context,
 382                                      SilcIDCacheEntry *ret);
 383
 384 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context
 385  *
 386  * SYNOPSIS
 387  *
 388  *    bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
 389  *                                      SilcIDCacheEntry *ret);
 390  *
 391  * DESCRIPTION
 392  *
 393  *    Find cache entry by user specified context. Returns TRUE if the
 394  *    entry was found.
 395  *
 396  ***/
 397 bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
 398                                   SilcIDCacheEntry *ret);
 399
 400 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name
 401  *
 402  * SYNOPSIS
 403  *
 404  *    bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
 405  *                                   SilcIDCacheList *ret);
 406  *
 407  * DESCRIPTION
 408  *
 409  *    Find cache entries by the name associated with the ID. This may
 410  *    return muliptle entries allocated to the SilcIDCacheList. Returns
 411  *    TRUE if the entry was found. The caller must free the SIlcIDCacheList.
 412  *
 413  ***/
 414 bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
 415                                SilcIDCacheList *ret);
 416
 417 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one
 418  *
 419  * SYNOPSIS
 420  *
 421  *    bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
 422  *                                       SilcIDCacheEntry *ret);
 423  *
 424  * DESCRIPTION
 425  *
 426  *    Find cache entry by the name associated with the ID. This returns
 427  *    one entry and the found entry is considered to be exact match.
 428  *    return muliptle entries allocated to the SilcIDCacheList. Returns
 429  *    TRUE if the entry was found.
 430  *
 431  ***/
 432 bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
 433                                    SilcIDCacheEntry *ret);
 434
 435 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_count
 436  *
 437  * SYNOPSIS
 438  *
 439  *    int silc_idcache_list_count(SilcIDCacheList list);
 440  *
 441  * DESCRIPTION
 442  *
 443  *    Returns the number of cache entries in the ID cache list.
 444  *
 445  ***/
 446 int silc_idcache_list_count(SilcIDCacheList list);
 447
 448 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_first
 449  *
 450  * SYNOPSIS
 451  *
 452  *    bool silc_idcache_list_first(SilcIDCacheList list,
 453  *                                 SilcIDCacheEntry *ret);
 454  *
 455  * DESCRIPTION
 456  *
 457  *    Returns the first cache entry from the ID cache list. Returns FALSE
 458  *    If the entry could not be retrieved.
 459  *
 460  ***/
 461 bool silc_idcache_list_first(SilcIDCacheList list, SilcIDCacheEntry *ret);
 462
 463 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_next
 464  *
 465  * SYNOPSIS
 466  *
 467  *    bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
 468  *
 469  * DESCRIPTION
 470  *
 471  *    Returns the next cache entry from the ID Cache list. Returns FALSE
 472  *    when there are not anymore entries in the list.
 473  *
 474  ***/
 475 bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
 476
 477 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_free
 478  *
 479  * SYNOPSIS
 480  *
 481  *    void silc_idcache_list_free(SilcIDCacheList list);
 482  *
 483  * DESCRIPTION
 484  *
 485  *     Frees ID cache list. User must free the list context returned by
 486  *     any of the searching functions.
 487  *
 488  ***/
 489 void silc_idcache_list_free(SilcIDCacheList list);
 490
 491 #endif