NetIDMgr Configuration Provider

---

Detailed Description

Data Structures
struct	tag_kconf_schema
	Configuration schema descriptor record. More...
Configuration data types
#define	KC_NONE   0
	Not a known type.
#define	KC_SPACE   1
	When used as kconf_schema type, defines the start of a configuration space.
#define	KC_ENDSPACE   2
	Ends a configuration space started with KC_SPACE.
#define	KC_INT32   3
	A 32 bit integer.
#define	KC_INT64   4
	A 64 bit integer.
#define	KC_STRING   5
	A unicode string.
#define	KC_BINARY   6
	An unparsed binary stream.
Defines
#define	KCONF_FLAG_ROOT   0x00000001
	This is the root configuration space.
#define	KCONF_FLAG_USER   0x00000002
	Indicates the configuration store which stores user-specific information.
#define	KCONF_FLAG_MACHINE   0x00000004
	Indicates the configuration store which stores machine-specific information.
#define	KCONF_FLAG_SCHEMA   0x00000008
	Indicates the configuration store which stores the schema.
#define	KCONF_FLAG_TRAILINGVALUE   0x00000020
	Indicates that the last component of the given configuration path is to be considered to be a configuration value.
#define	KCONF_FLAG_WRITEIFMOD   0x00000040
	Only write values back there is a change.
#define	KCONF_FLAG_IFMODCI   0x00000080
	Use case-insensitive comparison for KCONF_FLAG_WRITEIFMOD.
#define	KCONF_FLAG_NOPARSENAME   0x00000040
	Do not parse the configuration space name.
#define	KCONF_MAXCCH_NAME   256
	Maximum number of allowed characters (including terminating NULL) in a name.
#define	KCONF_MAXCB_NAME   (KCONF_MAXCCH_NAME * sizeof(wchar_t))
	Maximum number of allowed bytes (including terminating NULL) in a name.
#define	KCONF_MAX_DEPTH   16
	Maximum level of nesting for configuration spaces.
#define	KCONF_MAXCCH_PATH   (KCONF_MAXCCH_NAME * KCONF_MAX_DEPTH)
	Maximum number of allowed characters (including terminating NULL) in a configuration path.
#define	KCONF_MAXCB_PATH   (KCONF_MAXCCH_PATH * sizeof(wchar_t))
	Maximum number of allowed bytes (including terminating NULL) in a configuration path.
#define	KCONF_MAXCCH_STRING   KHM_MAXCCH_STRING
	Maximum number of allowed characters (including terminating NULL) in a string.
#define	KCONF_MAXCB_STRING   (KCONF_MAXCCH_STRING * sizeof(wchar_t))
	Maximum number of allowed bytes (including terminating NULL) in a string.
Typedefs
typedef tag_kconf_schema	kconf_schema
	Configuration schema descriptor record.
Functions
KHMEXP khm_int32 KHMAPI	khc_open_space (khm_handle parent, const wchar_t *cspace, khm_int32 flags, khm_handle *result)
	Open a configuration space.
KHMEXP khm_int32 KHMAPI	khc_shadow_space (khm_handle upper, khm_handle lower)
	Set the shadow space for a configuration handle.
KHMEXP khm_int32 KHMAPI	khc_close_space (khm_handle conf)
	Close a handle opened with khc_open_space().
KHMEXP khm_int32 KHMAPI	khc_read_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf, khm_size *bufsize)
	Read a string value from a configuration space.
KHMEXP khm_int32 KHMAPI	khc_read_multi_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf, khm_size *bufsize)
	Read a multi-string value from a configuration space.
KHMEXP khm_int32 KHMAPI	khc_read_int32 (khm_handle conf, const wchar_t *value_name, khm_int32 *buf)
	Read a 32 bit integer value from a configuration space.
KHMEXP khm_int32 KHMAPI	khc_read_int64 (khm_handle conf, const wchar_t *value_name, khm_int64 *buf)
	Read a 64 bit integer value from a configuration space.
KHMEXP khm_int32 KHMAPI	khc_read_binary (khm_handle conf, const wchar_t *value_name, void *buf, khm_size *bufsize)
	Read a binary value from a configuration space.
