The RtlQueryRegistryValues routine allows the caller to query several values from the registry subtree with a single call.

NTSTATUS 
  RtlQueryRegistryValues(
    IN ULONG  RelativeTo,
    IN PCWSTR  Path,
    IN PRTL_QUERY_REGISTRY_TABLE  QueryTable,
    IN PVOID  Context,
    IN PVOID  Environment  OPTIONAL
    );

Parameters

RelativeTo

Specifies whether Path is an absolute registry path or is relative to a predefined path as one of the following.

Value	Meaning
RTL_REGISTRY_ABSOLUTE	Path is an absolute registry path.
RTL_REGISTRY_CONTROL	Path is relative to \Registry\Machine\System\CurrentControlSet\Control.
RTL_REGISTRY_DEVICEMAP	Path is relative to \Registry\Machine\Hardware\DeviceMap.
RTL_REGISTRY_SERVICES	Path is relative to \Registry\Machine\System\CurrentControlSet\Services.
RTL_REGISTRY_USER	Path is relative to \Registry\User\CurrentUser. (For a system process, this is \Users\.Default.)
RTL_REGISTRY_WINDOWS_NT	Path is relative to \Registry\Machine\Software\Microsoft\ Windows NT\CurrentVersion.

The RelativeTo value can be modified by ORing it with one of the following flags.

RTL_REGISTRY_OPTIONAL	Specifies that the key referenced by this parameter and the Path parameter are optional.
RTL_REGISTRY_HANDLE	Specifies that the Path parameter is actually a registry handle to use.

Path

Pointer to either an absolute registry path or a path relative to the known location specified by the RelativeTo parameter. Note that the names of keys in such a path must be known to the caller, including the last key in the path. If the RTL_REGISTRY_HANDLE flag is specified, this parameter is a registry handle for an already opened key to be queried directly.

QueryTable

Pointer to a table of one or more value names and subkey names in which the caller is interested. Each table entry contains the address of a caller-supplied QueryRoutine function that will be called for each value name that exists in the registry. The table must be terminated with a NULL table entry, which is a table entry with a NULL QueryRoutine member and a NULL Name member. The structure for query table entries is defined as follows:

typedef struct _RTL_QUERY_REGISTRY_TABLE {
    PRTL_QUERY_REGISTRY_ROUTINE QueryRoutine;
    ULONG Flags;
    PWSTR Name;
    PVOID EntryContext;
    ULONG DefaultType;
    PVOID DefaultData;
    ULONG DefaultLength;
} RTL_QUERY_REGISTRY_TABLE, *PRTL_QUERY_REGISTRY_TABLE;

QueryRoutine

The address of a QueryRoutine function that is called with the name, type, data, and data length of a registry value. If this member is NULL, it marks the end of the table.

A QueryRoutine function is declared as follows:

NTSTATUS
QueryRoutine (
    IN PWSTR ValueName,
    IN ULONG ValueType,
    IN PVOID ValueData,
    IN ULONG ValueLength,
    IN PVOID Context,
    IN PVOID EntryContext
    );

Flags

Control how the remaining members are to be interpreted, as follows.

Value	Meaning
RTL_QUERY_REGISTRY_SUBKEY	The Name of this table entry is another path to a registry key, and all following table entries are for that key rather than the key specified by the Path parameter. This change in focus lasts until the end of the table or until another RTL_REGISTRY_SUBKEY or RTL_QUERY_REGISTRY_TOPKEY entry is seen. Each such entry must specify a path that is relative to the Path specified in the call to RtlQueryRegistryValues.
RTL_QUERY_REGISTRY_TOPKEY	Resets the current registry key handle to the original one specified by the RelativeTo and Path parameters. This is useful for getting back to the original node after descending into subkeys with the RTL_QUERY_REGISTRY SUBKEY flag.
RTL_QUERY_REGISTRY_REQUIRED	Specifies that this value is required and, if it is not found, RtlQueryRegistryValues immediately exits with a status code of STATUS_OBJECT_NAME_NOT_FOUND. This occurs if the Name member is NULL and the current key has no subkeys, or if Name specifies a nonexistent subkey. (If this flag is not specified, then when no match is found for a non-NULL Name, the routine uses the DefaultValue member as the value. When Name is NULL and the current key has no subkeys, the routine simply skips that table entry.)
RTL_QUERY_REGISTRY_NOVALUE	Specifies that even though there is no Name for this table entry, all the caller wants is a callback: that is, the caller does not want to enumerate all the values under the current key. QueryRoutine is called with NULL for ValueData, REG_NONE for ValueType, and zero for ValueLength.
RTL_QUERY_REGISTRY_NOEXPAND	Specifies that, if the type of this registry value is REG_EXPAND_SZ or REG_MULTI_SZ, RtlQueryRegistryValues is not to do any preprocessing of these registry values before calling QueryRoutine. By default, RtlQueryRegistryValues expands environment variable references into REG_EXPAND_SZ values, enumerates each null-terminated string in a REG_MULTI_SZ value, and calls QueryRoutine once with each, making it look like there is more than one REG_SZ value with the same ValueName. If the storage has been allocated, the caller must release the storage at an appropriate point because the system does not release the storage automatically. Note that REG_MULTI_SIZE is a null- terminated UNICODE string.
RTL_QUERY_REGISTRY_DIRECT	The QueryRoutine member is ignored, and the EntryContext points to the buffer to store the value.
RTL_QUERY_REGISTRY_DELETE	This is used to delete value keys after they have been queried.

