Função NtCreateTransactionManager (wdm.h)

Artigo
02/07/2025

A rotina de ZwCreateTransactionManager cria um novo objeto do gerenciador de transações.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

Parâmetros

[out] TmHandle

Um ponteiro para uma variável alocada por chamador que recebe um identificador para o novo objeto do gerenciador de transações .

[in] DesiredAccess

Um valor ACCESS_MASK que especifica o acesso solicitado do chamador ao objeto do gerenciador de transações. Além dos direitos de acesso definidos para todos os tipos de objetos (consulte ACCESS_MASK), o chamador pode especificar qualquer um dos seguintes sinalizadores de direito de acesso para objetos do gerenciador de transações.

sinalizador ACCESS_MASK	Permite que o chamador
TRANSACTIONMANAGER_CREATE_RM	Criar um gerenciador de recursos (consulte ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Obtenha informações sobre o gerenciador de transações (consulte ZwQueryInformationTransactionManager e ZwEnumerateTransactionObject). Também é necessário para ZwOpenResourceManager, ZwCreateTransaction e ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER	Recuperar o gerenciador de transações (consulte ZwRecoverTransactionManager e ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	Não usado.
TRANSACTIONMANAGER_SET_INFORMATION	Não usado.

Como alternativa, você pode especificar um ou mais dos bitmaps ACCESS_MASK a seguir. Esses bitmaps combinam os sinalizadores da tabela anterior com os sinalizadores deXXX STANDARD_RIGHTS_ descritos na página de referência ACCESS_MASK. Você também pode combinar esses bitmaps com sinalizadores adicionais da tabela anterior. A tabela a seguir mostra como os bitmaps correspondem a direitos de acesso específicos.

Bitmap de direitos	Conjunto de direitos de acesso específicos
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ e TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME e TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE e TRANSACTIONMANAGER_GENERIC_EXECUTE

[in, optional] ObjectAttributes

Um ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica o nome do objeto e outros atributos. Use a rotina InitializeObjectAttributes para inicializar essa estrutura. Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá definir o atributo OBJ_KERNEL_HANDLE quando chamar InitializeObjectAttributes. Esse parâmetro é opcional e pode ser NULL.

[in, optional] LogFileName

Um ponteiro para uma estrutura de UNICODE_STRING que contém o caminho e o nome do arquivo de um fluxo de arquivos de log CLFS ser associado ao objeto do gerenciador de transações. Esse parâmetro deve ser NULL se o parâmetro CreateOptions for TRANSACTION_MANAGER_VOLATILE. Caso contrário, esse parâmetro deve ser nãoNULL. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] CreateOptions

Sinalizadores de criação de objeto opcionais. A tabela a seguir contém os sinalizadores disponíveis, que são definidos em Ktmtypes.h.

Sinalizador de opção	Significado
TRANSACTION_MANAGER_VOLATILE	O objeto do gerenciador de transações será volátil. Portanto, ele não usará um arquivo de log.
TRANSACTION_MANAGER_COMMIT_DEFAULT	Somente para uso interno.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	Somente para uso interno.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	Somente para uso interno.
TRANSACTION_MANAGER_COMMIT_LOWEST	Somente para uso interno.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	Somente para uso interno.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	Somente para uso interno.

[in, optional] CommitStrength

Reservado para uso futuro. Esse parâmetro deve ser zero.

Valor de retorno

ZwCreateTransactionManager retorna STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, essa rotina poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O valor de um parâmetro de entrada é inválido.
STATUS_INSUFFICIENT_RESOURCES	O KTM não pôde alocar recursos do sistema (normalmente memória).
STATUS_LOG_CORRUPTION_DETECTED	KTM encontrou um erro ao criar ou abrir o arquivo de log.
STATUS_INVALID_ACL	Um descritor de segurança contém uma ACL (lista de controle de acesso) inválida.
STATUS_INVALID_SID	Um descritor de segurança contém um SID (identificador de segurança) inválido.
STATUS_OBJECT_NAME_EXISTS	O nome do objeto que o parâmetro ObjectAttributes especifica já existe.
STATUS_OBJECT_NAME_COLLISION	O sistema operacional detectou um nome de objeto duplicado. O erro pode indicar que o fluxo de log já está sendo usado.
STATUS_OBJECT_NAME_INVALID	O nome do objeto especificado pelo parâmetro ObjectAttributes é inválido.
STATUS_ACCESS_DENIED	O valor do parâmetro DesiredAccess é inválido.

A rotina pode retornar outros valores NTSTATUS .

Observações

Se o fluxo de arquivo de log que o parâmetro LogFileName especificar não existir, o KTM chamará CLFS para criar o fluxo. Se o fluxo já existir, a KTM chamará CLFS para abrir o fluxo.

Seu componente TPS deve chamar ZwRecoverTransactionManager depois de chamar ZwCreateTransactionManager

Se o componente TPS especificar o sinalizador TRANSACTION_MANAGER_VOLATILE no parâmetro CreateOptions, todos os gerenciadores de recursos associados ao objeto gerenciador de transações deverão especificar o sinalizador RESOURCE_MANAGER_VOLATILE quando chamarem ZwCreateResourceManager.

Um componente TPS que chama ZwCreateTransactionManager deve eventualmente chamar ZwClose para fechar o identificador de objeto.

Para obter mais informações sobre como usar ZwCreateTransactionManager, consulte Criando umdo Resource Manager.

NtCreateTransactionManager e ZwCreateTransactionManager são duas versões da mesma rotina dos Serviços de Sistema Nativo do Windows.

Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas de serviços do sistema nativo.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Windows Vista e versões posteriores do sistema operacional.
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	HwStorPortProhibitedDIs, PowerIrpDDis