KHMEXP khm_int32 KHMAPI	khc_write_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf)
	Write a string value to a configuration space.
KHMEXP khm_int32 KHMAPI	khc_write_multi_string (khm_handle conf, const wchar_t *value_name, wchar_t *buf)
	Write a multi-string value to a configuration space.
KHMEXP khm_int32 KHMAPI	khc_write_int32 (khm_handle conf, const wchar_t *value_name, khm_int32 buf)
	Write a 32 bit integer value to a configuration space.
KHMEXP khm_int32 KHMAPI	khc_write_int64 (khm_handle conf, const wchar_t *value_name, khm_int64 buf)
	Write a 64 bit integer value to a configuration space.
KHMEXP khm_int32 KHMAPI	khc_write_binary (khm_handle conf, const wchar_t *value_name, void *buf, khm_size bufsize)
	Write a binary value to a configuration space.
KHMEXP khm_int32 KHMAPI	khc_get_type (khm_handle conf, const wchar_t *value_name)
	Get the type of a value in a configuration space.
KHMEXP khm_int32 KHMAPI	khc_value_exists (khm_handle conf, const wchar_t *value)
	Check which configuration stores contain a specific value.
KHMEXP khm_int32 KHMAPI	khc_remove_value (khm_handle conf, const wchar_t *value_name, khm_int32 flags)
	Remove a value from a configuration space.
KHMEXP khm_int32 KHMAPI	khc_get_config_space_name (khm_handle conf, wchar_t *buf, khm_size *bufsize)
	Get the name of a configuration space.
KHMEXP khm_int32 KHMAPI	khc_get_config_space_parent (khm_handle conf, khm_handle *parent)
	Get a handle to the parent space.
KHMEXP khm_int32 KHMAPI	khc_load_schema (khm_handle conf, const kconf_schema *schema)
	Load a configuration schema into the specified configuration space.
KHMEXP khm_int32 KHMAPI	khc_unload_schema (khm_handle conf, const kconf_schema *schema)
	Unload a schema from a configuration space.
KHMEXP khm_int32 KHMAPI	khc_enum_subspaces (khm_handle conf, khm_handle prev, khm_handle *next)
	Enumerate the subspaces of a configuration space.
KHMEXP khm_int32 KHMAPI	khc_remove_space (khm_handle conf)
	Remove a configuration space.

---

Define Documentation

#define KC_BINARY   6

An unparsed binary stream.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

Default values are not supported for binary streams. value is ignored.

#define KC_INT32   3

A 32 bit integer.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

value specifies a default value for this parameter in the lower 32 bits.

#define KC_INT64   4

A 64 bit integer.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

value specifies a default value for this parameter.

#define KC_SPACE   1

When used as kconf_schema type, defines the start of a configuration space.

There should be a subsequent KC_ENDSPACE record in the schema which defines the end of this configuration space.

name specifies the name of the configuration space. Optionally use description to provide a description.

#define KC_STRING   5

A unicode string.

Specifies a configuration parameter named name which is of this type. Use description to provide an optional description of the value.

value specifies a default value for this parameter which should be a pointer to a NULL terminated unicode string of no more than KCONF_MAXCCH_STRING characters.

#define KCONF_FLAG_IFMODCI   0x00000080

Use case-insensitive comparison for KCONF_FLAG_WRITEIFMOD.

When used in combination with KCONF_FLAG_WRITEIFMOD , the string comparison used when determining whether the string read from the configuration handle is the same as the string being written will be case insensitive. If this flag is not set, the comparison will be case sensitive.

#define KCONF_FLAG_NOPARSENAME   0x00000040

Do not parse the configuration space name.

If set, disables the parsing of the configuration space for subspaces. The space name is taken verbatim to be a configuration space name. This can be used when there can be forward slashes or backslahes in the name which are not escaped.

By default, the configuration space name,

    L"foo\\bar"

is taken to mean the configuration space bar which is a subspace of foo. If KCONF_FLAG_NOPARSENAME is set, then this is taken to mean configuration space foo\bar.

