Função RegSetValueExA (winreg.h)

Artigo
08/27/2023

Define os dados e o tipo de um valor especificado em uma chave do Registro.

Sintaxe

LSTATUS RegSetValueExA(
  [in]           HKEY       hKey,
  [in, optional] LPCSTR     lpValueName,
                 DWORD      Reserved,
  [in]           DWORD      dwType,
  [in]           const BYTE *lpData,
  [in]           DWORD      cbData
);

Parâmetros

[in] hKey

Um identificador para uma chave aberta do Registro. A chave deve ter sido aberta com o direito de acesso KEY_SET_VALUE. Para obter mais informações, consulte Segurança de Chave do Registro e Direitos de Acesso.

Esse identificador é retornado pela função RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx ou RegOpenKeyTransacted . Também pode ser uma das seguintes chaves predefinidas:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

A versão Unicode dessa função dá suporte às seguintes chaves predefinidas adicionais:

HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT

[in, optional] lpValueName

O nome do valor a ser definido. Se um valor com esse nome ainda não estiver presente na chave, a função o adicionará à chave.

Se lpValueName for NULL ou uma cadeia de caracteres vazia, "", a função definirá o tipo e os dados para o valor não nomeado ou padrão da chave.

Para obter mais informações, consulte Limites de tamanho do elemento do Registro.

As chaves do Registro não têm valores padrão, mas podem ter um valor sem nome, que pode ser de qualquer tipo.

Reserved

Esse parâmetro é reservado e precisa ser zero.

[in] dwType

O tipo de dados apontado pelo parâmetro lpData . Para obter uma lista dos tipos possíveis, consulte Tipos de valor do Registro.

[in] lpData

Os dados a serem armazenados.

Para tipos baseados em cadeia de caracteres, como REG_SZ, a cadeia de caracteres deve ser terminada em nulo. Com o tipo de dados REG_MULTI_SZ, a cadeia de caracteres deve ser encerrada com dois caracteres nulos .

Observe lpData indicando que um valor nulo é válido, no entanto, se esse for o caso, cbData deverá ser definido como '0'.

[in] cbData

O tamanho das informações apontadas pelo parâmetro lpData , em bytes. Se os dados forem do tipo REG_SZ, REG_EXPAND_SZ ou REG_MULTI_SZ, cbData deverá incluir o tamanho do caractere nulo de terminação ou caracteres.

Retornar valor

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor de retorno será o código de erro diferente de zero definido em Winerror.h. Você pode usar a função FormatMessage com o sinalizador FORMAT_MESSAGE_FROM_SYSTEM para obter uma descrição genérica do erro.

Comentários

Os tamanhos de valor são limitados pela memória disponível. No entanto, armazenar valores grandes no registro pode afetar seu desempenho. Valores longos (mais de 2.048 bytes) devem ser armazenados como arquivos, com os locais dos arquivos armazenados no registro.

Elementos de aplicativo, como ícones, bitmaps e arquivos executáveis, devem ser armazenados como arquivos e não devem ser colocados no Registro.

Se dwType for o tipo REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ e a versão ANSI dessa função for usada (chamando explicitamente RegSetValueExA ou não definindo UNICODE antes de incluir o arquivo Windows.h), os dados apontados pelo parâmetro lpData devem ser uma cadeia de caracteres ANSI. A cadeia de caracteres é convertida em Unicode antes de ser armazenada no registro.

Observe que as operações que acessam determinadas chaves do Registro são redirecionadas. Para obter mais informações, consulte Virtualização do Registro e Dados do Aplicativo de 32 bits e 64 bits no Registro.

Considere usar a função RegSetKeyValue , que fornece uma maneira mais conveniente de definir o valor de uma chave do Registro.

Observação

O cabeçalho winreg.h define RegSetValueEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winreg.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll