1 /* prop.h -- property request/response management routines 2 * 3 * Author: Chris Newman 4 * Removal of implementation-specific details by: Rob Siemborski 5 * 6 * This is intended to be used to create a list of properties to request, 7 * and _then_ request values for all properties. Any change to the request 8 * list will discard any existing values. This assumption allows a very 9 * efficient and simple memory model. This was designed for SASL API auxiliary 10 * property support, but would be fine for other contexts where this property 11 * model is appropriate. 12 * 13 * The "struct propctx" is allocated by prop_new and is a fixed size structure. 14 * If a prop_init() call were added, it would be reasonable to embed a "struct 15 * propctx" in another structure. prop_new also allocates a pool of memory 16 * (in the vbase field) which will be used for an array of "struct propval" 17 * to list all the requested properties. 18 * 19 * Properties may be multi-valued. 20 */ 21 22 #ifndef PROP_H 23 #define PROP_H 1 24 25 /* The following ifdef block is the standard way of creating macros 26 * which make exporting from a DLL simpler. All files within this DLL 27 * are compiled with the LIBSASL_EXPORTS symbol defined on the command 28 * line. this symbol should not be defined on any project that uses 29 * this DLL. This way any other project whose source files include 30 * this file see LIBSASL_API functions as being imported from a DLL, 31 * wheras this DLL sees symbols defined with this macro as being 32 * exported. */ 33 /* Under Unix, life is simpler: we just need to mark library functions 34 * as extern. (Technically, we don't even have to do that.) */ 35 #ifdef WIN32 36 # ifdef LIBSASL_EXPORTS 37 # define LIBSASL_API extern __declspec(dllexport) 38 # else /* LIBSASL_EXPORTS */ 39 # define LIBSASL_API extern __declspec(dllimport) 40 # endif /* LIBSASL_EXPORTS */ 41 #else /* WIN32 */ 42 # define LIBSASL_API extern 43 #endif /* WIN32 */ 44 45 /* Same as above, but used during a variable declaration. */ 46 #ifdef WIN32 47 # ifdef LIBSASL_EXPORTS 48 # define LIBSASL_VAR extern __declspec(dllexport) 49 # else /* LIBSASL_EXPORTS */ 50 # define LIBSASL_VAR extern __declspec(dllimport) 51 # endif /* LIBSASL_EXPORTS */ 52 #else /* WIN32 */ 53 # define LIBSASL_VAR extern 54 #endif /* WIN32 */ 55 56 /* the resulting structure for property values 57 */ 58 struct propval { 59 const char *name; /* name of property; NULL = end of list */ 60 /* same pointer used in request will be used here */ 61 const char **values; /* list of strings, values == NULL if property not 62 * found, *values == NULL if property found with 63 * no values */ 64 unsigned nvalues; /* total number of value strings */ 65 unsigned valsize; /* total size in characters of all value strings */ 66 }; 67 68 /* 69 * private internal structure 70 */ 71 #define PROP_DEFAULT 4 /* default number of propvals to assume */ 72 struct propctx; 73 74 #ifdef __cplusplus 75 extern "C" { 76 #endif 77 78 /* create a property context 79 * estimate -- an estimate of the storage needed for requests & responses 80 * 0 will use module default 81 * returns a new property context on success and NULL on any error 82 */ 83 LIBSASL_API struct propctx *prop_new(unsigned estimate); 84 85 /* create new propctx which duplicates the contents of an existing propctx 86 * returns SASL_OK on success 87 * possible other return values include: SASL_NOMEM, SASL_BADPARAM 88 */ 89 LIBSASL_API int prop_dup(struct propctx *src_ctx, struct propctx **dst_ctx); 90 91 /* Add property names to request 92 * ctx -- context from prop_new() 93 * names -- list of property names; must persist until context freed 94 * or requests cleared (This extends to other contexts that 95 * are dup'ed from this one, and their children, etc) 96 * 97 * NOTE: may clear values from context as side-effect 98 * returns SASL_OK on success 99 * possible other return values include: SASL_NOMEM, SASL_BADPARAM 100 */ 101 LIBSASL_API int prop_request(struct propctx *ctx, const char **names); 102 103 /* return array of struct propval from the context 104 * return value persists until next call to 105 * prop_request, prop_clear or prop_dispose on context 106 * 107 * returns NULL on error 108 */ 109 LIBSASL_API const struct propval *prop_get(struct propctx *ctx); 110 111 /* Fill in an array of struct propval based on a list of property names 112 * return value persists until next call to 113 * prop_request, prop_clear or prop_dispose on context 114 * returns number of matching properties which were found (values != NULL) 115 * if a name requested here was never requested by a prop_request, then 116 * the name field of the associated vals entry will be set to NULL 117 * 118 * The vals array MUST be atleast as long as the names array. 119 * 120 * returns # of matching properties on success 121 * possible other return values include: SASL_BADPARAM 122 */ 123 LIBSASL_API int prop_getnames(struct propctx *ctx, const char **names, 124 struct propval *vals); 125 126 /* clear values and optionally requests from property context 127 * ctx -- property context 128 * requests -- 0 = don't clear requests, 1 = clear requests 129 */ 130 LIBSASL_API void prop_clear(struct propctx *ctx, int requests); 131 132 /* erase the value of a property 133 */ 134 LIBSASL_API void prop_erase(struct propctx *ctx, const char *name); 135 136 /* dispose of property context 137 * ctx -- is disposed and set to NULL; noop if ctx or *ctx is NULL 138 */ 139 LIBSASL_API void prop_dispose(struct propctx **ctx); 140 141 142 /****fetcher interfaces****/ 143 144 /* format the requested property names into a string 145 * ctx -- context from prop_new()/prop_request() 146 * sep -- separator between property names (unused if none requested) 147 * seplen -- length of separator, if < 0 then strlen(sep) will be used 148 * outbuf -- output buffer 149 * outmax -- maximum length of output buffer including NUL terminator 150 * outlen -- set to length of output string excluding NUL terminator 151 * returns SASL_OK on success 152 * returns SASL_BADPARAM or amount of additional space needed on failure 153 */ 154 LIBSASL_API int prop_format(struct propctx *ctx, const char *sep, int seplen, 155 char *outbuf, unsigned outmax, unsigned *outlen); 156 157 /* add a property value to the context 158 * ctx -- context from prop_new()/prop_request() 159 * name -- name of property to which value will be added 160 * if NULL, add to the same name as previous prop_set/setvals call 161 * value -- a value for the property; will be copied into context 162 * if NULL, remove existing values 163 * vallen -- length of value, if <= 0 then strlen(value) will be used 164 * returns SASL_OK on success 165 * possible error return values include: SASL_BADPARAM, SASL_NOMEM 166 */ 167 LIBSASL_API int prop_set(struct propctx *ctx, const char *name, 168 const char *value, int vallen); 169 170 /* set the values for a property 171 * ctx -- context from prop_new()/prop_request() 172 * name -- name of property to which value will be added 173 * if NULL, add to the same name as previous prop_set/setvals call 174 * values -- array of values, ending in NULL. Each value is a NUL terminated 175 * string 176 * returns SASL_OK on success 177 * possible error return values include: SASL_BADPARAM, SASL_NOMEM 178 */ 179 LIBSASL_API int prop_setvals(struct propctx *ctx, const char *name, 180 const char **values); 181 182 #ifdef __cplusplus 183 } 184 #endif 185 186 #endif /* PROP_H */ 187