9.8 * l=J 76Cq.2☴o tA_I|++ /* prop.h -- property request/response management routines * * Author: Chris Newman * Removal of implementation-specific details by: Rob Siemborski * * This is intended to be used to create a list of properties to request, * and _then_ request values for all properties. Any change to the request * list will discard any existing values. This assumption allows a very * efficient and simple memory model. This was designed for SASL API auxiliary * property support, but would be fine for other contexts where this property * model is appropriate. * * The "struct propctx" is allocated by prop_new and is a fixed size structure. * If a prop_init() call were added, it would be reasonable to embed a "struct * propctx" in another structure. prop_new also allocates a pool of memory * (in the vbase field) which will be used for an array of "struct propval" * to list all the requested properties. * * Properties may be multi-valued. */ #ifndef PROP_H #define PROP_H 1 /* The following ifdef block is the standard way of creating macros * which make exporting from a DLL simpler. All files within this DLL * are compiled with the LIBSASL_EXPORTS symbol defined on the command * line. this symbol should not be defined on any project that uses * this DLL. This way any other project whose source files include * this file see LIBSASL_API functions as being imported from a DLL, * wheras this DLL sees symbols defined with this macro as being * exported. */ /* Under Unix, life is simpler: we just need to mark library functions * as extern. (Technically, we don't even have to do that.) */ #ifdef WIN32 # ifdef LIBSASL_EXPORTS # define LIBSASL_API extern __declspec(dllexport) # else /* LIBSASL_EXPORTS */ # define LIBSASL_API extern __declspec(dllimport) # endif /* LIBSASL_EXPORTS */ #else /* WIN32 */ # define LIBSASL_API extern #endif /* WIN32 */ /* Same as above, but used during a variable declaration. */ #ifdef WIN32 # ifdef LIBSASL_EXPORTS # define LIBSASL_VAR extern __declspec(dllexport) # else /* LIBSASL_EXPORTS */ # define LIBSASL_VAR extern __declspec(dllimport) # endif /* LIBSASL_EXPORTS */ #else /* WIN32 */ # define LIBSASL_VAR extern #endif /* WIN32 */ /* the resulting structure for property values */ struct propval { const char *name; /* name of property; NULL = end of list */ /* same pointer used in request will be used here */ const char **values; /* list of strings, values == NULL if property not * found, *values == NULL if property found with * no values */ unsigned nvalues; /* total number of value strings */ unsigned valsize; /* total size in characters of all value strings */ }; /* * private internal structure */ #define PROP_DEFAULT 4 /* default number of propvals to assume */ struct propctx; #ifdef __cplusplus extern "C" { #endif /* create a property context * estimate -- an estimate of the storage needed for requests & responses * 0 will use module default * returns a new property context on success and NULL on any error */ LIBSASL_API struct propctx *prop_new(unsigned estimate); /* create new propctx which duplicates the contents of an existing propctx * returns SASL_OK on success * possible other return values include: SASL_NOMEM, SASL_BADPARAM */ LIBSASL_API int prop_dup(struct propctx *src_ctx, struct propctx **dst_ctx); /* Add property names to request * ctx -- context from prop_new() * names -- list of property names; must persist until context freed * or requests cleared (This extends to other contexts that * are dup'ed from this one, and their children, etc) * * NOTE: may clear values from context as side-effect * returns SASL_OK on success * possible other return values include: SASL_NOMEM, SASL_BADPARAM */ LIBSASL_API int prop_request(struct propctx *ctx, const char **names); /* return array of struct propval from the context * return value persists until next call to * prop_r