Функция RtlQueryRegistryValues (wdm.h)

Подпрограмма RtlQueryRegistryValues позволяет вызывающей системе запрашивать несколько значений из поддерев реестра с одним вызовом.

Синтаксис

NTSYSAPI NTSTATUS RtlQueryRegistryValues(
  [in]           ULONG                     RelativeTo,
  [in]           PCWSTR                    Path,
  [in, out]      PRTL_QUERY_REGISTRY_TABLE QueryTable,
  [in, optional] PVOID                     Context,
  [in, optional] PVOID                     Environment
);

Параметры

[in] RelativeTo

Указывает, является ли пути абсолютным путем реестра или относительно предопределенного пути в качестве одного из следующих.

Значение RelativeTo можно изменить побитовой инструкцией-ORing с одним из следующих флагов.

[in] Path

Указатель на абсолютный путь реестра или путь относительно известного расположения, указанного параметром RelativeTo. Обратите внимание, что имена ключей в таком пути должны быть известны вызывающей, включая последний ключ в пути. Если указан флаг RTL_REGISTRY_HANDLE, этот параметр является дескриптором реестра для запроса непосредственно открытого ключа.

[in, out] QueryTable

Указатель на таблицу с одним или несколькими именами значений и именами вложенных ключей, в которых заинтересован вызывающий объект. Каждая запись таблицы содержит адрес указанной вызывающей функции QueryRoutine, которая будет вызываться для каждого имени значения, существующего в реестре. Таблица должна быть завершена с записью NULL таблицы, которая является записью таблицы с элементом NULLQueryRoutine и элементом NULLName. Структура записей таблицы запросов определяется следующим образом:

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;

Если вызывающий объект выделяет хранилище для таблицы запросов, на которую указывает параметр QueryTable, вызывающий объект отвечает за освобождение этого хранилища после возврата вызова RtlQueryRegistryValues.

QueryRoutine

Адрес функции QueryRoutine, которая вызывается с именем, типом, данными и длиной данных реестра. Если этот элемент и элемент Name являются null, он помечает конец таблицы.

Функция QueryRoutine объявлена следующим образом:

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

Дополнительные сведения см. в разделе QueryRoutine.

Флаги

Флаги для управления интерпретацией оставшихся элементов структуры RTL_QUERY_REGISTRY_TABLE. Для этого элемента определены следующие биты флагов.

Начиная с Windows 2000 поддержка папки "Входящие" предоставляется для всех битов флагов в предыдущей таблице, за исключением RTL_QUERY_REGISTRY_TYPECHECK. Поддержка папки "Входящие" для RTL_QUERY_REGISTRY_TYPECHECK доступна начиная с Windows 8. Для более ранних версий Windows поддержка RTL_QUERY_REGISTRY_TYPECHECK предоставляется через Центр обновления Windows. Дополнительные сведения см. в разделе "Примечания".

Имя

Это имя значения, запрашиваемого вызывающим элементом. Если имяNULL, функция QueryRoutine, указанная для этой записи таблицы, вызывается для всех значений, связанных с текущим разделом реестра. Если установлен флаг RTL_QUERY_REGISTRY_DIRECT, необходимо указать значение, отличное отNULL для Name.

EntryContext

Если установлен флаг RTL_QUERY_REGISTRY_DIRECT, это указатель на буфер для хранения результата операции запроса для этого ключа. В противном случае это значение передается в качестве параметра EntryContextQueryRoutine.

DefaultType

Наименьший байт этого элемента указывает тип возвращаемых данных REG_XXX, если не найден соответствующий ключ, а флаг RTL_QUERY_REGISTRY_REQUIRED не указан. Укажите REG_NONE для типа по умолчанию. Если установлен флаг RTL_QUERY_REGISTRY_TYPECHECK, самый значительный байт этого члена указывает тип REG_XXX хранящегося значения реестра, которое ожидает вызывающий элемент. Биты от 8 до 23 этого элемента зарезервированы и должны быть нулевыми.

DefaultData

Указатель на возвращаемое значение по умолчанию, если не найден соответствующий ключ, и флаг RTL_QUERY_REGISTRY_REQUIRED не указан. Этот элемент игнорируется, если DefaultType = REG_NONE. В противном случае тип данных, на которые указывает DefaultData, должен соответствовать типу значения реестра, указанному элементом DefaultType . Дополнительные сведения о типах значений реестра см. в определении параметра Type в KEY_VALUE_BASIC_INFORMATION.

DefaultLength

Указывает длину в байтах элемента DefaultData. Если DefaultType REG_SZ, REG_EXPAND_SZ или REG_MULTI_SZ вызывающие элементы могут указывать ноль, чтобы указать, RtlQueryRegistryValues должен вычислить длину на основе значения данных по умолчанию. Если DefaultType = REG_NONE, этот элемент игнорируется.

[in, optional] Context

Указывает значение, переданное в качестве параметра контекста контекста функции QueryRoutine при каждом вызове.

[in, optional] Environment

Указатель на среду, используемую при расширении значений переменных в значениях реестра REG_EXPAND_SZ или указатель NULL (необязательно).

Возвращаемое значение

RtlQueryRegistryValues возвращает код NTSTATUS. Возможные возвращаемые значения:

RtlQueryRegistryValues также завершает обработку таблицы, если функция QueryRoutine для записи таблицы возвращает код ошибки NTSTATUS и возвращает этот код ошибки в качестве результата. (За одним исключением: если QueryRoutine возвращает STATUS_BUFFER_TOO_SMALL, код ошибки игнорируется.)

