7 Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
9 Copyright (C) 2000 - 2001 Pekka Riikonen
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.
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.
23 /****h* silccore/silcidcache.h
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.
36 /****s* silccore/SilcIDCacheAPI/SilcIDCacheEntry
40 * typedef struct { ... } SilcIDCacheEntry;
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.
55 * A name associated with the ID.
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.
66 * Any caller specified context.
78 /****s* silccore/SilcIDCacheAPI/SilcIDCache
82 * typedef struct SilcIDCacheStruct *SilcIDCache;
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.
92 typedef struct SilcIDCacheStruct *SilcIDCache;
94 /****s* silccore/SilcIDCacheAPI/SilcIDCacheList
98 * typedef struct SilcIDCacheListStruct *SilcIDCacheList;
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
109 typedef struct SilcIDCacheListStruct *SilcIDCacheList;
111 /****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor
115 * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
116 * SilcIDCacheEntry entry);
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.
126 typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
127 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(uint32 count, SilcIdType id_type,
139 * SilcIDCacheDestructor destructor);
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
149 SilcIDCache silc_idcache_alloc(uint32 count, SilcIdType id_type,
150 SilcIDCacheDestructor destructor);
152 /****f* silccore/SilcIDCacheAPI/silc_idcache_free
156 * void silc_idcache_free(SilcIDCache cache);
160 * Frees ID cache object and all cache entries.
163 void silc_idcache_free(SilcIDCache cache);
165 /****f* silccore/SilcIDCacheAPI/silc_idcache_add
169 * bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
170 * void *context, int expire);
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.
181 bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
182 void *context, int expire);
184 /****f* silccore/SilcIDCacheAPI/silc_idcache_del
188 * bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
192 * Delete cache entry from cache. Returns TRUE if the entry was deleted.
193 * The destructor function is not called.
196 bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
198 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id
202 * bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
206 * Delete cache entry by ID. Returns TRUE if the entry was deleted.
207 * The destructor function is not called.
210 bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
212 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id_ext
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);
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
230 bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id,
231 SilcHashFunction hash,
233 SilcHashCompare compare,
234 void *compare_context);
236 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context
240 * bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
244 * Deletes cachen entry by the user specified context. Returns TRUE
245 * if the entry was deleted. The destructor function is not called.
248 bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
250 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_all
254 * bool silc_idcache_del_all(SilcIDCache cache);
258 * Deletes all cache entries from the cache and frees all memory.
259 * The destructor function is not called.
262 bool silc_idcache_del_all(SilcIDCache cache);
264 /****f* silccore/SilcIDCacheAPI/silc_idcache_purge
268 * bool silc_idcache_purge(SilcIDCache cache);
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.
277 bool silc_idcache_purge(SilcIDCache cache);
279 /****f* silccore/SilcIDCacheAPI/silc_idcache_by_context
283 * bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
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.
292 bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
294 /****f* silccore/SilcIDCacheAPI/silc_idcache_get_all
298 * bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
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.
307 bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
309 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id
313 * bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
314 * SilcIDCacheList *ret);
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.
323 bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
324 SilcIDCacheList *ret);
326 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one
330 * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
331 * SilcIDCacheEntry *ret);
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.
340 bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
341 SilcIDCacheEntry *ret);
343 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one_ext
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);
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.
362 bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id,
363 SilcHashFunction hash,
365 SilcHashCompare compare,
366 void *compare_context,
367 SilcIDCacheEntry *ret);
369 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context
373 * bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
374 * SilcIDCacheEntry *ret);
378 * Find cache entry by user specified context. Returns TRUE if the
382 bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
383 SilcIDCacheEntry *ret);
385 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name
389 * bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
390 * SilcIDCacheList *ret);
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.
399 bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
400 SilcIDCacheList *ret);
402 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one
406 * bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
407 * SilcIDCacheEntry *ret);
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.
417 bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
418 SilcIDCacheEntry *ret);
420 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_count
424 * int silc_idcache_list_count(SilcIDCacheList list);
428 * Returns the number of cache entries in the ID cache list.
431 int silc_idcache_list_count(SilcIDCacheList list);
433 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_first
437 * bool silc_idcache_list_first(SilcIDCacheList list,
438 * SilcIDCacheEntry *ret);
442 * Returns the first cache entry from the ID cache list. Returns FALSE
443 * If the entry could not be retrieved.
446 bool silc_idcache_list_first(SilcIDCacheList list, SilcIDCacheEntry *ret);
448 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_next
452 * bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
456 * Returns the next cache entry from the ID Cache list. Returns FALSE
457 * when there are not anymore entries in the list.
460 bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
462 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_free
466 * void silc_idcache_list_free(SilcIDCacheList list);
470 * Frees ID cache list. User must free the list context returned by
471 * any of the searching functions.
474 void silc_idcache_list_free(SilcIDCacheList list);