xref: /illumos-gate/usr/src/lib/libsasl/include/prop.h (revision 1da57d551424de5a9d469760be7c4b4d4f10a755)
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 #ifdef	__cplusplus
32 extern "C" {
33 #endif
34 
35 /*
36  * the resulting structure for property values
37  */
38 struct propval {
39 	/*
40 	 * name of property; NULL = end of list
41 	 * same pointer used in request will be used here
42 	 */
43     const char *name;
44     const char **values;
45 	/*
46 	 * list of strings, values == NULL if property not
47 	 * found, *values == NULL if property found with
48 	 * no values
49 	 */
50     unsigned nvalues;    /* total number of value strings */
51     unsigned valsize;	 /* total size in characters of all value strings */
52 };
53 
54 /*
55  * private internal structure
56  */
57 #define	PROP_DEFAULT 4		/* default number of propvals to assume */
58 struct propctx;
59 
60 /*
61  * create a property context
62  *  estimate -- an estimate of the storage needed for requests & responses
63  *              0 will use module default
64  * returns a new property context on success and NULL on any error
65  */
66 struct propctx *prop_new(unsigned estimate);
67 
68 /*
69  * create new propctx which duplicates the contents of an existing propctx
70  * returns SASL_OK on success
71  * possible other return values include: SASL_NOMEM, SASL_BADPARAM
72  */
73 int prop_dup(struct propctx *src_ctx, struct propctx **dst_ctx);
74 
75 /*
76  * Add property names to request
77  *  ctx       -- context from prop_new()
78  *  names     -- list of property names; must persist until context freed
79  *               or requests cleared (This extends to other contexts that
80  *               are dup'ed from this one, and their children, etc)
81  *
82  * NOTE: may clear values from context as side-effect
83  * returns SASL_OK on success
84  * possible other return values include: SASL_NOMEM, SASL_BADPARAM
85  */
86 int prop_request(struct propctx *ctx, const char **names);
87 
88 /*
89  * return array of struct propval from the context
90  *  return value persists until next call to
91  *   prop_request, prop_clear or prop_dispose on context
92  *
93  *  returns NULL on error
94  */
95 const struct propval *prop_get(struct propctx *ctx);
96 
97 /*
98  * Fill in an array of struct propval based on a list of property names
99  *  return value persists until next call to
100  *   prop_request, prop_clear or prop_dispose on context
101  *  returns number of matching properties which were found (values != NULL)
102  *  if a name requested here was never requested by a prop_request, then
103  *  the name field of the associated vals entry will be set to NULL
104  *
105  * The vals array MUST be atleast as long as the names array.
106  *
107  * returns # of matching properties on success
108  * possible other return values include: SASL_BADPARAM
109  */
110 int prop_getnames(struct propctx *ctx, const char **names,
111 		struct propval *vals);
112 
113 /*
114  * clear values and optionally requests from property context
115  *  ctx      -- property context
116  *  requests -- 0 = don't clear requests, 1 = clear requests
117  */
118 void prop_clear(struct propctx *ctx, int requests);
119 
120 /*
121  * erase the value of a property
122  */
123 void prop_erase(struct propctx *ctx, const char *name);
124 
125 /*
126  * dispose of property context
127  *  ctx      -- is disposed and set to NULL; noop if ctx or *ctx is NULL
128  */
129 void prop_dispose(struct propctx **ctx);
130 
131 
132 /* fetcher interfaces */
133 
134 /*
135  * format the requested property names into a string
136  *  ctx    -- context from prop_new()/prop_request()
137  *  sep    -- separator between property names (unused if none requested)
138  *  seplen -- length of separator, if < 0 then strlen(sep) will be used
139  *  outbuf -- output buffer
140  *  outmax -- maximum length of output buffer including NUL terminator
141  *  outlen -- set to length of output string excluding NUL terminator
142  * returns SASL_OK on success
143  * returns SASL_BADPARAM or amount of additional space needed on failure
144  */
145 int prop_format(struct propctx *ctx, const char *sep, int seplen,
146 		char *outbuf, unsigned outmax, unsigned *outlen);
147 
148 /*
149  * add a property value to the context
150  *  ctx    -- context from prop_new()/prop_request()
151  *  name   -- name of property to which value will be added
152  *            if NULL, add to the same name as previous prop_set/setvals call
153  *  value  -- a value for the property; will be copied into context
154  *            if NULL, remove existing values
155  *  vallen -- length of value, if <= 0 then strlen(value) will be used
156  * returns SASL_OK on success
157  * possible error return values include: SASL_BADPARAM, SASL_NOMEM
158  */
159 int prop_set(struct propctx *ctx, const char *name,
160 		const char *value, int vallen);
161 
162 /*
163  * set the values for a property
164  *  ctx    -- context from prop_new()/prop_request()
165  *  name   -- name of property to which value will be added
166  *            if NULL, add to the same name as previous prop_set/setvals call
167  *  values -- array of values, ending in NULL.  Each value is a NUL terminated
168  *            string
169  * returns SASL_OK on success
170  * possible error return values include: SASL_BADPARAM, SASL_NOMEM
171  */
172 int prop_setvals(struct propctx *ctx, const char *name,
173 		const char **values);
174 
175 
176 #ifdef	__cplusplus
177 }
178 #endif
179 
180 #endif /* _SASL_PROP_H */
181