Função RegCreateKeyExA (winreg.h)
Cria a chave do Registro especificada. Se a chave já existir, a função a abrirá. Observe que os nomes de chave não diferenciam maiúsculas de minúsculas.
Para executar operações de registro transacionadas em uma chave, chame a função RegCreateKeyTransacted.
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 RegCreateKeyExA(
[in] HKEY hKey,
[in] LPCSTR lpSubKey,
DWORD Reserved,
[in, optional] LPSTR lpClass,
[in] DWORD dwOptions,
[in] REGSAM samDesired,
[in, optional] const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[out] PHKEY phkResult,
[out, optional] LPDWORD lpdwDisposition
);
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 modificam o registro se permitido por seu descritor de segurança.
Esse identificador é retornado pela função RegCreateKeyEx
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_USERS
[in] lpSubKey
O nome de uma subchave que essa função abre ou cria. A subchave especificada deve ser uma subchave da chave identificada pelo parâmetro hKey; pode ter até 32 níveis de profundidade na árvore do Registro. Para obter mais informações sobre nomes de chave, consulte Estrutura do Registro.
Se lpSubKey for um ponteiro para uma cadeia de caracteres vazia, phkResult receberá um novo identificador para a chave especificada por hKey.
Esse parâmetro não pode ser NULL.
Reserved
Esse parâmetro é reservado e deve ser zero.
[in, optional] lpClass
O tipo de classe definido pelo usuário dessa chave. Esse parâmetro pode ser ignorado. Esse parâmetro pode ser NULL.
[in] dwOptions
Esse parâmetro pode ser um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Se esse sinalizador estiver definido, a função ignorará o parâmetro samDesired e tentará abrir a chave com o acesso necessário para fazer backup ou restaurar a chave. Se o thread de chamada tiver o privilégio de SE_BACKUP_NAME habilitado, a chave será aberta com os direitos de acesso ACCESS_SYSTEM_SECURITY e KEY_READ. Se o thread de chamada tiver o privilégio de SE_RESTORE_NAME habilitado, começando pelo Windows Vista, a chave será aberta com os direitos de acesso ACCESS_SYSTEM_SECURITY, DELETE e KEY_WRITE. Se ambos os privilégios estiverem habilitados, a chave terá os direitos de acesso combinados para ambos os privilégios. Para obter mais informações, consulte Em execução com privilégios especiais. |
|
Observação links simbólicos do Registro só devem ser usados para compatibilidade de aplicativos quando absolutamente necessário.
|
|
Essa chave não é volátil; esse é o padrão. As informações são armazenadas em um arquivo e preservadas quando o sistema é reiniciado. A função RegSaveKey salva chaves que não são voláteis. |
|
Todas as chaves criadas pela função são voláteis. As informações são armazenadas na memória e não são preservadas quando o hive do registro correspondente é descarregado. Para HKEY_LOCAL_MACHINE, isso ocorre somente quando o sistema inicia um desligamento completo. Para chaves do Registro carregadas pela função RegLoadKey
Observação Em um desligamento selecionado pelo usuário, um desligamento de inicialização rápida é o comportamento padrão para o sistema.
|
[in] samDesired
Uma máscara que especifica os direitos de acesso para a chave a ser criada. Para obter mais informações, consulte de Direitos de Acesso e Segurança de Chave do Registro.
[in, optional] lpSecurityAttributes
Um ponteiro para uma estrutura de SECURITY_ATTRIBUTES que determina se o identificador retornado pode ser herdado por processos filho. Se lpSecurityAttributes for NULL, o identificador não poderá ser herdado.
O lpSecurityDescriptor membro da estrutura especifica um descritor de segurança para a nova chave. Se lpSecurityAttributes for NULL, a chave obterá um descritor de segurança padrão. As ACLs em um descritor de segurança padrão para uma chave são herdadas de sua chave pai direta.
[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.
[out, optional] lpdwDisposition
Um ponteiro para uma variável que recebe um dos seguintes valores de disposição.
| Valor | Significado |
|---|---|
|
A chave não existia e foi criada. |
|
A chave existia e foi simplesmente aberta sem ser alterada. |
Se lpdwDisposition for NULL, nenhuma informação de disposição será retornada.
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
Observações
A chave que a função RegCreateKeyEx cria não tem valores. Um aplicativo pode usar a função RegSetValueEx para definir valores de chave.
A função RegCreateKeyEx 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.
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.
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.
Nota
O cabeçalho winreg.h define RegCreateKeyEx 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
RegDeleteKey
RegOpenKeyEx