usr/src/lib/libsasl/include/prop.h

   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
  34 extern "C" {
  35 #endif
  36
  37 /*
  38  * the resulting structure for property values
  39  */
  40 struct 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 */
  60 struct 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  */
  68 struct 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  */
  75 int 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  */
  88 int 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  */
  97 const 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  */
 112 int 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  */
 120 void prop_clear(struct propctx *ctx, int requests);
 121
 122 /*
 123  * erase the value of a property
 124  */
 125 void 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  */
 131 void 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  */
 147 int 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  */
 161 int 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  */
 174 int 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 */