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