Função SHRegWriteUSValueA (shlwapi.h)
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_LINK (0x00000006)
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) |