5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2000 - 2005 Pekka Riikonen
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.
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.
21 /****h* silccore/SILC ID Cache Interface
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.
34 /****s* silccore/SilcIDCacheAPI/SilcIDCacheEntry
38 * typedef struct { ... } SilcIDCacheEntry;
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.
53 * A name associated with the ID.
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.
64 * Any caller specified context.
76 /****s* silccore/SilcIDCacheAPI/SilcIDCache
80 * typedef struct SilcIDCacheStruct *SilcIDCache;
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.
90 typedef struct SilcIDCacheStruct *SilcIDCache;
92 /****s* silccore/SilcIDCacheAPI/SilcIDCacheList
96 * typedef struct SilcIDCacheListStruct *SilcIDCacheList;
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
107 typedef struct SilcIDCacheListStruct *SilcIDCacheList;
109 /****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor
113 * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
114 * SilcIDCacheEntry entry,
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.
125 typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
126 SilcIDCacheEntry entry,
129 #define SILC_ID_CACHE_EXPIRE 3600
130 #define SILC_ID_CACHE_EXPIRE_DEF (time(NULL) + SILC_ID_CACHE_EXPIRE)
134 /****f* silccore/SilcIDCacheAPI/silc_idcache_alloc
138 * SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
139 * SilcIDCacheDestructor destructor,
140 * void *destructor_context,
141 * bool delete_id, bool delete_name);
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
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.
155 SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
156 SilcIDCacheDestructor destructor,
157 void *destructor_context,
158 bool delete_id, bool delete_name);
160 /****f* silccore/SilcIDCacheAPI/silc_idcache_free
164 * void silc_idcache_free(SilcIDCache cache);
168 * Frees ID cache object and all cache entries.
171 void silc_idcache_free(SilcIDCache cache);
173 /****f* silccore/SilcIDCacheAPI/silc_idcache_add
177 * bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
178 * void *context, int expire, SilcIDCacheEntry *ret);
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.
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
193 * If the `ret' is non-NULL the created ID Cache entry is returned to
197 bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
198 void *context, int expire, SilcIDCacheEntry *ret);
200 /****f* silccore/SilcIDCacheAPI/silc_idcache_del
204 * bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
208 * Delete cache entry from cache. Returns TRUE if the entry was deleted.
209 * The destructor function is not called.
212 bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
214 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id
218 * bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
222 * Delete cache entry by ID. Returns TRUE if the entry was deleted.
223 * The destructor function is not called.
226 bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
228 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id_ext
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);
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
246 bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id,
247 SilcHashFunction hash,
249 SilcHashCompare compare,
250 void *compare_context);
252 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context
256 * bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
260 * Deletes cachen entry by the user specified context. Returns TRUE
261 * if the entry was deleted. The destructor function is not called.
264 bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
266 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_all
270 * bool silc_idcache_del_all(SilcIDCache cache);
274 * Deletes all cache entries from the cache and frees all memory.
275 * The destructor function is not called.
278 bool silc_idcache_del_all(SilcIDCache cache);
280 /****f* silccore/SilcIDCacheAPI/silc_idcache_purge
284 * bool silc_idcache_purge(SilcIDCache cache);
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.
293 bool silc_idcache_purge(SilcIDCache cache);
295 /****f* silccore/SilcIDCacheAPI/silc_idcache_by_context
299 * bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
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.
308 bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
310 /****f* silccore/SilcIDCacheAPI/silc_idcache_get_all
314 * bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
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.
323 bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
325 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id
329 * bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
330 * SilcIDCacheList *ret);
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.
339 bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
340 SilcIDCacheList *ret);
342 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one
346 * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
347 * SilcIDCacheEntry *ret);
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.
356 bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
357 SilcIDCacheEntry *ret);
359 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one_ext
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);
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.
378 bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id,
379 SilcHashFunction hash,
381 SilcHashCompare compare,
382 void *compare_context,
383 SilcIDCacheEntry *ret);
385 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context
389 * bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
390 * SilcIDCacheEntry *ret);
394 * Find cache entry by user specified context. Returns TRUE if the
398 bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
399 SilcIDCacheEntry *ret);
401 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name
405 * bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
406 * SilcIDCacheList *ret);
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.
415 bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
416 SilcIDCacheList *ret);
418 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one
422 * bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
423 * SilcIDCacheEntry *ret);
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.
433 bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
434 SilcIDCacheEntry *ret);
436 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_count
440 * int silc_idcache_list_count(SilcIDCacheList list);
444 * Returns the number of cache entries in the ID cache list.
447 int silc_idcache_list_count(SilcIDCacheList list);
449 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_first
453 * bool silc_idcache_list_first(SilcIDCacheList list,
454 * SilcIDCacheEntry *ret);
458 * Returns the first cache entry from the ID cache list. Returns FALSE
459 * If the entry could not be retrieved.
462 bool silc_idcache_list_first(SilcIDCacheList list, SilcIDCacheEntry *ret);
464 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_next
468 * bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
472 * Returns the next cache entry from the ID Cache list. Returns FALSE
473 * when there are not anymore entries in the list.
476 bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
478 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_free
482 * void silc_idcache_list_free(SilcIDCacheList list);
486 * Frees ID cache list. User must free the list context returned by
487 * any of the searching functions.
490 void silc_idcache_list_free(SilcIDCacheList list);