lib/silccore/silcidcache.h

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