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