Name

This is the name of a Value that the caller queried. If Name is NULL, the QueryRoutine function specified for this table entry is called for all values associated with the current registry key. If the RTL_QUERY_REGISTRY_DIRECT flag is set, a non-NULL value for Name must be provided.

EntryContext

If the RTL_QUERY_REGISTRY_DIRECT flag is set, this is a pointer to the buffer to store the result of the query operation for this key. Otherwise, this value is passed as the EntryContext parameter of QueryRoutine.

DefaultType

Specifies the REG_XXX type of the data to be returned if no matching key is found and the RTL_QUERY_REGISTRY_REQUIRED flag is not specified. Specify REG_NONE for no default type.

DefaultData

Specifies the default value to be returned if no matching key is found and the RTL_QUERY_REGISTRY_REQUIRED flag is not specified. This member is ignored if DefaultType = REG_NONE.

DefaultLength

Specifies the length, in bytes, of the DefaultData member. If DefaultType is REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, callers can optionally specify zero to indicate RtlQueryRegistryValues should compute the length based on the default data value. If DefaultType = REG_NONE, this member is ignored.

Context

Specifies the value passed as the Context parameter of a QueryRoutine function each time it is called.

Environment

Pointer to the environment used when expanding variable values in REG_EXPAND_SZ registry values, or a NULL pointer (optional).

Return Value

RtlQueryRegistryValues returns an NTSTATUS code. The possible return values include:

STATUS_SUCCESS

The entire query table was processed successfully.

STATUS_INVALID_PARAMETER

Processing of the query table terminated with an invalid table entry. A table entry can be invalid if the specified flags require the QueryRoutine or Name members to be non-NULL, but a NULL value was provided.

STATUS_OBJECT_NAME_NOT_FOUND

The Path parameter does not match a valid key, or processing of the query table terminated with an entry with the RTL_QUERY_REGISTRY_REQUIRED flag set and no matching key is found. This occurs if the Name member is NULL and the current key has no subkeys, or if Name specifies a nonexistent subkey.

STATUS_BUFFER_TOO_SMALL

The RTL_QUERY_REGISTRY_DIRECT flag is set, and the buffer specified by EntryContext is too small to hold the key value data.

RtlQueryRegistryValues also terminates processing of the table if the QueryRoutine function for a table entry returns an NTSTATUS error code, and returns that error code as its result. (With one exception: If QueryRoutine returns STATUS_BUFFER_TOO_SMALL, the error code is ignored.)

Comments

The caller specifies an initial key path and a table. The table contains one or more entries that describe the key values and subkey names in which the caller is interested. The table is terminated by an entry with a NULL QueryRoutine member and a NULL Name member. The table must be allocated from nonpaged pool.

Warning  Kernel-mode drivers must specify the RTL_QUERY_REGISTRY_NOEXPAND flag to prevent calling environment variable routines. These routines are unsafe, so kernel-mode drivers should not use them.

If an entry does not specify the RTL_QUERY_REGISTRY_DIRECT flag, RtlQueryRegistryValues uses the specified QueryRoutine function to report the value name, type, data, and data length, in bytes, to the caller. If the Name member of the entry is NULL, RtlQueryRegistryValues reports every direct subkey of the key. If the key type is REG_MULTI_SZ and the RTL_QUERY_REGISTRY_NOEXPAND flag not is specified, the routine calls QueryRoutine separately for each individual string; otherwise the routine reports it as a single value. If an entry specifies the RTL_QUERY_REGISTRY_DIRECT flag, RtlQueryRegistryValues stores the value of the key in the buffer pointed to by the entry's EntryContext member. The format of the returned data is as follows.

Key data type	How data is returned
A null-terminated Unicode string (such as REG_SZ, REG_EXPAND_SZ).	EntryContext must point to an initialized UNICODE_STRING structure. If the Buffer member of UNICODE_STRING is NULL, the routine allocates storage for the string data. Otherwise, it stores the string data in the buffer that Buffer points to.
REG_MULTI_SZ	You must specify the RTL_QUERY_REGISTRY_NOEXPAND flag for this key data type. EntryContext points to an initialized UNICODE_STRING structure. The routine stores the key value as a single string value. Each individual component within the string is terminated by a zero. If the Buffer member of UNICODE_STRING is NULL, the routine allocates storage for the string data. Otherwise, it stores the string data in the buffer that Buffer points to.
Nonstring data with size, in bytes, <= sizeof(ULONG)	The value is stored in the memory location specified by EntryContext.
Nonstring data with size, in bytes, > sizeof(ULONG)	The buffer pointed to by EntryContext must begin with a signed LONG value. The magnitude of the value must specify the size, in bytes, of the buffer. If the sign of the value is negative, RtlQueryRegistryValues will only store the data of the key value. Otherwise, it will use the first ULONG in the buffer to record the value length, in bytes, the second ULONG to record the value type, and the rest of the buffer to store the value data.

If an error occurs at any stage of processing of the query table RtlQueryRegistryValues stops processing the table and returns the error status.

See ZwSetValueKey for a description of the possible REG_XXX values.

Requirements

IRQL: PASSIVE_LEVEL

Headers: Declared in wdm.h. Include wdm.h, ntddk.h, or ntifs.h.

See Also

RtlZeroMemory, ZwEnumerateKey, ZwEnumerateValueKey, ZwSetValueKey

APIScan Requirements

Header: Wdm.h, Ntddk.h, Ntifs.h
Function: RtlQueryRegistryValues