Função ZwSetValueKey (wdm.h)

Artigo
02/27/2024

A rotina ZwSetValueKey cria ou substitui a entrada de valor de uma chave do Registro.

Sintaxe

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

Parâmetros

[in] KeyHandle

Manipule para a chave do Registro para a qual gravar uma entrada de valor. Esse identificador é criado por uma chamada bem-sucedida para ZwCreateKey ou ZwOpenKey.

[in] ValueName

Ponteiro para o nome da entrada de valor para a qual os dados devem ser gravados. Esse parâmetro poderá ser um ponteiro NULL se a entrada de valor não tiver nenhum nome. Se uma cadeia de caracteres de nome for especificada e o nome fornecido não for exclusivo em relação à chave que o contém, os dados de uma entrada de valor existente serão substituídos.

[in, optional] TitleIndex

Esse parâmetro é reservado. Os drivers intermediários e de dispositivo devem definir esse parâmetro como zero.

[in] Type

Um dos seguintes tipos de dados definidos pelo sistema a serem gravados:

Valor do tipo	Significado
REG_BINARY	Dados binários em qualquer formulário.
REG_DWORD	Um valor numérico de 4 bytes.
REG_DWORD_LITTLE_ENDIAN	Um valor numérico de 4 bytes com o byte menos significativo no endereço mais baixo. Idêntico a REG_DWORD.
REG_DWORD_BIG_ENDIAN	Um valor numérico de 4 bytes com o byte menos significativo no endereço mais alto.
REG_EXPAND_SZ	Uma cadeia de caracteres Unicode terminada em nulo que contém referências não explicadas a variáveis de ambiente, como "%PATH%".
REG_LINK	Uma cadeia de caracteres Unicode que nomeia um link simbólico. Esse tipo é irrelevante para drivers intermediários e de dispositivo.
REG_MULTI_SZ	Uma matriz de cadeias de caracteres terminadas em nulo, terminada por outro zero.
REG_NONE	Dados sem tipo específico.
REG_SZ	Uma cadeia de caracteres Unicode terminada em nulo.
REG_RESOURCE_LIST	A lista de recursos de hardware de um driver de dispositivo, usada pelo driver ou um dos dispositivos físicos que ele controla, na árvore \ResourceMap
REG_RESOURCE_REQUIREMENTS_LIST	Uma lista de possíveis recursos de hardware de um driver de dispositivo que ele ou um dos dispositivos físicos que ele controla pode usar, do qual o sistema grava um subconjunto na árvore \ResourceMap
REG_FULL_RESOURCE_DESCRIPTOR	Uma lista de recursos de hardware que um dispositivo físico está usando, detectada e gravada na árvore \HardwareDescription pelo sistema

Os drivers de dispositivo não devem tentar chamar ZwSetValueKey para gravar explicitamente entradas de valor em uma subchave da chave \Registry...\ResourceMap . Somente o sistema pode gravar entradas de valor na árvore \Registry...\HardwareDescription .

[in, optional] Data

Ponteiro para um buffer alocado pelo chamador que contém os dados da entrada de valor.

[in] DataSize

Especifica o tamanho, em bytes, do buffer de dados . Se Type for REG_XXX_SZ, esse valor deverá incluir espaço para quaisquer zeros de terminação.

Retornar valor

ZwSetValueKeyretornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, essa rotina pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	O chamador não tem acesso apropriado ao valor do Registro.
STATUS_INVALID_HANDLE	O manipulador é inválido.

Comentários

O KeyHandle passado para ZwSetValueKey deve ter sido aberto com o sinalizador KEY_SET_VALUE DesiredAccess definido para que essa chamada seja bem-sucedida. Para obter uma descrição dos valores possíveis para DesiredAccess, consulte ZwCreateKey.

Se a chave fornecida não tiver nenhuma entrada de valor existente com um nome que corresponda ao ValueName fornecido, ZwSetValueKey criará uma nova entrada de valor com o nome fornecido. Se existir um nome de entrada de valor correspondente, essa rotina substituirá a entrada de valor original para o ValueName fornecido. Assim, ZwSetValueKey preserva um nome exclusivo para cada entrada de valor de qualquer chave específica. Embora cada nome de entrada de valor precise ser exclusivo para sua chave de contenção, muitas chaves diferentes no Registro podem ter entradas de valor com os mesmos nomes.

Para obter mais informações sobre como trabalhar com chaves do Registro, consulte Usando o Registro em um Driver.

Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtSetValueKey" em vez de "ZwSetValueKey".

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)