Função SHRegWriteUSValueA (shlwapi.h)

  • Artigo

Grava um valor em uma subchave do Registro em uma subárvore específica do usuário (HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE).

Sintaxe

LSTATUS SHRegWriteUSValueA(
  [in] HUSKEY     hUSKey,
  [in] LPCSTR     pszValue,
  [in] DWORD      dwType,
  [in] const void *pvData,
  [in] DWORD      cbData,
  [in] DWORD      dwFlags
);

Parâmetros

[in] hUSKey

Tipo: HUSKEY

Um identificador para uma subchave do Registro aberta no momento. A subchave 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 pode ser obtido por meio da função SHRegOpenUSKey .

[in] pszValue

Tipo: LPCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do valor. Esse valor é uma entrada na subchave especificada por hUSKey. Se um valor com esse nome ainda não estiver presente na subchave, ele será adicionado.

Se esse parâmetro for NULL ou uma cadeia de caracteres vazia, a função definirá o tipo e os dados para o valor Padrão da subchave.

[in] dwType

Tipo: DWORD

O tipo dos dados a serem armazenados no valor especificado por pszValue. Um dos seguintes tipos de valor do Registro definidos em Winnt.h e Wdm.h.

REG_NONE (0x00000000)

REG_SZ (0x00000001)

REG_EXPAND_SZ (0x00000002)

REG_BINARY (0x00000003)

REG_DWORD (0x00000004)

REG_DWORD_LITTLE_ENDIAN (0x00000004)

REG_DWORD_BIG_ENDIAN (0x00000005)

REG_MULTI_SZ (0x00000007)

REG_RESOURCE_LIST (0x00000008)

REG_FULL_RESOURCE_DESCRIPTOR (0x00000009)

REG_RESOURCE_REQUIREMENTS_LIST (0x0000000A)

REG_QWORD (0x0000000B)

REG_QWORD_LITTLE_ENDIAN (0x0000000B)

[in] pvData

Tipo: const void*

Um ponteiro para os dados a serem definidos para o valor especificado por pszValue. 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. Uma barra invertida em um caminho deve ser precedida por outra barra invertida como um caractere de escape. Por exemplo, especifique "C:\mydir\myfile" para armazenar a cadeia de caracteres "C:\mydir\myfile".

[in] cbData

Tipo: DWORD

O tamanho, em bytes, dos dados apontados pelo parâmetro pvData . 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.

[in] dwFlags

Tipo: DWORD

Sinalizadores que indicam a subárvore na qual os dados devem ser gravados. Um ou mais dos seguintes valores:

SHREGSET_HKCU (0x00000001)

Gravar em HKEY_CURRENT_USER somente se um valor do nome especificado em pszValue não existir atualmente na subchave especificada.

SHREGSET_FORCE_HKCU (0x00000002)

Gravar em HKEY_CURRENT_USER. Se um valor do nome especificado em pszValue já existir, ele será substituído.

SHREGSET_HKLM (0x00000004)

Gravar em HKEY_LOCAL_MACHINE somente se um valor do nome especificado em pszValue não existir atualmente na subchave especificada..

SHREGSET_FORCE_HKLM (0x00000008)

Gravar em HKEY_LOCAL_MACHINE. Se um valor do nome especificado em pszValue já existir, ele será substituído.

SHREGSET_DEFAULT (0x00000006)

Equivalente a (SHREGSET_FORCE_HKCU | SHREGSET_HKLM).

Retornar valor

Tipo: LSTATUS

Retorna ERROR_SUCCESS se tiver êxito; caso contrário, 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 recuperar uma descrição genérica do erro.

Comentários

Para usar SHRegWriteUSValue, primeiro você deve abrir a chave com SHRegOpenUSKey. Depois que a chave for aberta, você poderá usar SHRegWriteUSValue quantas vezes forem necessárias.

Se você precisar gravar apenas um único valor, deverá usar SHRegSetUSValue, que abre a chave e grava o valor.

Se você precisar escrever mais de um valor na mesma chave, várias chamadas para SHRegWriteUSValue geralmente são mais eficientes do que SHRegSetUSValue, pois a chave só é aberta uma vez.

Observação

O cabeçalho shlwapi.h define SHRegWriteUSValue 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, Windows XP [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 shlwapi.h
Biblioteca Shlwapi.lib
DLL Shlwapi.dll (versão 4.71 ou posterior)

Confira também

Tipos de valor do Registro