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