Back to index

courier  0.68.2
tlscache.h
Go to the documentation of this file.
00001 /*
00002 ** Copyright 2002 Double Precision, Inc.
00003 ** See COPYING for distribution information.
00004 */
00005 
00006 #ifndef tlscache_h
00007 #define tlscache_h
00008 
00009 #include      "config.h"
00010 
00011 #include      <sys/types.h>
00012 #include      <unistd.h>
00013 
00014 
00015 /*
00016 ** This module implements a cache for SSL sessions, however the interface
00017 ** is generic enough to accomodate caching of any kind of small object.
00018 ** The cache is a disk file, that contains a circular cache (when the
00019 ** end of the file is reached, we wrap around and begin adding new cached
00020 ** object to the beginning of the file, overwriting the oldest one).
00021 **
00022 ** Well, that's the general idea, but technically it's the other way around.
00023 ** The cache begins at the end of the file, and grows towards the beginning
00024 ** of the file, then wraps around to the end of the file again.  The cache
00025 ** is searched by reading the file starting with wherever the current add
00026 ** position is, then wrapping around if necessary.  Hence, the cache file
00027 ** is searched starting with the most recently added object; which is the
00028 ** expected usage pattern.
00029 **
00030 ** File locking is used to implement concurrency.
00031 */
00032 
00033 struct CACHE {
00034        int fd;
00035        char *filename;
00036 };
00037 
00038 /*
00039 ** Open a cache file.  If it doesn't exist, create one with the indicated
00040 ** size (in bytes).
00041 */
00042 
00043 struct CACHE *tls_cache_open(const char *filename,
00044                           off_t req_size);       /* In bytes */
00045 
00046 /*
00047 ** Close and deallocate the CACHE object.
00048 */
00049 void tls_cache_close(struct CACHE *p);
00050 
00051 /*
00052 ** Cache a new object, val, vallen bytes long.
00053 */
00054 
00055 int tls_cache_add(struct CACHE *p, const char *val, size_t vallen);
00056 
00057 /*
00058 ** Read the cache file.  walk_func is a callback function that's repeatedly
00059 ** called for each cached object.  walk_func should return 0 to continue
00060 ** with the next cached object; a positive value to stop reading the cache
00061 ** (object found); a negative value to stopr eading the cache and remove it
00062 ** (if it's corrupted, for some reason).  walk_func receives 'arg', a
00063 ** transparent pointer.
00064 **
00065 ** tls_cache_walk returns 0 when all cached objects were read, or the non-0
00066 ** return value from the callback function.  tls_cache_walk will return -1
00067 ** if it itself encounters an error.
00068 **
00069 ** The callback function may modify rec, and set *doupdate to non-zero in
00070 ** order to update the cached record (the return code is still processed in
00071 ** the normal way).  The updated record will be saved if the callback function
00072 ** terminate with 0 or a positive return code.
00073 */
00074 
00075 int tls_cache_walk(struct CACHE *p,
00076                  int (*walk_func)(void *rec, size_t recsize,
00077                                 int *doupdate, void *arg),
00078                  void *arg);
00079 
00080 
00081 #endif