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 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 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 KEY_CREATE_SUB_KEY acesso à chave. Para obter mais informações, consulte Segurança de chave do Registro e Direitos de Acesso.
O acesso para criação de chave é 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 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] 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 precisa ser zero.
[in, optional] lpClass
O tipo de classe definido pelo usuário dessa chave. Esse parâmetro pode ser ignorado. Este parâmetro pode ser NULL.
[in] dwOptions
Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Se esse sinalizador for 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 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 SE_RESTORE_NAME habilitado, começando com o 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, confira Executar com privilégios especiais. |
|
Nota Os links simbólicos do Registro só devem ser usados para compatibilidade do aplicativo 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 for descarregado. Por HKEY_LOCAL_MACHINE, isso ocorre somente quando o sistema inicia um desligamento completo. Para chaves do Registro carregadas pela função RegLoadKey , isso ocorre quando o RegUnLoadKey correspondente é executado. A função RegSaveKey não salva chaves voláteis. Esse sinalizador é ignorado para chaves que já existem.
Nota Em um desligamento selecionado pelo usuário, um desligamento rápido de inicialização é 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 Segurança de chave do Registro e Direitos de Acesso.
[in, optional] lpSecurityAttributes
Um ponteiro para uma estrutura 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 membro lpSecurityDescriptor 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 do Registro predefinidas, 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.
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
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 Virtualização do Registro e Dados do Aplicativo de 32 bits e 64 bits no Registro.
Observação
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 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 |