This topic has not yet been rated - Rate this topic

RtlQueryRegistryValues routine

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

Syntax

Copy

NTSTATUS RtlQueryRegistryValues(
  __in      ULONG RelativeTo,
  __in      PCWSTR Path,
  __inout   PRTL_QUERY_REGISTRY_TABLE QueryTable,
  __in_opt  PVOID Context,
  __in_opt  PVOID Environment
);

Parameters

RelativeTo [in]

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 [in]

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 [in, out]

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:

Copy


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:

Copy


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

For more information, see QueryRoutine.

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. If the caller sets this flag, the caller should additionally set the RTL_QUERY_REGISTRY_TYPECHECK flag to guard against buffer overflow. For more information, see the Remarks section.
RTL_QUERY_REGISTRY_TYPECHECK	Use this flag with the RTL_QUERY_REGISTRY_DIRECT flag to verify that the REG_XXX type of the stored registry value matches the type expected by the caller. If the types do not match, the call fails. For more information, see the Remarks section.
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

The least-significant byte of this member 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. If the RTL_QUERY_REGISTRY_TYPECHECK flag is set, the most-significant byte of this member specifies the REG_XXX type of the stored registry value that the caller expects. Bits 8 to 23 of this member are reserved and should be zero.

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 [in, optional]

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

Environment [in, optional]

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:

Return code	Description
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 member 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.
STATUS_OBJECT_TYPE_MISMATCH	The RTL_QUERY_REGISTRY_TYPECHECK flag is set and the type of the stored registry value does not match the type expected by the caller.

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.)

Remarks

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.

Note 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.

Caution If you use the RTL_QUERY_REGISTRY_DIRECT flag, a non-trusted user-mode application may be able to cause a buffer overflow. A buffer overflow can occur if a driver uses this flag to read a registry value to which the wrong type is assigned. In all cases, a driver that uses the RTL_QUERY_REGISTRY_DIRECT flag should additionally use the RTL_QUERY_REGISTRY_TYPECHECK flag to prevent such overflows.

If the RTL_QUERY_REGISTRY_TYPECHECK flag is set in a table entry, the caller must specify the expected REG_XXX type in the most-significant byte of the DefaultType member of the table entry. Support for the RTL_QUERY_REGISTRY_TYPECHECK flag is available through Windows Update for Windows 7, Windows Vista, Windows Server 2003, and Windows XP. For more information about this update, see Vulnerabilities in Windows Kernel Could Allow Elevation of Privilege (2393802). In versions of these operating systems that do not have this update, the caller can use the RTL_QUERY_REGISTRY_TYPECHECK flag. However, this flag is ignored by the RtlQueryRegistryValues routine.

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

Version	Available in Windows 2000 and later versions of Windows.
Header	Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
Library	Contained in Ntoskrnl.lib.
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL

RtlQueryRegistryValues routine

Syntax

Parameters

Return value

Remarks

Requirements

See also