Função RegCreateKeyTransactedA (winreg.h)
Cria a chave do Registro especificada e a associa a uma transação. Se a chave já existir, a função a abrirá. Observe que os nomes de chave não diferenciam maiúsculas de minúsculas.
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 RegCreateKeyTransactedA(
[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,
[in] HANDLE hTransaction,
PVOID pExtendedParemeter
);
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
Esse identificador é retornado pela função RegCreateKeyTransacted ou RegOpenKeyTransacted 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 deve ser zero.
[in, optional] lpClass
A classe definida 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, a chave será aberta com os direitos de acesso ACCESS_SYSTEM_SECURITY 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. |
|
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 quando o sistema é desligado. Para chaves do Registro carregadas pela função RegLoadKey |
[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.
[in] hTransaction
Um identificador para uma transação ativa. Esse identificador é retornado pela função
pExtendedParemeter
Esse parâmetro é reservado e deve ser NULL.
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
Quando uma chave é criada usando essa função, as operações subsequentes na chave são transacionadas. Se uma operação não transacionada for executada na chave antes que a transação seja confirmada, a transação será revertida. Depois que uma transação for confirmada ou revertida, você deverá reabrir a chave usando RegCreateKeyTransacted ou RegOpenKeyTransacted com um identificador de transação ativo para fazer operações adicionais transacionadas. Para obter mais informações sobre transações, consulte Kernel Transaction Manager.
Observe que as operações subsequentes em subchaves dessa chave não são transacionadas automaticamente. Portanto, RegDeleteKeyEx não executa uma operação de exclusão transacionada. Em vez disso, use a função RegDeleteKeyTransacted para executar uma operação de exclusão transacionada.
A chave que a função RegCreateKeyTransacted cria não tem valores. Um aplicativo pode usar a função RegSetValueEx para definir valores de chave.
A função RegCreateKeyTransacted 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.
Nota
O cabeçalho winreg.h define RegCreateKeyTransacted 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 Vista [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2008 [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
RegDeleteKeyTransacted