2
* Copyright (c) 2005 Massachusetts Institute of Technology
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:
12
* The above copyright notice and this permission notice shall be
13
* included in all copies or substantial portions of the Software.
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
27
#ifndef __KHIMAIRA_KCONFIG_H
28
#define __KHIMAIRA_KCONFIG_H
33
/*! \defgroup kconf NetIDMgr Configuration Provider */
36
/*! \brief Configuration schema descriptor record
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.
43
\see kconf_load_schema()
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
65
wchar_t * description;/*!< a friendly description of the value
66
or configuration space. */
69
/*! \name Configuration data types
71
/*! \brief Not a known type */
74
/*! \brief When used as ::kconf_schema \a type, defines the start of a configuration space.
76
There should be a subsequent KC_ENDSPACE record in the schema
77
which defines the end of this configuration space.
79
\a name specifies the name of the configuration space. Optionally
80
use \a description to provide a description.*/
83
/*! \brief Ends a configuration space started with KC_SPACE */
86
/*! \brief A 32 bit integer
88
Specifies a configuration parameter named \a name which is of this
89
type. Use \a description to provide an optional description of
92
\a value specifies a default value for this parameter in the lower
97
/*! \brief A 64 bit integer
99
Specifies a configuration parameter named \a name which is of this
100
type. Use \a description to provide an optional description of
103
\a value specifies a default value for this parameter.
107
/*! \brief A unicode string
109
Specifies a configuration parameter named \a name which is of this
110
type. Use \a description to provide an optional description of
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.
119
/*! \brief An unparsed binary stream
121
Specifies a configuration parameter named \a name which is of this
122
type. Use \a description to provide an optional description of
125
Default values are not supported for binary streams. \a value is
131
/*! \brief This is the root configuration space */
132
#define KCONF_FLAG_ROOT 0x00000001
134
/*! \brief Indicates the configuration store which stores user-specific information */
135
#define KCONF_FLAG_USER 0x00000002
137
/*! \brief Indicates the configuration store which stores machine-specific information */
138
#define KCONF_FLAG_MACHINE 0x00000004
140
/*! \brief Indicates the configuration store which stores the schema */
141
#define KCONF_FLAG_SCHEMA 0x00000008
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
146
/*! \brief Only write values back there is a change
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.
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.
157
\note Note also that this flag does not affect binary values.
159
#define KCONF_FLAG_WRITEIFMOD 0x00000040
161
/*! \brief Use case-insensitive comparison for KCONF_FLAG_WRITEIFMOD
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.
169
#define KCONF_FLAG_IFMODCI 0x00000080
171
/*! \brief Do not parse the configuration space name
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.
178
By default, the configuration space name,
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.
188
#define KCONF_FLAG_NOPARSENAME 0x00000040
190
/*! \brief Maximum number of allowed characters (including terminating NULL) in a name
192
\note This is a hard limit in Windows, since we are mapping
193
configuration spaces to registry keys.
195
#define KCONF_MAXCCH_NAME 256
197
/*! \brief Maximum number of allowed bytes (including terminating NULL) in a name */
198
#define KCONF_MAXCB_NAME (KCONF_MAXCCH_NAME * sizeof(wchar_t))
200
/*! \brief Maximum level of nesting for configuration spaces
202
#define KCONF_MAX_DEPTH 16
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)
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))
210
/*! \brief Maximum number of allowed characters (including terminating NULL) in a string */
211
#define KCONF_MAXCCH_STRING KHM_MAXCCH_STRING
213
/*! \brief Maximum number of allowed bytes (including terminating NULL) in a string */
214
#define KCONF_MAXCB_STRING (KCONF_MAXCCH_STRING * sizeof(wchar_t))
216
/*! \brief Open a configuration space
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.
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.
231
Once opened, use khc_close_space() to close the configuration
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.
238
\param[in] cspace The configuration path. This can be up to
239
::KCONF_MAXCCH_PATH characters in length. Use backslashes to
240
specify hiearchy. Set this to NULL to reopen the parent
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.
248
\param[out] result Pointer to a handle which receives the handle
249
to the opened configuration space if the call succeeds.
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.
256
KHMEXP khm_int32 KHMAPI
257
khc_open_space(khm_handle parent, const wchar_t * cspace, khm_int32 flags,
258
khm_handle * result);
260
/*! \brief Set the shadow space for a configuration handle
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
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.
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
278
Specify NULL for \a lower to remove any prior shadow.
280
KHMEXP khm_int32 KHMAPI
281
khc_shadow_space(khm_handle upper, khm_handle lower);
283
/*! \brief Close a handle opened with khc_open_space()
285
KHMEXP khm_int32 KHMAPI
286
khc_close_space(khm_handle conf);
288
/*! \brief Read a string value from a configuration space
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
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'.
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
305
- If KCONF_FLAG_USER was specified, then the user configuration
308
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
311
- Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
314
Note that not specifying any of the configuration store specifiers
315
in the call to khc_open_space() is equivalent to specifying all
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.
322
\param[in] buf Buffer to copy the string to. Specify NULL to just
323
retrieve the number of required bytes.
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.
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.
337
\see khc_open_space()
339
KHMEXP khm_int32 KHMAPI
340
khc_read_string(khm_handle conf,
341
const wchar_t * value_name,
345
/*! \brief Read a multi-string value from a configuration space
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
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'.
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
362
- If KCONF_FLAG_USER was specified, then the user configuration
365
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
368
- Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
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).
379
Note that not specifying any of the configuration store specifiers
380
in the call to khc_open_space() is equivalent to specifying all
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.
387
\param[in] buf Buffer to copy the multi-string to. Specify NULL
388
to just retrieve the number of required bytes.
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.
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.
402
\see khc_open_space()
404
KHMEXP khm_int32 KHMAPI
405
khc_read_multi_string(khm_handle conf,
406
const wchar_t * value_name,
410
/*! \brief Read a 32 bit integer value from a configuration space
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
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'.
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
427
- If KCONF_FLAG_USER was specified, then the user configuration
430
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
433
- Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
436
Note that not specifying any of the configuration store specifiers
437
in the call to khc_open_space() is equivalent to specifying all
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.
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
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()
455
KHMEXP khm_int32 KHMAPI
456
khc_read_int32(khm_handle conf,
457
const wchar_t * value_name,
460
/*! \brief Read a 64 bit integer value from a configuration space
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
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'.
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
477
- If KCONF_FLAG_USER was specified, then the user configuration
480
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
483
- Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema
486
Note that not specifying any of the configuration store specifiers
487
in the call to khc_open_space() is equivalent to specifying all
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.
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
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.
504
\see khc_open_space()
506
KHMEXP khm_int32 KHMAPI
507
khc_read_int64(khm_handle conf,
508
const wchar_t * value_name,
511
/*! \brief Read a binary value from a configuration space
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
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'.
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
528
- If KCONF_FLAG_USER was specified, then the user configuration
531
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
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.
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.
543
\param[in] buf Buffer to copy the string to. Specify NULL to just
544
retrieve the number of required bytes.
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.
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.
555
\see khc_open_space()
557
KHMEXP khm_int32 KHMAPI
558
khc_read_binary(khm_handle conf,
559
const wchar_t * value_name,
563
/*! \brief Write a string value to a configuration space
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
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'.
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
580
- If \a KCONF_FLAG_USER was specified, then the user configuration
583
- Otherwise, if \a KCONF_FLAG_MACHINE was specified, then the
584
machine configuration space.
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
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.
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
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
604
\see khc_open_space()
606
KHMEXP khm_int32 KHMAPI
607
khc_write_string(khm_handle conf,
608
const wchar_t * value_name,
611
/*! \brief Write a multi-string value to a configuration space
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
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'.
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
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.
634
- If KCONF_FLAG_USER was specified, then the user configuration
637
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
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
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.
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
654
\see khc_open_space()
656
KHMEXP khm_int32 KHMAPI
657
khc_write_multi_string(khm_handle conf,
658
const wchar_t * value_name,
661
/*! \brief Write a 32 bit integer value to a configuration space
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
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'.
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
678
- If KCONF_FLAG_USER was specified, then the user configuration
681
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
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
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.
694
\see khc_open_space()
696
KHMEXP khm_int32 KHMAPI
697
khc_write_int32(khm_handle conf,
698
const wchar_t * value_name,
701
/*! \brief Write a 64 bit integer value to a configuration space
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
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'.
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
718
- If KCONF_FLAG_USER was specified, then the user configuration
721
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
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
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.
734
\see khc_open_space()
736
KHMEXP khm_int32 KHMAPI
737
khc_write_int64(khm_handle conf,
738
const wchar_t * value_name,
741
/*! \brief Write a binary value to a configuration space
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
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'.
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
758
- If KCONF_FLAG_USER was specified, then the user configuration
761
- Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine
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
769
\see khc_open_space()
771
KHMEXP khm_int32 KHMAPI
772
khc_write_binary(khm_handle conf,
773
const wchar_t * value_name,
777
/*! \brief Get the type of a value in a configuration space
779
\return The return value is the type of the specified value, or
780
KC_NONE if the value does not exist.
782
KHMEXP khm_int32 KHMAPI
783
khc_get_type(khm_handle conf, const wchar_t * value_name);
785
/*! \brief Check which configuration stores contain a specific value.
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.
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.
795
If the specified handle is shadowed (see khc_shadow_space()) and
796
the value is not found in any of the visible stores for the
797
topmost handle, each of the shadowed handles will be tried in turn
798
until the value is found. The return value will correspond to the
799
handle where the value is first found.
801
\return A combination of ::KCONF_FLAG_MACHINE, ::KCONF_FLAG_USER
802
and ::KCONF_FLAG_SCHEMA indicating which stores contain the
805
KHMEXP khm_int32 KHMAPI
806
khc_value_exists(khm_handle conf, const wchar_t * value);
808
/*! \brief Remove a value from a configuration space
810
Removes a value from one or more configuration stores.
812
A value can exist in multiple configuration stores. Only the
813
values that are stored in writable stores can be removed. When
814
the function searches for values to remove, it will only look in
815
configuration stores that are specified in the handle. In
816
addition, the configuration stores affected can be further
817
narrowed by specifying them in the \a flags parameter. If \a
818
flags is zero, then all the stores visible to the handle are
819
searched. If \a flags specifies ::KCONF_FLAG_USER or
820
::KCONF_FLAG_MACHINE or both, then only the specified stores are
821
searched, provided that the stores are visible to the handle.
823
This function only operates on the topmost configuration space
824
visible to the handle. If the configuration handle is shadowed,
825
the shadowed configuration spaces are unaffected by the removal.
827
\param[in] conf Handle to configuration space to remove value from
829
\param[in] value_name Value to remove
831
\param[in] flags Specifies which configuration stores will be
832
affected by the removal. See above.
834
\retval KHM_ERROR_SUCCESS The value was removed from all the
835
specified configuration stores.
837
\retval KHM_ERROR_NOT_FOUND The value was not found.
839
\retval KHM_ERROR_UNKNOWN An unknown error occurred while trying
842
\retval KHM_ERROR_PARTIAL The value was successfully removed from
843
one or more stores, but the operation failed on one or more
846
KHMEXP khm_int32 KHMAPI
847
khc_remove_value(khm_handle conf, const wchar_t * value_name, khm_int32 flags);
849
/*! \brief Get the name of a configuration space
851
\param[in] conf Handle to a configuration space
853
\param[out] buf The buffer to receive the name. Set to NULL if
854
only the size of the buffer is required.
856
\param[in,out] bufsize On entry, holds the size of the buffer
857
pointed to by \a buf. On exit, holds the number of bytes
858
copied into the buffer including the NULL terminator.
860
KHMEXP khm_int32 KHMAPI
861
khc_get_config_space_name(khm_handle conf,
865
/*! \brief Get a handle to the parent space
867
\param[in] conf Handle to a configuration space
869
\param[out] parent Handle to the parent configuration space if the
870
call succeeds. Receives NULL otherwise. The returned handle
871
must be closed using khc_close_space()
873
KHMEXP khm_int32 KHMAPI
874
khc_get_config_space_parent(khm_handle conf,
875
khm_handle * parent);
877
/*! \brief Load a configuration schema into the specified configuration space
879
\param[in] conf Handle to a configuration space or NULL to use the
880
root configuration space.
882
\param[in] schema The schema to load. The schema is assumed to be
885
\see khc_unload_schema()
887
KHMEXP khm_int32 KHMAPI
888
khc_load_schema(khm_handle conf,
889
const kconf_schema * schema);
891
/*! \brief Unload a schema from a configuration space
893
KHMEXP khm_int32 KHMAPI
894
khc_unload_schema(khm_handle conf,
895
const kconf_schema * schema);
897
/*! \brief Enumerate the subspaces of a configuration space
899
Prepares a configuration space for enumeration and returns the
900
child spaces in no particular order.
902
\param[in] conf The configuration space to enumerate child spaces
904
\param[in] prev The previous configuration space returned by
905
khc_enum_subspaces() or NULL if this is the first call. If
906
this is not NULL, then the handle passed in \a prev will be
909
\param[out] next If \a prev was NULL, receives the first sub space
910
found in \a conf. You must \b either call
911
khc_enum_subspaces() again with the returned handle or call
912
khc_close_space() to free the returned handle if no more
913
subspaces are required. \a next can point to the same handle
914
specified in \a prev.
916
\retval KHM_ERROR_SUCCESS The call succeeded. There is a valid
917
handle to a configuration space in \a first_subspace.
919
\retval KHM_ERROR_INVALID_PARAM Either \a conf or \a prev was not a
920
valid configuration space handle or \a first_subspace is NULL.
921
Note that \a prev can be NULL.
923
\retval KHM_ERROR_NOT_FOUND There were no subspaces in the
924
configuration space pointed to by \a conf.
926
\note The configuration spaces that are enumerated directly belong
927
to the configuration space given by \a conf. This function
928
does not enumerate subspaces of shadowed configuration spaces
929
(see khc_shadow_space()). Even if \a conf was obtained on a
930
restricted domain (i.e. you specified one or more
931
configuration stores when you openend the handle and didn't
932
include all the configuration stores. See khc_open_space()),
933
the subspaces that are returned are the union of all
934
configuration spaces in all the configuration stores. This is
935
not a bug. This is a feature. In NetIDMgr, a configuartion
936
space exists if some configuration store defines it (or it was
937
created with a call to khc_open_space() even if no
938
configuration store defines it yet). This is the tradeoff you
939
make when using a layered configuration system.
941
However, the returned handle has the same domain restrictions
944
KHMEXP khm_int32 KHMAPI
945
khc_enum_subspaces(khm_handle conf,
949
/*! \brief Remove a configuration space
951
The configuration space will be marked for removal. Once all the
952
handles for the space have been released, it will be deleted. The
953
configuration stores that will be affected are the write enabled
954
configuration stores for the handle.
956
KHMEXP khm_int32 KHMAPI
957
khc_remove_space(khm_handle conf);
added
removed
src/windows/identity/kconfig/kconfig.h