#define KCONF_FLAG_WRITEIFMOD   0x00000040

Only write values back there is a change.

Any write operations using the handle with check if the value being written is different from the value being read from the handle. It will only be written if the value is different.

Note:

Note that the value being read from a handle takes schema and shadowed configuration handles into consideration while the value being written is only written to the topmost layer of configuration that can be written to.

Note also that this flag does not affect binary values.

#define KCONF_MAXCCH_NAME   256

Maximum number of allowed characters (including terminating NULL) in a name.

Note:

This is a hard limit in Windows, since we are mapping configuration spaces to registry keys.

---

Typedef Documentation

typedef struct tag_kconf_schema kconf_schema

Configuration schema descriptor record.

The schema descriptor is a convenient way to provide a default set of configuration options for a part of an application. It describes the configuration spaces and the values and subspaces contained in each space.

See also:

kconf_load_schema()

---

Function Documentation

KHMEXP khm_int32 KHMAPI khc_enum_subspaces	(	khm_handle	conf,
		khm_handle	prev,
		khm_handle *	next
	)

Enumerate the subspaces of a configuration space.

Prepares a configuration space for enumeration and returns the child spaces in no particular order.

Parameters:

[in]	conf	The configuration space to enumerate child spaces
[in]	prev	The previous configuration space returned by khc_enum_subspaces() or NULL if this is the first call. If this is not NULL, then the handle passed in prev will be freed.
[out]	next	If prev was NULL, receives the first sub space found in conf. You must either call khc_enum_subspaces() again with the returned handle or call khc_close_space() to free the returned handle if no more subspaces are required. next can point to the same handle specified in prev.

Return values:

	KHM_ERROR_SUCCESS	The call succeeded. There is a valid handle to a configuration space in first_subspace.
	KHM_ERROR_INVALID_PARAM	Either conf or prev was not a valid configuration space handle or first_subspace is NULL. Note that prev can be NULL.
	KHM_ERROR_NOT_FOUND	There were no subspaces in the configuration space pointed to by conf.

Note:

