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