Função RegCreateKeyA (winreg.h)

Artigo
03/08/2023

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

Nota 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 fazem backup ou restauram o estado do sistema, incluindo arquivos do sistema e hives do 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 KEY_CREATE_SUB_KEY acesso à chave. Para obter mais informações, consulte Segurança de Chave do Registro e Direitos de Acesso.

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 o 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 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.

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

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.

Observação

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 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