The configuration spaces that are enumerated directly belong to the configuration space given by conf. This function does not enumerate subspaces of shadowed configuration spaces (see khc_shadow_space()). Even if conf was obtained on a restricted domain (i.e. you specified one or more configuration stores when you openend the handle and didn't include all the configuration stores. See khc_open_space()), the subspaces that are returned are the union of all configuration spaces in all the configuration stores. This is not a bug. This is a feature. In NetIDMgr, a configuartion space exists if some configuration store defines it (or it was created with a call to khc_open_space() even if no configuration store defines it yet). This is the tradeoff you make when using a layered configuration system.

However, the returned handle has the same domain restrictions as conf.

KHMEXP khm_int32 KHMAPI khc_get_config_space_name	(	khm_handle	conf,
		wchar_t *	buf,
		khm_size *	bufsize
	)

Get the name of a configuration space.

Parameters:

[in]	conf	Handle to a configuration space
[out]	buf	The buffer to receive the name. Set to NULL if only the size of the buffer is required.
[in,out]	bufsize	On entry, holds the size of the buffer pointed to by buf. On exit, holds the number of bytes copied into the buffer including the NULL terminator.

KHMEXP khm_int32 KHMAPI khc_get_config_space_parent	(	khm_handle	conf,
		khm_handle *	parent
	)

Get a handle to the parent space.

Parameters:

[in]	conf	Handle to a configuration space
[out]	parent	Handle to the parent configuration space if the call succeeds. Receives NULL otherwise. The returned handle must be closed using khc_close_space()

KHMEXP khm_int32 KHMAPI khc_get_type	(	khm_handle	conf,
		const wchar_t *	value_name
	)

Get the type of a value in a configuration space.

Returns:

The return value is the type of the specified value, or KC_NONE if the value does not exist.

KHMEXP khm_int32 KHMAPI khc_load_schema	(	khm_handle	conf,
		const kconf_schema *	schema
	)

Load a configuration schema into the specified configuration space.

Parameters:

[in]	conf	Handle to a configuration space or NULL to use the root configuration space.
[in]	schema	The schema to load. The schema is assumed to be well formed.

See also:

khc_unload_schema()

KHMEXP khm_int32 KHMAPI khc_open_space	(	khm_handle	parent,
		const wchar_t *	cspace,
		khm_int32	flags,
		khm_handle *	result
	)

Open a configuration space.

Opens the configuration space specified by cspace. By default, the opened space includes user,machine and schema configuration stores. However, you can specify a subset of these.

If the configuration space does not exist and the flags specify KHM_FLAG_CREATE, then the configuration space is created. The stores that are affected by the create operation depend on flags. If the flags only specifies KCONF_FLAG_MACHINE, then the configuration space is created in the machine store. If flags specifies any combination of stores including KCONF_FLAG_USER, then the configuration space is created in the user store. Note that KCONF_FLAG_SCHEMA is readonly.

Once opened, use khc_close_space() to close the configuration space.

Parameters:

[in]	parent	The parent configuration space. The path specified in cspace is relative to the parent. Set this to NULL to indicate the root configuration space.
[in]	cspace	The confiuration path. This can be up to KCONF_MAXCCH_PATH characters in length. Use either backslashes or forward slashes to specify hiearchy. Set this to NULL to reopen the parent configuration space.
[in]	flags	Flags. This can be a combination of KCONF_FLAG_* constants and KHM_FLAG_CREATE. If none of KCONF_FLAG_USER, KCONF_FLAG_MACHINE or KCONF_FLAG_SCHEMA is specified, then it defaults to all three.
[out]	result	Pointer to a handle which receives the handle to the opened configuration space if the call succeeds.

Note:

You can re-open a configuration space with different flags such as KCONF_FLAG_MACHINE by specifying NULL for cspace and settings flags to the required flags.

KHMEXP khm_int32 KHMAPI khc_read_binary	(	khm_handle	conf,
		const wchar_t *	value_name,
		void *	buf,
		khm_size *	bufsize
	)

Read a binary value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) does not support binary values.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:

[in]	buf	Buffer to copy the string to. Specify NULL to just retrieve the number of required bytes.
[in,out]	bufsize	On entry, specifies the number of bytes of space available at the location specified by buf. On exit specifies the number of bytes actually copied or the size of the required buffer if buf is NULL or insufficient.

Return values:

	KHM_ERROR_SUCCESS	Success. The data was copied to buf. The number of bytes copied is stored in bufsize
	KHM_ERROR_NOT_FOUND	The specified value was not found
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_int32	(	khm_handle	conf,
		const wchar_t *	value_name,
		khm_int32 *	buf
	)

Read a 32 bit integer value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

• Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:

[in]	conf	Handle to a configuration space
[in]	value	The value to query
[out]	buf	The buffer to receive the value

Return values:

	KHM_ERROR_NOT_READY	The configuration provider has not started.
	KHM_ERROR_SUCCESS	Success. The value that was read was placed in buf
	KHM_ERROR_NOT_FOUND	The specified value was not found
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid
	KHM_ERROR_TYPE_MISMATCH	The specified value was found but was not of the correct type.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_int64	(	khm_handle	conf,
		const wchar_t *	value_name,
		khm_int64 *	buf
	)

Read a 64 bit integer value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

• Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:

[in]	conf	Handle to a configuration space
[in]	value_name	The value to query
[out]	buf	The buffer to receive the value

Return values:

	KHM_ERROR_NOT_READY	The configuration provider has not started
	KHM_ERROR_SUCCESS	Success. The value that was read was placed in buf
	KHM_ERROR_NOT_FOUND	The specified value was not found
	KHM_ERROR_INVALID_PARAM	One or more parameters were invalid
	KHM_ERROR_TYPE_MISMATCH	The specified value was found but was not the correct data type.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_multi_string	(	khm_handle	conf,
		const wchar_t *	value_name,
		wchar_t *	buf,
		khm_size *	bufsize
	)

Read a multi-string value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

• Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

