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; version 2 of the License.
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.
20 /****h* silccore/SILC ID Cache Interface
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.
33 /****s* silccore/SilcIDCacheAPI/SilcIDCacheEntry
37 * typedef struct { ... } SilcIDCacheEntry;
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.
52 * A name associated with the ID.
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.
63 * Any caller specified context.
75 /****s* silccore/SilcIDCacheAPI/SilcIDCache
79 * typedef struct SilcIDCacheStruct *SilcIDCache;
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.
89 typedef struct SilcIDCacheStruct *SilcIDCache;
91 /****s* silccore/SilcIDCacheAPI/SilcIDCacheList
95 * typedef struct SilcIDCacheListStruct *SilcIDCacheList;
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
106 typedef struct SilcIDCacheListStruct *SilcIDCacheList;
108 /****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor
112 * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
113 * SilcIDCacheEntry entry,
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.
124 typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
125 SilcIDCacheEntry entry,
128 #define SILC_ID_CACHE_EXPIRE 3600
129 #define SILC_ID_CACHE_EXPIRE_DEF (time(NULL) + SILC_ID_CACHE_EXPIRE)
133 /****f* silccore/SilcIDCacheAPI/silc_idcache_alloc
137 * SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
138 * SilcIDCacheDestructor destructor,
139 * void *destructor_context,
140 * bool delete_id, bool delete_name);
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
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.
154 SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
155 SilcIDCacheDestructor destructor,
156 void *destructor_context,
157 bool delete_id, bool delete_name);
159 /****f* silccore/SilcIDCacheAPI/silc_idcache_free
163 * void silc_idcache_free(SilcIDCache cache);
167 * Frees ID cache object and all cache entries.
170 void silc_idcache_free(SilcIDCache cache);
172 /****f* silccore/SilcIDCacheAPI/silc_idcache_add
176 * bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
177 * void *context, int expire, SilcIDCacheEntry *ret);
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.
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
192 * If the `ret' is non-NULL the created ID Cache entry is returned to
196 bool silc_idcache_add(SilcIDCache cache, char *name, void *id,
197 void *context, int expire, SilcIDCacheEntry *ret);
199 /****f* silccore/SilcIDCacheAPI/silc_idcache_del
203 * bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
207 * Delete cache entry from cache. Returns TRUE if the entry was deleted.
208 * The destructor function is not called.
211 bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old);
213 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id
217 * bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
221 * Delete cache entry by ID. Returns TRUE if the entry was deleted.
222 * The destructor function is not called.
225 bool silc_idcache_del_by_id(SilcIDCache cache, void *id);
227 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id_ext
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);
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
245 bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id,
246 SilcHashFunction hash,
248 SilcHashCompare compare,
249 void *compare_context);
251 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context
255 * bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
259 * Deletes cachen entry by the user specified context. Returns TRUE
260 * if the entry was deleted. The destructor function is not called.
263 bool silc_idcache_del_by_context(SilcIDCache cache, void *context);
265 /****f* silccore/SilcIDCacheAPI/silc_idcache_del_all
269 * bool silc_idcache_del_all(SilcIDCache cache);
273 * Deletes all cache entries from the cache and frees all memory.
274 * The destructor function is not called.
277 bool silc_idcache_del_all(SilcIDCache cache);
279 /****f* silccore/SilcIDCacheAPI/silc_idcache_purge
283 * bool silc_idcache_purge(SilcIDCache cache);
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.
292 bool silc_idcache_purge(SilcIDCache cache);
294 /****f* silccore/SilcIDCacheAPI/silc_idcache_by_context
298 * bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
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.
307 bool silc_idcache_purge_by_context(SilcIDCache cache, void *context);
309 /****f* silccore/SilcIDCacheAPI/silc_idcache_get_all
313 * bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
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.
322 bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret);
324 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id
328 * bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
329 * SilcIDCacheList *ret);
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.
338 bool silc_idcache_find_by_id(SilcIDCache cache, void *id,
339 SilcIDCacheList *ret);
341 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one
345 * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
346 * SilcIDCacheEntry *ret);
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.
355 bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
356 SilcIDCacheEntry *ret);
358 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one_ext
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);
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.
377 bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id,
378 SilcHashFunction hash,
380 SilcHashCompare compare,
381 void *compare_context,
382 SilcIDCacheEntry *ret);
384 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context
388 * bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
389 * SilcIDCacheEntry *ret);
393 * Find cache entry by user specified context. Returns TRUE if the
397 bool silc_idcache_find_by_context(SilcIDCache cache, void *context,
398 SilcIDCacheEntry *ret);
400 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name
404 * bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
405 * SilcIDCacheList *ret);
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.
414 bool silc_idcache_find_by_name(SilcIDCache cache, char *name,
415 SilcIDCacheList *ret);
417 /****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one
421 * bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
422 * SilcIDCacheEntry *ret);
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.
432 bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
433 SilcIDCacheEntry *ret);
435 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_count
439 * int silc_idcache_list_count(SilcIDCacheList list);
443 * Returns the number of cache entries in the ID cache list.
446 int silc_idcache_list_count(SilcIDCacheList list);
448 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_first
452 * bool silc_idcache_list_first(SilcIDCacheList list,
453 * SilcIDCacheEntry *ret);
457 * Returns the first cache entry from the ID cache list. Returns FALSE
458 * If the entry could not be retrieved.
461 bool silc_idcache_list_first(SilcIDCacheList list, SilcIDCacheEntry *ret);
463 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_next
467 * bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
471 * Returns the next cache entry from the ID Cache list. Returns FALSE
472 * when there are not anymore entries in the list.
475 bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret);
477 /****f* silccore/SilcIDCacheAPI/silc_idcache_list_free
481 * void silc_idcache_list_free(SilcIDCacheList list);
485 * Frees ID cache list. User must free the list context returned by
486 * any of the searching functions.
489 void silc_idcache_list_free(SilcIDCacheList list);