5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2000 - 2006 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* silcapputil/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.
28 * SILC ID Cache is not thread-safe. If the same cache context must be
29 * used in multithreaded environment concurrency control must be employed.
36 /****s* silcapputil/SilcIDCacheAPI/SilcIDCacheEntry
40 * typedef struct SilcIDCacheEntryStruct { ... } SilcIDCacheEntry;
44 * This is an entry in the SILC ID Cache system. This context is
45 * allocated by adding new entry to ID cache by calling silc_idcache_add.
46 * Each of the fields in the structure are allocated by the caller.
50 typedef struct SilcIDCacheEntryStruct {
51 struct SilcIDCacheEntryStruct *next;
52 void *id; /* Associated ID */
53 char *name; /* Associated entry name */
54 void *context; /* Associated context */
58 /****s* silcapputil/SilcIDCacheAPI/SilcIDCache
62 * typedef struct SilcIDCacheStruct *SilcIDCache;
66 * This context is the actual ID Cache and is allocated by
67 * silc_idcache_alloc and given as argument usually to all
68 * silc_idcache_* functions. It is freed by the
69 * silc_idcache_free function.
72 typedef struct SilcIDCacheStruct *SilcIDCache;
74 /****f* silcapputil/SilcIDCacheAPI/SilcIDCacheDestructor
78 * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
79 * const SilcIDCacheEntry entry,
80 * void *destructor_context,
85 * Destructor callback given as argument to silc_idcache_alloc. This
86 * is called when an entry is deleted from the cache. Application
87 * must free the contents of the `entry'.
90 typedef void (*SilcIDCacheDestructor)(SilcIDCache cache,
91 const SilcIDCacheEntry entry,
92 void *destructor_context,
97 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_alloc
101 * SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
102 * SilcIDCacheDestructor destructor,
103 * void *destructor_context,
104 * SilcBool delete_id, SilcBool delete_name);
108 * Allocates new ID cache object. The initial amount of allocated entries
109 * can be sent as argument. If `count' is 0 the system uses default values.
110 * The `id_type' defines the types of the ID's that will be saved to the
114 SilcIDCache silc_idcache_alloc(SilcUInt32 count, SilcIdType id_type,
115 SilcIDCacheDestructor destructor,
116 void *destructor_context);
118 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_free
122 * void silc_idcache_free(SilcIDCache cache);
126 * Frees ID cache context and all cache entries.
129 void silc_idcache_free(SilcIDCache cache);
131 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_add
136 * silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
140 * Add new entry to the cache. Returns the allocated cache entry if the
141 * entry was added successfully, or NULL if error occurred. The `name' is
142 * the name associated with the ID, the `id' the actual ID and the
143 * `context' a caller specific context.
145 * The `name', `id' and `context' pointers will be stored in the cache,
146 * and if the caller frees these pointers the caller is also responsible
147 * of deleting the cache entry.
151 silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context);
153 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_del
157 * SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry,
158 * void *app_context);
162 * Delete cache entry from cache. Returns TRUE if the entry was deleted.
163 * The destructor will be called for the entry. The `app_context' is
164 * delivered to the destructor.
167 SilcBool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry entry,
170 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_del_by_id
174 * SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id,
175 * void *app_context);
179 * Delete cache entry by ID. Returns TRUE if the entry was deleted.
180 * The destructor will be called for the entry. The `app_context' is
181 * delivered to the destructor.
184 SilcBool silc_idcache_del_by_id(SilcIDCache cache, void *id,
187 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_del_by_context
191 * SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context);
195 * Deletes cachen entry by the user specified context. Returns TRUE
196 * if the entry was deleted. The destructor will be called for the
197 * entry. The `app_context' is delivered to the destructor.
200 SilcBool silc_idcache_del_by_context(SilcIDCache cache, void *context,
203 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_update
207 * SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
208 * void *new_id, char *new_name,
209 * SilcBool free_old_name);
213 * Updates cache `entry' with new values. If the `new_id' is non-NULL
214 * then the new value will be copied over the old value in the `entry'.
215 * If the `new_name' is non-NULL then the `entry' will be updated with
216 * `new_name'. The caller is responsible of freeing the old name if it
217 * was updated with new one. The old ID value does not need to be freed
218 * as the new value is copied over the old value. If the `free_old_name'
219 * is TRUE the library will free the old name from the entry.
222 SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry,
223 void *new_id, char *new_name,
224 SilcBool free_old_name);
226 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_update
231 * silc_idcache_update_by_context(SilcIDCache cache, void *context,
232 * void *new_id, char *new_name,
233 * SilcBool free_old_name);
237 * Same as silc_idcache_update but finds the corrent ID cache entry by
238 * the `context' added to the ID cache.
241 SilcBool silc_idcache_update_by_context(SilcIDCache cache, void *context,
242 void *new_id, char *new_name,
243 SilcBool free_old_name);
245 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_get_all
249 * SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
253 * Returns all cache entries into the SilcList `ret_list' pointer. Each
254 * entry in the list is SilcIDCacheEntry. Returns FALSE if the cache
258 SilcBool silc_idcache_get_all(SilcIDCache cache, SilcList *ret_list);
260 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_id
264 * SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
265 * SilcList *ret_list);
269 * Find ID Cache entry by ID. This may return multiple entries.
270 * The entires are returned into the `ret_list' SilcList context.
271 * Returns TRUE if entry was found.
275 * If this function is used to find Client ID (SilcClientID), only the
276 * hash portion of the Client ID is compared. Use the function
277 * silc_idcache_find_by_id_one to find exact match for Client ID (full
278 * ID is compared and not only the hash).
280 * Comparing only the hash portion of Client ID allows searching of
281 * Client ID's by nickname, because the hash is based on the nickname.
282 * As nicknames are not unique, multiple entries may be found.
285 SilcBool silc_idcache_find_by_id(SilcIDCache cache, void *id,
288 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_id_one
292 * SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
293 * SilcIDCacheEntry *ret);
297 * Find ID Cache entry by ID. Returns only one entry from the cache
298 * and the found entry is considered to be exact match. Returns TRUE
299 * if the entry was found.
302 SilcBool silc_idcache_find_by_id_one(SilcIDCache cache, void *id,
303 SilcIDCacheEntry *ret);
305 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_context
309 * SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
310 * SilcIDCacheEntry *ret);
314 * Find cache entry by user specified context. Returns TRUE if the
318 SilcBool silc_idcache_find_by_context(SilcIDCache cache, void *context,
319 SilcIDCacheEntry *ret);
321 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_name
325 * SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
326 * SilcList *ret_list);
330 * Find cache entries by the name associated with the ID. This may
331 * return multiple entries to the `ret_list' SilcList context. Returns
332 * TRUE if the entry was found.
335 SilcBool silc_idcache_find_by_name(SilcIDCache cache, char *name,
338 /****f* silcapputil/SilcIDCacheAPI/silc_idcache_find_by_name_one
342 * SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
343 * SilcIDCacheEntry *ret);
347 * Find cache entry by the name associated with the ID. This returns
348 * one entry and the found entry is considered to be exact match.
349 * Returns TRUE if the entry was found.
352 SilcBool silc_idcache_find_by_name_one(SilcIDCache cache, char *name,
353 SilcIDCacheEntry *ret);
355 #endif /* SILCIDCACHE_H */