windows-kfw-sdk-20060921
[openafs.git] / src / WINNT / kfw / inc / netidmgr / kconfig.h
1 /*
2  * Copyright (c) 2005 Massachusetts Institute of Technology
3  *
4  * Permission is hereby granted, free of charge, to any person
5  * obtaining a copy of this software and associated documentation
6  * files (the "Software"), to deal in the Software without
7  * restriction, including without limitation the rights to use, copy,
8  * modify, merge, publish, distribute, sublicense, and/or sell copies
9  * of the Software, and to permit persons to whom the Software is
10  * furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be
13  * included in all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22  * SOFTWARE.
23  */
24
25 /* $Id$ */
26
27 #ifndef __KHIMAIRA_KCONFIG_H
28 #define __KHIMAIRA_KCONFIG_H
29
30 #include<khdefs.h>
31 #include<mstring.h>
32
33 /*! \defgroup kconf NetIDMgr Configuration Provider */
34 /*@{*/
35
36 /*! \brief Configuration schema descriptor record 
37
38     The schema descriptor is a convenient way to provide a default set
39     of configuration options for a part of an application.  It
40     describes the configuration spaces and the values and subspaces
41     contained in each space.
42
43     \see kconf_load_schema()
44 */
45 typedef struct tag_kconf_schema {
46     wchar_t *   name;       /*!< name of the object being described.
47                                 Optional for KC_ENDSPACE type object,
48                                 but required for everything else.
49                                 Names can be upto KCONF_MAXCCH_NAME
50                                 characters in length. */
51     khm_int32   type;       /*!< type of the object.  Can be one of
52                                 KC_SPACE, KC_ENDSPACE, KC_INT32,
53                                 KC_INT64, KC_STRING or KC_BINARY */
54     khm_ui_8    value;      /*!< the value of the object.  It is not
55                                 used for KC_SPACE and KC_ENDSPACE
56                                 typed objects.  For a KC_STRING, this
57                                 contains a pointer to the string
58                                 value.  The string should not be
59                                 longer than KCONF_MAXCCH_STRING
60                                 characters. KC_INT32 and KC_INT64
61                                 objects store the value directly in
62                                 this field, while KC_BINARY objects do
63                                 not support defining a default value
64                                 here. */
65     wchar_t *   description;/*!< a friendly description of the value
66                                 or configuration space. */
67 } kconf_schema;
68
69 /*! \name Configuration data types
70   @{*/
71 /*! \brief Not a known type */
72 #define KC_NONE         0
73
74 /*! \brief When used as ::kconf_schema \a type, defines the start of a configuration space.
75
76     There should be a subsequent KC_ENDSPACE record in the schema
77     which defines the end of this configuration space.
78
79     \a name specifies the name of the configuration space.  Optionally
80     use \a description to provide a description.*/
81 #define KC_SPACE        1
82
83 /*! \brief Ends a configuration space started with KC_SPACE */
84 #define KC_ENDSPACE     2
85
86 /*! \brief A 32 bit integer
87
88     Specifies a configuration parameter named \a name which is of this
89     type.  Use \a description to provide an optional description of
90     the value.
91
92     \a value specifies a default value for this parameter in the lower
93     32 bits.
94 */
95 #define KC_INT32        3
96
97 /*! \brief A 64 bit integer 
98
99     Specifies a configuration parameter named \a name which is of this
100     type.  Use \a description to provide an optional description of
101     the value.
102
103     \a value specifies a default value for this parameter.
104 */
105 #define KC_INT64        4
106
107 /*! \brief A unicode string 
108
109     Specifies a configuration parameter named \a name which is of this
110     type.  Use \a description to provide an optional description of
111     the value.
112
113     \a value specifies a default value for this parameter which should
114     be a pointer to a NULL terminated unicode string of no more than
115     ::KCONF_MAXCCH_STRING characters.
116 */
117 #define KC_STRING       5
118
119 /*! \brief An unparsed binary stream 
120
121     Specifies a configuration parameter named \a name which is of this
122     type.  Use \a description to provide an optional description of
123     the value.
124
125     Default values are not supported for binary streams.  \a value is
126     ignored.
127 */
128 #define KC_BINARY       6
129 /*@}*/
130
131 /*! \brief This is the root configuration space */
132 #define KCONF_FLAG_ROOT          0x00000001
133
134 /*! \brief Indicates the configuration store which stores user-specific information */
135 #define KCONF_FLAG_USER          0x00000002
136
137 /*! \brief Indicates the configuration store which stores machine-specific information */
138 #define KCONF_FLAG_MACHINE       0x00000004
139
140 /*! \brief Indicates the configuration store which stores the schema */
141 #define KCONF_FLAG_SCHEMA        0x00000008
142
143 /*! \brief Indicates that the last component of the given configuration path is to be considered to be a configuration value */
144 #define KCONF_FLAG_TRAILINGVALUE 0x00000020
145
146 /*! \brief Only write values back there is a change
147
148     Any write operations using the handle with check if the value
149     being written is different from the value being read from the
150     handle.  It will only be written if the value is different.
151
152     \note Note that the value being read from a handle takes schema and
153     shadowed configuration handles into consideration while the value
154     being written is only written to the topmost layer of
155     configuration that can be written to.
156
157     \note Note also that this flag does not affect binary values.
158  */
159 #define KCONF_FLAG_WRITEIFMOD    0x00000040
160
161 /*! \brief Use case-insensitive comparison for KCONF_FLAG_WRITEIFMOD
162
163     When used in combination with \a KCONF_FLAG_WRITEIFMOD , the
164     string comparison used when determining whether the string read
165     from the configuration handle is the same as the string being
166     written will be case insensitive.  If this flag is not set, the
167     comparison will be case sensitive.
168  */
169 #define KCONF_FLAG_IFMODCI     0x00000080
170
171 /*! \brief Do not parse the configuration space name
172
173     If set, disables the parsing of the configuration space for
174     subspaces.  The space name is taken verbatim to be a configuration
175     space name.  This can be used when there can be forward slashes or
176     backslahes in the name which are not escaped.
177
178     By default, the configuration space name,
179
180     \code
181     L"foo\\bar"
182     \endcode
183
184     is taken to mean the configuration space \a bar which is a
185     subspace of \a foo.  If ::KCONF_FLAG_NOPARSENAME is set, then this
186     is taken to mean configuration space \a foo\\bar.
187  */
188 #define KCONF_FLAG_NOPARSENAME   0x00000040
189
190 /*! \brief Maximum number of allowed characters (including terminating NULL) in a name 
191
192     \note This is a hard limit in Windows, since we are mapping
193         configuration spaces to registry keys.
194 */
195 #define KCONF_MAXCCH_NAME 256
196
197 /*! \brief Maximum number of allowed bytes (including terminating NULL) in a name */
198 #define KCONF_MAXCB_NAME (KCONF_MAXCCH_NAME * sizeof(wchar_t))
199
200 /*! \brief Maximum level of nesting for configuration spaces
201  */
202 #define KCONF_MAX_DEPTH 16
203
204 /*! \brief Maximum number of allowed characters (including terminating NULL) in a configuration path */
205 #define KCONF_MAXCCH_PATH (KCONF_MAXCCH_NAME * KCONF_MAX_DEPTH)
206
207 /*! \brief Maximum number of allowed bytes (including terminating NULL) in a configuration path */
208 #define KCONF_MAXCB_PATH (KCONF_MAXCCH_PATH * sizeof(wchar_t))
209
210 /*! \brief Maximum number of allowed characters (including terminating NULL) in a string */
211 #define KCONF_MAXCCH_STRING KHM_MAXCCH_STRING
212
213 /*! \brief Maximum number of allowed bytes (including terminating NULL) in a string */
214 #define KCONF_MAXCB_STRING (KCONF_MAXCCH_STRING * sizeof(wchar_t))
215
216 /*! \brief Open a configuration space
217
218     Opens the configuration space specified by \a cspace.  By default,
219     the opened space includes user,machine and schema configuration
220     stores.  However, you can specify a subset of these.
221
222     If the configuration space does not exist and the \a flags specify
223     KHM_FLAG_CREATE, then the configuration space is created.  The
224     stores that are affected by the create operation depend on \a
225     flags.  If the \a flags only specifies ::KCONF_FLAG_MACHINE, then
226     the configuration space is created in the machine store.  If \a
227     flags specifies any combination of stores including \a
228     ::KCONF_FLAG_USER, then the configuration space is created in the
229     user store.  Note that ::KCONF_FLAG_SCHEMA is readonly.
230
231     Once opened, use khc_close_space() to close the configuration
232     space.
233
234     \param[in] parent The parent configuration space.  The path
235         specified in \a cspace is relative to the parent.  Set this to
236         NULL to indicate the root configuration space.  
237
238     \param[in] cspace The confiuration path.  This can be up to
239         ::KCONF_MAXCCH_PATH characters in length.  Use either
240         backslashes or forward slashes to specify hiearchy.  Set this
241         to NULL to reopen the parent configuration space.
242
243     \param[in] flags Flags.  This can be a combination of KCONF_FLAG_*
244         constants and KHM_FLAG_CREATE.  If none of ::KCONF_FLAG_USER,
245         ::KCONF_FLAG_MACHINE or ::KCONF_FLAG_SCHEMA is specified, then
246         it defaults to all three.
247
248     \param[out] result Pointer to a handle which receives the handle
249         to the opened configuration space if the call succeeds.
250
251     \note You can re-open a configuration space with different flags
252         such as ::KCONF_FLAG_MACHINE by specifying NULL for \a cspace
253         and settings \a flags to the required flags.
254
255 */
256 KHMEXP khm_int32 KHMAPI 
257 khc_open_space(khm_handle parent, const wchar_t * cspace, khm_int32 flags, 
258                khm_handle * result);
259
260 /*! \brief Set the shadow space for a configuration handle
261
262     The handle specified by \a lower becomes a shadow for the handle
263     specified by \a upper.  Any configuration value that is queried in
264     \a upper that does not exist in \a upper will be queried in \a
265     lower.
266
267     If \a upper already had a shadow handle, that handle will be
268     replaced by \a lower.  The handle \a lower still needs to be
269     closed by a call to khc_close_space().  However, closing \a lower
270     will not affect \a upper which will still treat the configuration
271     space pointed to by \a lower to be it's shadow.
272
273     Shadows are specific to handles and not configuration spaces.
274     Shadowing a configuration space using one handle does not affect
275     any other handles which may be obtained for the same configuration
276     space.
277
278     Specify NULL for \a lower to remove any prior shadow.
279  */
280 KHMEXP khm_int32 KHMAPI 
281 khc_shadow_space(khm_handle upper, khm_handle lower);
282
283 /*! \brief Close a handle opened with khc_open_space()
284 */
285 KHMEXP khm_int32 KHMAPI 
286 khc_close_space(khm_handle conf);
287
288 /*! \brief Read a string value from a configuration space
289
290     The \a value_name parameter specifies the value to read from the
291     configuration space.  This can be either a value name or a value
292     path consisting of a series nested configuration space names
293     followed by the value name all separated by backslashes or forward
294     slashes.
295
296     For example: If \a conf is a handle to the configuration space \c
297     'A/B/C', then the value name \c 'D/E/v' refers to the value named
298     \c 'v' in the configuration space \c 'A/B/C/D/E'.
299
300     The specific configuration store that is used to access the value
301     depends on the flags that were specified in the call to
302     khc_open_space().  The precedence of configuration stores are as
303     follows:
304
305     - If KCONF_FLAG_USER was specified, then the user configuration
306       space.
307
308     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
309       configuration space.
310
311     - Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
312       store.
313
314     Note that not specifying any of the configuration store specifiers
315     in the call to khc_open_space() is equivalent to specifying all
316     three.
317
318     If the value is not found in the configuration space and any
319     shadowed configuration spaces, the function returns \a
320     KHM_ERROR_NOT_FOUND.  In this case, the buffer is left unmodified.
321
322     \param[in] buf Buffer to copy the string to.  Specify NULL to just
323         retrieve the number of required bytes.
324     
325     \param[in,out] bufsize On entry, specifies the number of bytes of
326         space available at the location specified by \a buf.  On exit
327         specifies the number of bytes actually copied or the size of
328         the required buffer if \a buf is NULL or insufficient.
329
330     \retval KHM_ERROR_NOT_READY The configuration provider has not started
331     \retval KHM_ERROR_INVALID_PARAM One or more of the supplied parameters are not valid
332     \retval KHM_ERROR_TYPE_MISMATCH The specified value is not a string
333     \retval KHM_ERROR_TOO_LONG \a buf was NULL or the size of the buffer was insufficient.  The required size is in bufsize.
334     \retval KHM_ERROR_SUCCESS Success.  The number of bytes copied is in bufsize.
335     \retval KHM_ERROR_NOT_FOUND The value was not found.
336
337     \see khc_open_space()
338 */
339 KHMEXP khm_int32 KHMAPI 
340 khc_read_string(khm_handle conf, 
341                 const wchar_t * value_name, 
342                 wchar_t * buf, 
343                 khm_size * bufsize);
344
345 /*! \brief Read a multi-string value from a configuration space
346
347     The \a value_name parameter specifies the value to read from the
348     configuration space.  This can be either a value name or a value
349     path consisting of a series nested configuration space names
350     followed by the value name all separated by backslashes or forward
351     slashes.
352
353     For example: If \a conf is a handle to the configuration space \c
354     'A/B/C', then the value name \c 'D/E/v' refers to the value named
355     \c 'v' in the configuration space \c 'A/B/C/D/E'.
356
357     The specific configuration store that is used to access the value
358     depends on the flags that were specified in the call to
359     khc_open_space().  The precedence of configuration stores are as
360     follows:
361
362     - If KCONF_FLAG_USER was specified, then the user configuration
363       space.
364
365     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
366       configuration space.
367
368     - Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
369       store.
370
371     A multi-string is a pseudo data type.  The value in the
372     configuration store should contain a CSV string.  Each comma
373     separated value in the CSV string is considered to be a separate
374     value.  Empty values are not allowed. The buffer pointed to by \a
375     buf will receive these values in the form of a series of NULL
376     terminated strings terminated by an empty string (or equivalently,
377     the last string will be terminated by a double NULL).
378
379     Note that not specifying any of the configuration store specifiers
380     in the call to khc_open_space() is equivalent to specifying all
381     three.
382
383     If the value is not found in the configuration space and any
384     shadowed configuration spaces, the function returns \a
385     KHM_ERROR_NOT_FOUND.  In this case, the buffer is left unmodified.
386
387     \param[in] buf Buffer to copy the multi-string to.  Specify NULL
388         to just retrieve the number of required bytes.
389     
390     \param[in,out] bufsize On entry, specifies the number of bytes of
391         space available at the location specified by \a buf.  On exit
392         specifies the number of bytes actually copied or the size of
393         the required buffer if \a buf is NULL or insufficient.
394
395     \retval KHM_ERROR_NOT_READY The configuration provider has not started
396     \retval KHM_ERROR_INVALID_PARAM One or more of the supplied parameters are not valid
397     \retval KHM_ERROR_TYPE_MISMATCH The specified value is not a string
398     \retval KHM_ERROR_TOO_LONG \a buf was NULL or the size of the buffer was insufficient.  The required size is in bufsize.
399     \retval KHM_ERROR_SUCCESS Success.  The number of bytes copied is in bufsize.
400     \retval KHM_ERROR_NOT_FOUND The value was not found.
401
402     \see khc_open_space()
403 */
404 KHMEXP khm_int32 KHMAPI 
405 khc_read_multi_string(khm_handle conf, 
406                       const wchar_t * value_name, 
407                       wchar_t * buf, 
408                       khm_size * bufsize);
409
410 /*! \brief Read a 32 bit integer value from a configuration space
411
412     The \a value_name parameter specifies the value to read from the
413     configuration space.  This can be either a value name or a value
414     path consisting of a series nested configuration space names
415     followed by the value name all separated by backslashes or forward
416     slashes.
417
418     For example: If \a conf is a handle to the configuration space \c
419     'A/B/C', then the value name \c 'D/E/v' refers to the value named
420     \c 'v' in the configuration space \c 'A/B/C/D/E'.
421
422     The specific configuration store that is used to access the value
423     depends on the flags that were specified in the call to
424     khc_open_space().  The precedence of configuration stores are as
425     follows:
426
427     - If KCONF_FLAG_USER was specified, then the user configuration
428       space.
429
430     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
431       configuration space.
432
433     - Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
434       store.
435
436     Note that not specifying any of the configuration store specifiers
437     in the call to khc_open_space() is equivalent to specifying all
438     three.
439
440     If the value is not found in the configuration space and any
441     shadowed configuration spaces, the function returns \a
442     KHM_ERROR_NOT_FOUND.  In this case, the buffer is left unmodified.
443
444     \param[in] conf Handle to a configuration space
445     \param[in] value The value to query
446     \param[out] buf The buffer to receive the value
447
448     \retval KHM_ERROR_NOT_READY The configuration provider has not started.
449     \retval KHM_ERROR_SUCCESS Success.  The value that was read was placed in \a buf
450     \retval KHM_ERROR_NOT_FOUND The specified value was not found
451     \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid
452     \retval KHM_ERROR_TYPE_MISMATCH The specified value was found but was not of the correct type.
453     \see khc_open_space()
454 */
455 KHMEXP khm_int32 KHMAPI 
456 khc_read_int32(khm_handle conf, 
457                const wchar_t * value_name, 
458                khm_int32 * buf);
459
460 /*! \brief Read a 64 bit integer value from a configuration space
461
462     The \a value_name parameter specifies the value to read from the
463     configuration space.  This can be either a value name or a value
464     path consisting of a series nested configuration space names
465     followed by the value name all separated by backslashes or forward
466     slashes.
467
468     For example: If \a conf is a handle to the configuration space \c
469     'A/B/C', then the value name \c 'D/E/v' refers to the value named
470     \c 'v' in the configuration space \c 'A/B/C/D/E'.
471
472     The specific configuration store that is used to access the value
473     depends on the flags that were specified in the call to
474     khc_open_space().  The precedence of configuration stores are as
475     follows:
476
477     - If KCONF_FLAG_USER was specified, then the user configuration
478       space.
479
480     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
481       configuration space.
482
483     - Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
484       store.
485
486     Note that not specifying any of the configuration store specifiers
487     in the call to khc_open_space() is equivalent to specifying all
488     three.
489
490     If the value is not found in the configuration space and any
491     shadowed configuration spaces, the function returns \a
492     KHM_ERROR_NOT_FOUND.  In this case, the buffer is left unmodified.
493
494     \param[in] conf Handle to a configuration space
495     \param[in] value_name The value to query
496     \param[out] buf The buffer to receive the value
497
498     \retval KHM_ERROR_NOT_READY The configuration provider has not started
499     \retval KHM_ERROR_SUCCESS Success.  The value that was read was placed in \a buf
500     \retval KHM_ERROR_NOT_FOUND The specified value was not found
501     \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid
502     \retval KHM_ERROR_TYPE_MISMATCH The specified value was found but was not the correct data type.
503
504     \see khc_open_space()
505 */
506 KHMEXP khm_int32 KHMAPI 
507 khc_read_int64(khm_handle conf, 
508                const wchar_t * value_name, 
509                khm_int64 * buf);
510
511 /*! \brief Read a binary value from a configuration space
512
513     The \a value_name parameter specifies the value to read from the
514     configuration space.  This can be either a value name or a value
515     path consisting of a series nested configuration space names
516     followed by the value name all separated by backslashes or forward
517     slashes.
518
519     For example: If \a conf is a handle to the configuration space \c
520     'A/B/C', then the value name \c 'D/E/v' refers to the value named
521     \c 'v' in the configuration space \c 'A/B/C/D/E'.
522
523     The specific configuration store that is used to access the value
524     depends on the flags that were specified in the call to
525     khc_open_space().  The precedence of configuration stores are as
526     follows:
527
528     - If KCONF_FLAG_USER was specified, then the user configuration
529       space.
530
531     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
532       configuration space.
533
534     Note that not specifying any of the configuration store specifiers
535     in the call to khc_open_space() is equivalent to specifying all
536     three. Also note that the schema store (KCONF_FLAG_SCHEMA) does
537     not support binary values.
538
539     If the value is not found in the configuration space and any
540     shadowed configuration spaces, the function returns \a
541     KHM_ERROR_NOT_FOUND.  In this case, the buffer is left unmodified.
542
543     \param[in] buf Buffer to copy the string to.  Specify NULL to just
544         retrieve the number of required bytes.
545     
546     \param[in,out] bufsize On entry, specifies the number of bytes of
547         space available at the location specified by \a buf.  On exit
548         specifies the number of bytes actually copied or the size of
549         the required buffer if \a buf is NULL or insufficient.
550
551     \retval KHM_ERROR_SUCCESS Success. The data was copied to \a buf.  The number of bytes copied is stored in \a bufsize
552     \retval KHM_ERROR_NOT_FOUND The specified value was not found
553     \retval KHM_ERROR_INVALID_PARAM One or more parameters were invalid.
554
555     \see khc_open_space()
556 */
557 KHMEXP khm_int32 KHMAPI 
558 khc_read_binary(khm_handle conf, 
559                 const wchar_t * value_name, 
560                 void * buf, 
561                 khm_size * bufsize);
562
563 /*! \brief Write a string value to a configuration space
564
565     The \a value_name parameter specifies the value to write to the
566     configuration space.  This can be either a value name or a value
567     path consisting of a series nested configuration space names
568     followed by the value name all separated by backslashes or forward
569     slashes.
570
571     For example: If \a conf is a handle to the configuration space \c
572     'A/B/C', then the value name \c 'D/E/v' refers to the value named
573     \c 'v' in the configuration space \c 'A/B/C/D/E'.
574
575     The specific configuration store that is used to write the value
576     depends on the flags that were specified in the call to
577     khc_open_space().  The precedence of configuration stores are as
578     follows:
579
580     - If \a KCONF_FLAG_USER was specified, then the user configuration
581       space.
582
583     - Otherwise, if \a KCONF_FLAG_MACHINE was specified, then the
584       machine configuration space.
585
586     Note that not specifying any of the configuration store specifiers
587     in the call to khc_open_space() is equivalent to specifying all
588     three.  Also note that the schema store (KCONF_FLAG_SCHEMA) is
589     readonly.
590
591     If the \a KCONF_FLAG_WRITEIFMOD flag is specified in the call to
592     khc_open_space() for obtaining the configuration handle, the
593     specified string will only be written if it is different from the
594     value being read from the handle.
595
596     If the \a KCONF_FLAG_IFMODCI flag is specified along with the \a
597     KCONF_FLAG_WRITEIFMOD flag, then the string comparison used will
598     be case insensitive.
599
600     \param[in] conf Handle to a configuration space
601     \param[in] value_name Name of value to write
602     \param[in] buf A NULL terminated unicode string not exceeding KCONF_MAXCCH_STRING in characters including terminating NULL
603
604     \see khc_open_space()
605 */
606 KHMEXP khm_int32 KHMAPI 
607 khc_write_string(khm_handle conf, 
608                  const wchar_t * value_name, 
609                  wchar_t * buf);
610
611 /*! \brief Write a multi-string value to a configuration space
612
613     The \a value_name parameter specifies the value to write to the
614     configuration space.  This can be either a value name or a value
615     path consisting of a series nested configuration space names
616     followed by the value name all separated by backslashes or forward
617     slashes.
618
619     For example: If \a conf is a handle to the configuration space \c
620     'A/B/C', then the value name \c 'D/E/v' refers to the value named
621     \c 'v' in the configuration space \c 'A/B/C/D/E'.
622
623     The specific configuration store that is used to write the value
624     depends on the flags that were specified in the call to
625     khc_open_space().  The precedence of configuration stores are as
626     follows:
627
628     A multi-string is a pseudo data type.  The buffer pointed to by \a
629     buf should contain a sequence of NULL terminated strings
630     terminated by an empty string (or equivalently, the last string
631     should terminate with a double NULL).  This will be stored in the
632     value as a CSV string.
633
634     - If KCONF_FLAG_USER was specified, then the user configuration
635       space.
636
637     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
638       configuration space.
639
640     Note that not specifying any of the configuration store specifiers
641     in the call to khc_open_space() is equivalent to specifying all
642     three.  Also note that the schema store (KCONF_FLAG_SCHEMA) is
643     readonly.
644
645     If the \a KCONF_FLAG_WRITEIFMOD flag is specified in the call to
646     khc_open_space() for obtaining the configuration handle, the
647     specified string will only be written if it is different from the
648     value being read from the handle.
649
650     If the \a KCONF_FLAG_IFMODCI flag is specified along with the \a
651     KCONF_FLAG_WRITEIFMOD flag, then the string comparison used will
652     be case insensitive.
653
654     \see khc_open_space()
655 */
656 KHMEXP khm_int32 KHMAPI 
657 khc_write_multi_string(khm_handle conf, 
658                        const wchar_t * value_name, 
659                        wchar_t * buf);
660
661 /*! \brief Write a 32 bit integer value to a configuration space
662
663     The \a value_name parameter specifies the value to write to the
664     configuration space.  This can be either a value name or a value
665     path consisting of a series nested configuration space names
666     followed by the value name all separated by backslashes or forward
667     slashes.
668
669     For example: If \a conf is a handle to the configuration space \c
670     'A/B/C', then the value name \c 'D/E/v' refers to the value named
671     \c 'v' in the configuration space \c 'A/B/C/D/E'.
672
673     The specific configuration store that is used to write the value
674     depends on the flags that were specified in the call to
675     khc_open_space().  The precedence of configuration stores are as
676     follows:
677
678     - If KCONF_FLAG_USER was specified, then the user configuration
679       space.
680
681     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
682       configuration space.
683
684     Note that not specifying any of the configuration store specifiers
685     in the call to khc_open_space() is equivalent to specifying all
686     three.  Also note that the schema store (KCONF_FLAG_SCHEMA) is
687     readonly.
688
689     If the \a KCONF_FLAG_WRITEIFMOD flag is specified in the call to
690     khc_open_space() for obtaining the configuration handle, the
691     specified string will only be written if it is different from the
692     value being read from the handle.
693
694     \see khc_open_space()
695 */
696 KHMEXP khm_int32 KHMAPI 
697 khc_write_int32(khm_handle conf, 
698                 const wchar_t * value_name, 
699                 khm_int32 buf);
700
701 /*! \brief Write a 64 bit integer value to a configuration space
702
703     The \a value_name parameter specifies the value to write to the
704     configuration space.  This can be either a value name or a value
705     path consisting of a series nested configuration space names
706     followed by the value name all separated by backslashes or forward
707     slashes.
708
709     For example: If \a conf is a handle to the configuration space \c
710     'A/B/C', then the value name \c 'D/E/v' refers to the value named
711     \c 'v' in the configuration space \c 'A/B/C/D/E'.
712
713     The specific configuration store that is used to write the value
714     depends on the flags that were specified in the call to
715     khc_open_space().  The precedence of configuration stores are as
716     follows:
717
718     - If KCONF_FLAG_USER was specified, then the user configuration
719       space.
720
721     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
722       configuration space.
723
724     Note that not specifying any of the configuration store specifiers
725     in the call to khc_open_space() is equivalent to specifying all
726     three.  Also note that the schema store (KCONF_FLAG_SCHEMA) is
727     readonly.
728
729     If the \a KCONF_FLAG_WRITEIFMOD flag is specified in the call to
730     khc_open_space() for obtaining the configuration handle, the
731     specified string will only be written if it is different from the
732     value being read from the handle.
733
734     \see khc_open_space()
735 */
736 KHMEXP khm_int32 KHMAPI 
737 khc_write_int64(khm_handle conf, 
738                 const wchar_t * value_name, 
739                 khm_int64 buf);
740
741 /*! \brief Write a binary value to a configuration space
742
743     The \a value_name parameter specifies the value to write to the
744     configuration space.  This can be either a value name or a value
745     path consisting of a series nested configuration space names
746     followed by the value name all separated by backslashes or forward
747     slashes.
748
749     For example: If \a conf is a handle to the configuration space \c
750     'A/B/C', then the value name \c 'D/E/v' refers to the value named
751     \c 'v' in the configuration space \c 'A/B/C/D/E'.
752
753     The specific configuration store that is used to write the value
754     depends on the flags that were specified in the call to
755     khc_open_space().  The precedence of configuration stores are as
756     follows:
757
758     - If KCONF_FLAG_USER was specified, then the user configuration
759       space.
760
761     - Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
762       configuration space.
763
764     Note that not specifying any of the configuration store specifiers
765     in the call to khc_open_space() is equivalent to specifying all
766     three.  Also note that the schema store (KCONF_FLAG_SCHEMA) is
767     readonly.
768
769     \see khc_open_space()
770 */
771 KHMEXP khm_int32 KHMAPI 
772 khc_write_binary(khm_handle conf, 
773                  const wchar_t * value_name, 
774                  void * buf, 
775                  khm_size bufsize);
776
777 /*! \brief Get the type of a value in a configuration space
778
779     \return The return value is the type of the specified value, or
780         KC_NONE if the value does not exist.
781  */
782 KHMEXP khm_int32 KHMAPI 
783 khc_get_type(khm_handle conf, const wchar_t * value_name);
784
785 /*! \brief Check which configuration stores contain a specific value.
786
787     Each value in a configuration space can be contained in zero or
788     more configuration stores.  Use this function to determine which
789     configuration stores contain the specific value.
790
791     The returned bitmask always indicates a subset of the
792     configuration stores that were specified when opening the
793     configuration space corresponding to \a conf.
794
795     \return A combination of ::KCONF_FLAG_MACHINE, ::KCONF_FLAG_USER
796         and ::KCONF_FLAG_SCHEMA indicating which stores contain the
797         value.
798  */
799 KHMEXP khm_int32 KHMAPI 
800 khc_value_exists(khm_handle conf, const wchar_t * value);
801
802 /*! \brief Remove a value from a configuration space
803
804     Removes a value from one or more configuration stores.
805
806     A value can exist in multiple configuration stores.  Only the
807     values that are stored in writable stores can be removed.  When
808     the function searches for values to remove, it will only look in
809     configuration stores that are specified in the handle.  In
810     addition, the configuration stores affected can be further
811     narrowed by specifying them in the \a flags parameter.  If \a
812     flags is zero, then all the stores visible to the handle are
813     searched.  If \a flags specifies ::KCONF_FLAG_USER or
814     ::KCONF_FLAG_MACHINE or both, then only the specified stores are
815     searched, provided that the stores are visible to the handle.
816
817     This function only operates on the topmost configuration space
818     visible to the handle.  If the configuration handle is shadowed,
819     the shadowed configuration spaces are unaffected by the removal.
820
821     \param[in] conf Handle to configuration space to remove value from
822
823     \param[in] value_name Value to remove
824
825     \param[in] flags Specifies which configuration stores will be
826         affected by the removal.  See above.
827
828     \retval KHM_ERROR_SUCCESS The value was removed from all the
829         specified configuration stores.
830
831     \retval KHM_ERROR_NOT_FOUND The value was not found.
832
833     \retval KHM_ERROR_UNKNOWN An unknown error occurred while trying
834         to remove the value.
835
836     \retval KHM_ERROR_PARTIAL The value was successfully removed from
837         one or more stores, but the operation failed on one or more
838         other stores.
839  */
840 KHMEXP khm_int32 KHMAPI
841 khc_remove_value(khm_handle conf, const wchar_t * value_name, khm_int32 flags);
842
843 /*! \brief Get the name of a configuration space
844
845     \param[in] conf Handle to a configuration space
846
847     \param[out] buf The buffer to receive the name.  Set to NULL if
848         only the size of the buffer is required.
849
850     \param[in,out] bufsize On entry, holds the size of the buffer
851         pointed to by \a buf.  On exit, holds the number of bytes
852         copied into the buffer including the NULL terminator.
853  */
854 KHMEXP khm_int32 KHMAPI 
855 khc_get_config_space_name(khm_handle conf, 
856                           wchar_t * buf, 
857                           khm_size * bufsize);
858
859 /*! \brief Get a handle to the parent space
860
861     \param[in] conf Handle to a configuration space
862
863     \param[out] parent Handle to the parent configuration space if the
864         call succeeds.  Receives NULL otherwise.  The returned handle
865         must be closed using khc_close_space()
866  */
867 KHMEXP khm_int32 KHMAPI 
868 khc_get_config_space_parent(khm_handle conf, 
869                             khm_handle * parent);
870
871 /*! \brief Load a configuration schema into the specified configuration space
872
873     \param[in] conf Handle to a configuration space or NULL to use the
874         root configuration space.
875
876     \param[in] schema The schema to load.  The schema is assumed to be
877         well formed.
878
879     \see khc_unload_schema()
880  */
881 KHMEXP khm_int32 KHMAPI 
882 khc_load_schema(khm_handle conf, 
883                 const kconf_schema * schema);
884
885 /*! \brief Unload a schema from a configuration space
886  */
887 KHMEXP khm_int32 KHMAPI 
888 khc_unload_schema(khm_handle conf, 
889                   const kconf_schema * schema);
890
891 /*! \brief Enumerate the subspaces of a configuration space
892
893     Prepares a configuration space for enumeration and returns the
894     child spaces in no particular order.
895
896     \param[in] conf The configuration space to enumerate child spaces
897
898     \param[in] prev The previous configuration space returned by
899         khc_enum_subspaces() or NULL if this is the first call.  If
900         this is not NULL, then the handle passed in \a prev will be
901         freed.
902
903     \param[out] next If \a prev was NULL, receives the first sub space
904         found in \a conf.  You must \b either call
905         khc_enum_subspaces() again with the returned handle or call
906         khc_close_space() to free the returned handle if no more
907         subspaces are required.  \a next can point to the same handle
908         specified in \a prev.
909
910     \retval KHM_ERROR_SUCCESS The call succeeded.  There is a valid
911         handle to a configuration space in \a first_subspace.
912
913     \retval KHM_ERROR_INVALID_PARAM Either \a conf or \a prev was not a
914         valid configuration space handle or \a first_subspace is NULL.
915         Note that \a prev can be NULL.
916
917     \retval KHM_ERROR_NOT_FOUND There were no subspaces in the
918         configuration space pointed to by \a conf.
919
920     \note The configuration spaces that are enumerated directly belong
921         to the configuration space given by \a conf.  This function
922         does not enumerate subspaces of shadowed configuration spaces
923         (see khc_shadow_space()).  Even if \a conf was obtained on a
924         restricted domain (i.e. you specified one or more
925         configuration stores when you openend the handle and didn't
926         include all the configuration stores. See khc_open_space()),
927         the subspaces that are returned are the union of all
928         configuration spaces in all the configuration stores.  This is
929         not a bug.  This is a feature.  In NetIDMgr, a configuartion
930         space exists if some configuration store defines it (or it was
931         created with a call to khc_open_space() even if no
932         configuration store defines it yet).  This is the tradeoff you
933         make when using a layered configuration system.
934
935         However, the returned handle has the same domain restrictions
936         as \a conf.
937  */
938 KHMEXP khm_int32 KHMAPI 
939 khc_enum_subspaces(khm_handle conf,
940                    khm_handle prev,
941                    khm_handle * next);
942
943 /*! \brief Remove a configuration space
944
945     The configuration space will be marked for removal.  Once all the
946     handles for the space have been released, it will be deleted.  The
947     configuration stores that will be affected are the write enabled
948     configuration stores for the handle.
949  */
950 KHMEXP khm_int32 KHMAPI
951 khc_remove_space(khm_handle conf);
952 /*@}*/
953
954 #endif