A multi-string is a pseudo data type. The value in the configuration store should contain a CSV string. Each comma separated value in the CSV string is considered to be a separate value. Empty values are not allowed. The buffer pointed to by buf will receive these values in the form of a series of NULL terminated strings terminated by an empty string (or equivalently, the last string will be terminated by a double NULL).

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:

[in]	buf	Buffer to copy the multi-string to. Specify NULL to just retrieve the number of required bytes.
[in,out]	bufsize	On entry, specifies the number of bytes of space available at the location specified by buf. On exit specifies the number of bytes actually copied or the size of the required buffer if buf is NULL or insufficient.

Return values:

	KHM_ERROR_NOT_READY	The configuration provider has not started
	KHM_ERROR_INVALID_PARAM	One or more of the supplied parameters are not valid
	KHM_ERROR_TYPE_MISMATCH	The specified value is not a string
	KHM_ERROR_TOO_LONG	buf was NULL or the size of the buffer was insufficient. The required size is in bufsize.
	KHM_ERROR_SUCCESS	Success. The number of bytes copied is in bufsize.
	KHM_ERROR_NOT_FOUND	The value was not found.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_read_string	(	khm_handle	conf,
		const wchar_t *	value_name,
		wchar_t *	buf,
		khm_size *	bufsize
	)

Read a string value from a configuration space.

The value_name parameter specifies the value to read from the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to access the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

• Otherwise, if KCONF_FLAG_SCHEMA was specified, the the schema store.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three.

If the value is not found in the configuration space and any shadowed configuration spaces, the function returns KHM_ERROR_NOT_FOUND. In this case, the buffer is left unmodified.

Parameters:

[in]	buf	Buffer to copy the string to. Specify NULL to just retrieve the number of required bytes.
[in,out]	bufsize	On entry, specifies the number of bytes of space available at the location specified by buf. On exit specifies the number of bytes actually copied or the size of the required buffer if buf is NULL or insufficient.

Return values:

	KHM_ERROR_NOT_READY	The configuration provider has not started
	KHM_ERROR_INVALID_PARAM	One or more of the supplied parameters are not valid
	KHM_ERROR_TYPE_MISMATCH	The specified value is not a string
	KHM_ERROR_TOO_LONG	buf was NULL or the size of the buffer was insufficient. The required size is in bufsize.
	KHM_ERROR_SUCCESS	Success. The number of bytes copied is in bufsize.
	KHM_ERROR_NOT_FOUND	The value was not found.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_remove_space

(

khm_handle

conf

)

Remove a configuration space.

The configuration space will be marked for removal. Once all the handles for the space have been released, it will be deleted. The configuration stores that will be affected are the write enabled configuration stores for the handle.

KHMEXP khm_int32 KHMAPI khc_remove_value	(	khm_handle	conf,
		const wchar_t *	value_name,
		khm_int32	flags
	)

Remove a value from a configuration space.

Removes a value from one or more configuration stores.

A value can exist in multiple configuration stores. Only the values that are stored in writable stores can be removed. When the function searches for values to remove, it will only look in configuration stores that are specified in the handle. In addition, the configuration stores affected can be further narrowed by specifying them in the flags parameter. If flags is zero, then all the stores visible to the handle are searched. If flags specifies KCONF_FLAG_USER or KCONF_FLAG_MACHINE or both, then only the specified stores are searched, provided that the stores are visible to the handle.

This function only operates on the topmost configuration space visible to the handle. If the configuration handle is shadowed, the shadowed configuration spaces are unaffected by the removal.

Parameters:

[in]	conf	Handle to configuration space to remove value from
[in]	value_name	Value to remove
[in]	flags	Specifies which configuration stores will be affected by the removal. See above.

Return values:

	KHM_ERROR_SUCCESS	The value was removed from all the specified configuration stores.
	KHM_ERROR_NOT_FOUND	The value was not found.
	KHM_ERROR_UNKNOWN	An unknown error occurred while trying to remove the value.
	KHM_ERROR_PARTIAL	The value was successfully removed from one or more stores, but the operation failed on one or more other stores.

