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