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 */
58struct 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 */
72struct propctx;
73
74#ifdef __cplusplus
75extern "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 */
83LIBSASL_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 */
89LIBSASL_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 */
101LIBSASL_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 */
109LIBSASL_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 */
123LIBSASL_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 */
130LIBSASL_API void prop_clear(struct propctx *ctx, int requests);
131
132/* erase the value of a property
133 */
134LIBSASL_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 */
139LIBSASL_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 */
154LIBSASL_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 */
167LIBSASL_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 */
179LIBSASL_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