Função RegSetValueExA (winreg.h)

Artigo
11/20/2024

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 acesso KEY_SET_VALUE direito. Para obter mais informações, consulte de Direitos de Acesso e Segurança de Chave do Registro.

Esse identificador é retornado pelo RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExou função 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 deve 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 terminadanulo. Com o tipo de dados REG_MULTI_SZ, a cadeia de caracteres deve ser encerrada com dois caracteres de nulos .

Observação lpData indicando que um valor de 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 da terminação caracteres ou caracteres de nulos.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um 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.

Observações

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 do aplicativo, como ícones, bitmaps e arquivos executáveis, devem ser armazenados como arquivos e não 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 deverão 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 de Virtualização do Registro e dados de 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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

Consulte também

RegSetKeyValue

RegCreateKeyEx

RegFlushKey

RegOpenKeyEx

RegQueryValueEx

Funções do Registro

Visão geral do Registro

Compartilhar via