Замечания

Вызывающий объект задает начальный путь ключа и таблицу. Таблица содержит одну или несколько записей, описывающих ключевые значения и имена подразделов, в которых заинтересован вызывающий объект. Таблица завершается записью с элементом NULLQueryRoutine и элементом NULLName. Таблица должна быть выделена из непагированного пула.

Драйверы режима ядра должны указывать флаг RTL_QUERY_REGISTRY_NOEXPAND, чтобы предотвратить вызов подпрограмм переменных среды. Эти подпрограммы небезопасны, поэтому драйверы в режиме ядра не должны использовать их.

Если флаг RTL_QUERY_REGISTRY_TYPECHECK задан в записи таблицы, вызывающий объект должен указать ожидаемый тип REG_XXX в 8 наиболее важных битах (MSBS) 32-разрядной DefaultType элемент записи таблицы. Как показано в следующем примере кода, константу RTL_QUERY_REGISTRY_TYPECHECK_SHIFT, определяемую как 24, можно использовать в качестве количества сдвигов, необходимых для размещения ожидаемого REG_XXX типа в 8 MSBS элемента DefaultType.

RTL_QUERY_REGISTRY_TABLE QueryRegTable[2];    
...
QueryRegTable[0].DefaultType = (REG_SZ << RTL_QUERY_REGISTRY_TYPECHECK_SHIFT) | REG_NONE;
...
QueryRegTable[1].DefaultType = (REG_DWORD << RTL_QUERY_REGISTRY_TYPECHECK_SHIFT) | REG_NONE;
...

Начиная с Windows 8, если RtlQueryRegistryValues обращается к ненадежному кусту, а вызывающий задает флаг RTL_QUERY_REGISTRY_DIRECT для этого вызова, вызывающий объект должен дополнительно задать флаг RTL_QUERY_REGISTRY_TYPECHECK. Нарушение этого правила вызовом из пользовательского режима вызывает исключение. Нарушение этого правила вызовом из режима ядра вызывает проверку ошибки 0x139 (KERNEL_SECURITY_CHECK_FAILURE).

Доверенными являются только системные hives. Вызов RtlQueryRegistryValues, который обращается к системным кустам, не вызывает исключение или ошибку, если установлен флаг RTL_QUERY_REGISTRY_DIRECT, и флаг RTL_QUERY_REGISTRY_TYPECHECK не задан. Однако, как рекомендуется, флаг RTL_QUERY_REGISTRY_TYPECHECK всегда следует задать, если установлен флаг RTL_QUERY_REGISTRY_DIRECT.

Аналогичным образом, в версиях Windows до Windows 8, как рекомендуется, вызов RtlQueryRegistryValues, который задает флаг RTL_QUERY_REGISTRY_DIRECT, должен дополнительно задать флаг RTL_QUERY_REGISTRY_TYPECHECK. Однако неисполнение этой рекомендации не приводит к исключению или проверке ошибок.

Ниже приведен список системных кустов:

• \REGISTRY\MACHINE\HARDWARE

• \REGISTRY\MACHINE\SOFTWARE

• \REGISTRY\MACHINE\SYSTEM

• \REGISTRY\MACHINE\SECURITY

• \REGISTRY\MACHINE\SAM

Поддержка флага RTL_QUERY_REGISTRY_TYPECHECK доступна через Центр обновления Windows для Windows 7, Windows Vista, Windows Server 2003 и Windows XP. Дополнительные сведения об этом обновлении см. в уязвимостях в ядре Windows, которые могут разрешить повышение привилегий (2393802). В версиях этих операционных систем, которые не имеют этого обновления, вызывающий объект может использовать флаг RTL_QUERY_REGISTRY_TYPECHECK. Однако этот флаг игнорируется подпрограммой RtlQueryRegistryValues.

Начиная с пакета драйверов Windows (WDK) 8, флаг RTL_QUERY_REGISTRY_TYPECHECK определен в файле заголовка Wdm.h следующим образом:

#define RTL_QUERY_REGISTRY_TYPECHECK 0x00000100

Если запись не указывает флаг RTL_QUERY_REGISTRY_DIRECT, RtlQueryRegistryValues использует указанную функцию QueryRoutine, чтобы сообщить имя значения, тип, данные и длину данных в байтах вызывающей функции. Если элемент имени записи NULL, RtlQueryRegistryValues сообщает каждый прямой подраздел ключа. Если тип ключа REG_MULTI_SZ и флаг RTL_QUERY_REGISTRY_NOEXPAND не указан, подпрограмма вызывает QueryRoutine отдельно для каждой отдельной строки; в противном случае подпрограмма сообщает об этом как одно значение. Если запись указывает флаг RTL_QUERY_REGISTRY_DIRECT, RtlQueryRegistryValues сохраняет значение ключа в буфере, на который указывает элемент entryContext. Формат возвращаемых данных выглядит следующим образом.

Если ошибка возникает на любом этапе обработки таблицы запросов, RtlQueryRegistryValues перестает обрабатывать таблицу и возвращает состояние ошибки.

Описание возможных значений REG_XXX см. в ZwSetValueKey.

Требования

См. также

QueryRoutine

RtlZeroMemory

UNICODE_STRING

ZwEnumerateKey

ZwEnumerateValueKey

ZwSetValueKey