1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17/** 18 * @file ap_socache.h 19 * @brief Small object cache provider interface. 20 * 21 * @defgroup AP_SOCACHE ap_socache 22 * @ingroup APACHE_MODS 23 * @{ 24 */ 25 26#ifndef AP_SOCACHE_H 27#define AP_SOCACHE_H 28 29#include "httpd.h" 30#include "ap_provider.h" 31#include "apr_pools.h" 32#include "apr_time.h" 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38/** If this flag is set, the store/retrieve/remove/status interfaces 39 * of the provider are NOT safe to be called concurrently from 40 * multiple processes or threads, and an external global mutex must be 41 * used to serialize access to the provider. 42 */ 43/* XXX: Even if store/retrieve/remove is atomic, isn't it useful to note 44 * independently that status and iterate may or may not be? 45 */ 46#define AP_SOCACHE_FLAG_NOTMPSAFE (0x0001) 47 48/** A cache instance. */ 49typedef struct ap_socache_instance_t ap_socache_instance_t; 50 51/** Hints which may be passed to the init function; providers may 52 * ignore some or all of these hints. */ 53struct ap_socache_hints { 54 /** Approximate average length of IDs: */ 55 apr_size_t avg_id_len; 56 /** Approximate average size of objects: */ 57 apr_size_t avg_obj_size; 58 /** Suggested interval between expiry cleanup runs; */ 59 apr_interval_time_t expiry_interval; 60}; 61 62/** 63 * Iterator callback prototype for the ap_socache_provider_t->iterate() method 64 * @param instance The cache instance 65 * @param s Associated server context (for logging) 66 * @param userctx User defined pointer passed from the iterator call 67 * @param id Unique ID for the object (binary blob) 68 * with a trailing null char for convenience 69 * @param idlen Length of id blob 70 * @param data Output buffer to place retrieved data (binary blob) 71 * with a trailing null char for convenience 72 * @param datalen Length of data buffer 73 * @param pool Pool for temporary allocations 74 * @return APR status value; return APR_SUCCESS or the iteration will halt; 75 * this value is returned to the ap_socache_provider_t->iterate() caller 76 */ 77typedef apr_status_t (ap_socache_iterator_t)(ap_socache_instance_t *instance, 78 server_rec *s, 79 void *userctx, 80 const unsigned char *id, 81 unsigned int idlen, 82 const unsigned char *data, 83 unsigned int datalen, 84 apr_pool_t *pool); 85 86/** A socache provider structure. socache providers are registered 87 * with the ap_provider.h interface using the AP_SOCACHE_PROVIDER_* 88 * constants. */ 89typedef struct ap_socache_provider_t { 90 /** Canonical provider name. */ 91 const char *name; 92 93 /** Bitmask of AP_SOCACHE_FLAG_* flags. */ 94 unsigned int flags; 95 96 /** 97 * Create a session cache based on the given configuration string. 98 * The instance pointer returned in the instance parameter will be 99 * passed as the first argument to subsequent invocations. 100 * 101 * @param instance Output parameter to which instance object is written. 102 * @param arg User-specified configuration string. May be NULL to 103 * force use of defaults. 104 * @param tmp Pool to be used for any temporary allocations 105 * @param p Pool to be use for any allocations lasting as long as 106 * the created instance 107 * @return NULL on success, or an error string on failure. 108 */ 109 const char *(*create)(ap_socache_instance_t **instance, const char *arg, 110 apr_pool_t *tmp, apr_pool_t *p); 111 112 /** 113 * Initialize the cache. The cname must be of maximum length 16 114 * characters, and uniquely identifies the consumer of the cache 115 * within the server; using the module name is recommended, e.g. 116 * "mod_ssl-sess". This string may be used within a filesystem 117 * path so use of only alphanumeric [a-z0-9_-] characters is 118 * recommended. If hints is non-NULL, it gives a set of hints for 119 * the provider. Returns APR error code. 120 * 121 * @param instance The cache instance 122 * @param cname A unique string identifying the consumer of this API 123 * @param hints Optional hints argument describing expected cache use 124 * @param s Server structure to which the cache is associated 125 * @param pool Pool for long-lived allocations 126 * @return APR status value indicating success. 127 */ 128 apr_status_t (*init)(ap_socache_instance_t *instance, const char *cname, 129 const struct ap_socache_hints *hints, 130 server_rec *s, apr_pool_t *pool); 131 132 /** 133 * Destroy a given cache instance object. 134 * @param instance The cache instance to destroy. 135 * @param s Associated server structure (for logging purposes) 136 */ 137 void (*destroy)(ap_socache_instance_t *instance, server_rec *s); 138 139 /** 140 * Store an object in a cache instance. 141 * @param instance The cache instance 142 * @param s Associated server structure (for logging purposes) 143 * @param id Unique ID for the object; binary blob 144 * @param idlen Length of id blob 145 * @param expiry Absolute time at which the object expires 146 * @param data Data to store; binary blob 147 * @param datalen Length of data blob 148 * @param pool Pool for temporary allocations. 149 * @return APR status value. 150 */ 151 apr_status_t (*store)(ap_socache_instance_t *instance, server_rec *s, 152 const unsigned char *id, unsigned int idlen, 153 apr_time_t expiry, 154 unsigned char *data, unsigned int datalen, 155 apr_pool_t *pool); 156 157 /** 158 * Retrieve a cached object. 159 * 160 * @param instance The cache instance 161 * @param s Associated server structure (for logging purposes) 162 * @param id Unique ID for the object; binary blob 163 * @param idlen Length of id blob 164 * @param data Output buffer to place retrievd data (binary blob) 165 * @param datalen On entry, length of data buffer; on exit, the 166 * number of bytes written to the data buffer. 167 * @param pool Pool for temporary allocations. 168 * @return APR status value; APR_NOTFOUND if the object was not 169 * found 170 */ 171 apr_status_t (*retrieve)(ap_socache_instance_t *instance, server_rec *s, 172 const unsigned char *id, unsigned int idlen, 173 unsigned char *data, unsigned int *datalen, 174 apr_pool_t *pool); 175 176 /** 177 * Remove an object from the cache 178 * 179 * @param instance The cache instance 180 * @param s Associated server structure (for logging purposes) 181 * @param id Unique ID for the object; binary blob 182 * @param idlen Length of id blob 183 * @param pool Pool for temporary allocations. 184 */ 185 apr_status_t (*remove)(ap_socache_instance_t *instance, server_rec *s, 186 const unsigned char *id, unsigned int idlen, 187 apr_pool_t *pool); 188 189 /** 190 * Dump the status of a cache instance for mod_status. Will use 191 * the ap_r* interfaces to produce appropriate status output. 192 * XXX: ap_r* are deprecated, bad dogfood 193 * 194 * @param instance The cache instance 195 * @param r The request structure 196 * @param flags The AP_STATUS_* constants used (see mod_status.h) 197 */ 198 void (*status)(ap_socache_instance_t *instance, request_rec *r, int flags); 199 200 /** 201 * Dump all cached objects through an iterator callback. 202 * @param instance The cache instance 203 * @param s Associated server context (for processing and logging) 204 * @param userctx User defined pointer passed through to the iterator 205 * @param iterator The user provided callback function which will receive 206 * individual calls for each unexpired id/data pair 207 * @param pool Pool for temporary allocations. 208 * @return APR status value; APR_NOTFOUND if the object was not 209 * found 210 */ 211 apr_status_t (*iterate)(ap_socache_instance_t *instance, server_rec *s, 212 void *userctx, ap_socache_iterator_t *iterator, 213 apr_pool_t *pool); 214 215} ap_socache_provider_t; 216 217/** The provider group used to register socache providers. */ 218#define AP_SOCACHE_PROVIDER_GROUP "socache" 219/** The provider version used to register socache providers. */ 220#define AP_SOCACHE_PROVIDER_VERSION "0" 221 222/** Default provider name. */ 223#define AP_SOCACHE_DEFAULT_PROVIDER "default" 224 225#ifdef __cplusplus 226} 227#endif 228 229#endif /* AP_SOCACHE_H */ 230/** @} */ 231