KHMEXP khm_int32 KHMAPI khc_shadow_space	(	khm_handle	upper,
		khm_handle	lower
	)

Set the shadow space for a configuration handle.

The handle specified by lower becomes a shadow for the handle specified by upper. Any configuration value that is queried in upper that does not exist in upper will be queried in lower.

If upper already had a shadow handle, that handle will be replaced by lower. The handle lower still needs to be closed by a call to khc_close_space(). However, closing lower will not affect upper which will still treat the configuration space pointed to by lower to be it's shadow.

Shadows are specific to handles and not configuration spaces. Shadowing a configuration space using one handle does not affect any other handles which may be obtained for the same configuration space.

Specify NULL for lower to remove any prior shadow.

KHMEXP khm_int32 KHMAPI khc_value_exists	(	khm_handle	conf,
		const wchar_t *	value
	)

Check which configuration stores contain a specific value.

Each value in a configuration space can be contained in zero or more configuration stores. Use this function to determine which configuration stores contain the specific value.

The returned bitmask always indicates a subset of the configuration stores that were specified when opening the configuration space corresponding to conf.

If the specified handle is shadowed (see khc_shadow_space()) and the value is not found in any of the visible stores for the topmost handle, each of the shadowed handles will be tried in turn until the value is found. The return value will correspond to the handle where the value is first found.

Returns:

A combination of KCONF_FLAG_MACHINE, KCONF_FLAG_USER and KCONF_FLAG_SCHEMA indicating which stores contain the value.

KHMEXP khm_int32 KHMAPI khc_write_binary	(	khm_handle	conf,
		const wchar_t *	value_name,
		void *	buf,
		khm_size	bufsize
	)

Write a binary value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_int32	(	khm_handle	conf,
		const wchar_t *	value_name,
		khm_int32	buf
	)

Write a 32 bit integer value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_int64	(	khm_handle	conf,
		const wchar_t *	value_name,
		khm_int64	buf
	)

Write a 64 bit integer value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_multi_string	(	khm_handle	conf,
		const wchar_t *	value_name,
		wchar_t *	buf
	)

Write a multi-string value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

A multi-string is a pseudo data type. The buffer pointed to by buf should contain a sequence of NULL terminated strings terminated by an empty string (or equivalently, the last string should terminate with a double NULL). This will be stored in the value as a CSV string.

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

If the KCONF_FLAG_IFMODCI flag is specified along with the KCONF_FLAG_WRITEIFMOD flag, then the string comparison used will be case insensitive.

See also:

khc_open_space()

KHMEXP khm_int32 KHMAPI khc_write_string	(	khm_handle	conf,
		const wchar_t *	value_name,
		wchar_t *	buf
	)

Write a string value to a configuration space.

The value_name parameter specifies the value to write to the configuration space. This can be either a value name or a value path consisting of a series nested configuration space names followed by the value name all separated by backslashes or forward slashes.

For example: If conf is a handle to the configuration space 'A/B/C', then the value name 'D/E/v' refers to the value named 'v' in the configuration space 'A/B/C/D/E'.

The specific configuration store that is used to write the value depends on the flags that were specified in the call to khc_open_space(). The precedence of configuration stores are as follows:

• If KCONF_FLAG_USER was specified, then the user configuration space.

• Otherwise, if KCONF_FLAG_MACHINE was specified, then the machine configuration space.

Note that not specifying any of the configuration store specifiers in the call to khc_open_space() is equivalent to specifying all three. Also note that the schema store (KCONF_FLAG_SCHEMA) is readonly.

If the KCONF_FLAG_WRITEIFMOD flag is specified in the call to khc_open_space() for obtaining the configuration handle, the specified string will only be written if it is different from the value being read from the handle.

If the KCONF_FLAG_IFMODCI flag is specified along with the KCONF_FLAG_WRITEIFMOD flag, then the string comparison used will be case insensitive.

Parameters:

[in]	conf	Handle to a configuration space
[in]	value_name	Name of value to write
[in]	buf	A NULL terminated unicode string not exceeding KCONF_MAXCCH_STRING in characters including terminating NULL

See also:

khc_open_space()

---