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 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 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 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 criam chaves, se permitido por seu descritor de segurança.
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 precisa ser zero.
[in, optional] lpClass
A classe definida 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, 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, confira Executar 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 for descarregado. Por HKEY_LOCAL_MACHINE, isso ocorre quando o sistema é desligado. 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. |
[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.
[in] hTransaction
Um identificador para uma transação ativa. Esse identificador é retornado pela função CreateTransaction .
pExtendedParemeter
Esse parâmetro é reservado e deve ser NULL.
Valor retornado
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
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 .
Observação
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 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
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winreg.h (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |