Método IRegistryKey::SetValueKey (portcls.h)

Artigo
02/29/2024

O SetValueKey método substitui ou cria uma entrada de valor sob a chave aberta.

Sintaxe

NTSTATUS SetValueKey(
  [in, optional] PUNICODE_STRING ValueName,
  [in]           ULONG           Type,
  [in]           PVOID           Data,
  [in]           ULONG           DataSize
);

Parâmetros

[in, optional] ValueName

Ponteiro para uma cadeia de caracteres que contém o nome da entrada de valor a ser definida. A cadeia de caracteres de nome é especificada por uma estrutura do tipo UNICODE_STRING. Se a entrada de valor não tiver nome, defina esse parâmetro como NULL. Se o chamador especificar uma cadeia de caracteres de nome, mas o nome fornecido não for exclusivo em relação à chave que contém, o método substituirá os dados por uma entrada de valor existente.

[in] Type

Especifica o tipo dos dados a serem gravados para ValueName. Defina esse parâmetro como um dos seguintes tipos definidos pelo sistema:

REG_BINARY

REG_DWORD

REG_DWORD_LITTLE_ENDIAN

REG_DWORD_BIG_ENDIAN

REG_EXPAND_SZ

REG_LINK

REG_MULTI_SZ

REG_NONE

REG_SZ

REG_RESOURCE_LIST

REG_RESOURCE_REQUIREMENTS_LIST

REG_FULL_RESOURCE_DESCRIPTOR

Esses tipos de parâmetro são explicados em ZwSetValueKey.

[in] Data

Ponteiro para um buffer que contém os dados. Esse parâmetro aponta para uma estrutura ou valor fornecido pelo usuário apropriado para a função.

[in] DataSize

Especifica o tamanho em bytes de Dados. Esse parâmetro especifica quantos bytes de dados o método copiará do buffer para o qual os Dados apontam.

Retornar valor

SetValueKey retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida na definição da chave de valor especificada. Caso contrário, o método retorna um código de erro apropriado. A tabela a seguir mostra alguns dos possíveis códigos de retorno status.

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Indica que um dos parâmetros passados para o método não é válido.
STATUS_OBJECT_NAME_NOT_FOUND	Indica que o método não pôde localizar a chave de valor nomeada.

Comentários

Se a chave fornecida não tiver nenhuma entrada de valor existente com um nome que corresponda ao ValueName fornecido, SetValueKey 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, SetValueKey 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 que contém, muitas chaves diferentes no Registro podem ter entradas de valor com os mesmos nomes.