Função RegCreateKeyA (winreg.h)

Cria a chave do Registro especificada. Se a chave já existir no registro, a função a abrirá.

Observação Essa função é fornecida apenas para compatibilidade com versões de 16 bits do Windows. Os aplicativos devem usar a função RegCreateKeyEx. No entanto, os aplicativos que backupm ou restauram o estado do sistema, incluindo arquivos do sistema e hives de registro, devem usar o serviço de cópia de sombra de volume em vez das funções do Registro.

 

Sintaxe

LSTATUS RegCreateKeyA(
  [in]           HKEY   hKey,
  [in, optional] LPCSTR lpSubKey,
  [out]          PHKEY  phkResult
);

Parâmetros

[in] hKey

Um identificador para uma chave aberta do Registro. O processo de chamada deve ter acesso KEY_CREATE_SUB_KEY à chave. Para obter mais informações, consulte de Direitos de Acesso e Segurança de Chave do Registro.

O acesso à criação de chaves é verificado no descritor de segurança da chave do Registro, não na máscara de acesso especificada quando o identificador foi obtido. Portanto, mesmo que hKey tenha sido aberto com um samDesired de KEY_READ, ele poderá ser usado em operações que criam chaves, se permitido por seu descritor de segurança.

Esse identificador é retornado pela função RegCreateKeyEx ou RegOpenKeyEx ou pode ser uma das seguintes chaves predefinidas :

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in, optional] lpSubKey

O nome de uma chave que essa função abre ou cria. Essa chave deve ser uma subchave da chave identificada pelo parâmetro hKey .

Para obter mais informações sobre nomes de chave, consulte Estrutura do Registro.

Se hKey for uma das chaves predefinidas, lpSubKey poderá ser NULL. Nesse caso, phkResult recebe o mesmo identificador de hKey passado para a função.

[out] phkResult

Um ponteiro para uma variável que recebe um identificador para a chave aberta ou criada. Se a chave não for uma das chaves predefinidas do Registro, chame a função RegCloseKey depois de terminar de usar o identificador.

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

Um aplicativo não pode criar uma chave que seja um filho direto de HKEY_USERS ou HKEY_LOCAL_MACHINE. Um aplicativo pode criar subchaves em níveis inferiores das árvores HKEY_USERS ou HKEY_LOCAL_MACHINE.

Se seu serviço ou aplicativo representar usuários diferentes, não use essa função com HKEY_CURRENT_USER. Em vez disso, chame a função RegOpenCurrentUser.

A função RegCreateKey cria todas as chaves ausentes no caminho especificado. Um aplicativo pode aproveitar esse comportamento para criar várias chaves ao mesmo tempo. Por exemplo, um aplicativo pode criar uma subchave de quatro níveis de profundidade ao mesmo tempo que as três subchaves anteriores especificando uma cadeia de caracteres do seguinte formulário para o parâmetro lpSubKey :

subkey1\subkey2\subkey3\subkey4

Observe que esse comportamento resultará na criação de chaves indesejadas se uma chave existente no caminho estiver escrita incorretamente.

Nota

O cabeçalho winreg.h define RegCreateKey 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

RegCloseKey

RegCreateKeyEx

RegDeleteKey

RegOpenKeyEx

Funções do Registro

Visão geral do Registro