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