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

Статья
03/08/2023

Подпрограмма ZwSetValueKey создает или заменяет запись значения раздела реестра.

Синтаксис

NTSYSAPI NTSTATUS ZwSetValueKey(
  [in]           HANDLE          KeyHandle,
  [in]           PUNICODE_STRING ValueName,
  [in, optional] ULONG           TitleIndex,
  [in]           ULONG           Type,
  [in, optional] PVOID           Data,
  [in]           ULONG           DataSize
);

Параметры

[in] KeyHandle

Дескриптор раздела реестра для записи записи значения. Этот дескриптор создается путем успешного вызова ZwCreateKey или ZwOpenKey.

[in] ValueName

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

[in, optional] TitleIndex

Этот параметр зарезервирован. Драйверы устройств и промежуточных параметров должны иметь нулевое значение.

[in] Type

Один из следующих системных типов данных для записи:

Значение типа	Значение
REG_BINARY	Двоичные данные в любой форме.
REG_DWORD	4-байтовое числовое значение.
REG_DWORD_LITTLE_ENDIAN	4-байтовое числовое значение с наименьшим значимым байтом по нижнему адресу. Идентично REG_DWORD.
REG_DWORD_BIG_ENDIAN	4-байтовое числовое значение с наименьшим значимым байтом на самом высоком адресе.
REG_EXPAND_SZ	Строка Юникода, завершающаяся null, которая содержит нерасширенные ссылки на переменные среды, такие как "%PATH%".
REG_LINK	Строка Юникода, именующая символьную ссылку. Этот тип не имеет отношения к драйверам устройства и промежуточным драйверам.
REG_MULTI_SZ	Массив строк, завершаемых нулевым значением.
REG_NONE	Данные без определенного типа.
REG_SZ	Строка Юникода, заканчивающаяся нулевым значением.
REG_RESOURCE_LIST	Список аппаратных ресурсов драйвера устройства, используемых драйвером или одним из физических устройств, которыми он управляет, в дереве \ResourceMap
REG_RESOURCE_REQUIREMENTS_LIST	Список возможных аппаратных ресурсов драйвера устройства или одно из физических устройств, которые он может использовать, из которого система записывает подмножество в дерево \ResourceMap .
REG_FULL_RESOURCE_DESCRIPTOR	Список аппаратных ресурсов, которые использует физическое устройство, обнаруженные и записанные системой в дерево \HardwareDescription

Драйверы устройств не должны пытаться вызвать ZwSetValueKey для явной записи записей значений в подразделе раздела \Registry...\ResourceMap . Только система может записывать записи значений в дерево \Registry...\HardwareDescription .

[in, optional] Data

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

[in] DataSize

Указывает размер буфера данных в байтах. Если type имеет значение REG_XXXX_SZ, это значение должно содержать пробел для всех завершающих нулей.

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

ZwSetValueKey возвращает STATUS_SUCCESS , если операция выполнена успешно. В противном случае эта подпрограмма может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_ACCESS_DENIED	Вызывающий объект не имеет соответствующего доступа к значению реестра.
STATUS_INVALID_HANDLE	Дескриптор недействителен.

Объект KeyHandle , переданный в ZwSetValueKey , должен быть открыт с флагом DesiredAccess KEY_SET_VALUE для успешного выполнения этого вызова. Описание возможных значений desiredAccess см. в разделе ZwCreateKey.

Если указанный ключ не имеет существующей записи значения с именем, соответствующим заданному значению ValueName, ZwSetValueKey создает новую запись значения с заданным именем. Если имя совпадающего значения существует, эта подпрограмма перезаписывает исходную запись значения для заданного значения ValueName. Таким образом, ZwSetValueKey сохраняет уникальное имя для каждой записи значения любого конкретного ключа. Хотя имя каждой записи значения должно быть уникальным для содержащего его ключа, многие разные разделы в реестре могут содержать записи значений с одинаковыми именами.

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

Если вызов этой функции происходит в пользовательском режиме, следует использовать имя NtSetValueKey вместо ZwSetValueKey.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx и ZwXxx см. в разделе Использование версий Nt и Zw для процедур собственных системных служб.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)