Função NtOpenTransactionManager (wdm.h)

Artigo
02/07/2025

A rotina ZwOpenTransactionManager obtém um identificador para um objeto do gerenciador de transações existente.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] LPGUID             TmIdentity,
  [in, optional] ULONG              OpenOptions
);

Parâmetros

[out] TmHandle

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

[in] DesiredAccess

Um valor ACCESS_MASK que especifica o acesso solicitado do chamador ao objeto do gerenciador de transações. Para obter informações sobre como especificar esse parâmetro, consulte o parâmetro DesiredAccess de ZwCreateTransactionManager.

[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 UNICODE_STRING que contém o caminho e o nome do arquivo do fluxo de arquivos de log que foi criado quando o objeto do gerenciador de transações foi criado. Para obter mais informações, consulte o parâmetro LogFileName de ZwCreateTransactionManager . Esse parâmetro é opcional e pode ser NULL.

[in, optional] TmIdentity

Um ponteiro para um GUID que identifica o objeto do gerenciador de transações. Esse parâmetro é opcional e pode ser NULL.

[in, optional] OpenOptions

Esse parâmetro não é usado e deve ser zero.

Valor de retorno

ZwOpenTransactionManager retornará 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_OBJECT_NAME_INVALID	O nome do objeto especificado pelo parâmetro ObjectAttributes é inválido.
STATUS_LOG_CORRUPTION_DETECTED	KTM encontrou um erro ao criar ou abrir o arquivo de log.
STATUS_ACCESS_DENIED	O valor do parâmetro DesiredAccess é inválido.

A rotina pode retornar outros valores NTSTATUS .

Observações

O chamador pode identificar qual objeto do gerenciador de transações abrir usando uma das três técnicas a seguir:

Use o parâmetro LogFileName para especificar o caminho e o nome do arquivo de um fluxo de arquivos de log que foi criado quando o objeto do gerenciador de transações foi criado.
Use o parâmetro TmIdentity para especificar o GUID que identifica o objeto do gerenciador de transações.
Use o parâmetro ObjectAttributes para fornecer uma estrutura OBJECT_ATTRIBUTES que contém o nome do objeto especificado anteriormente para a rotina de ZwCreateTransactionManager.

Você deve especificar apenas um dos parâmetros listados acima (um nome de objeto, um nome de arquivo de log ou um GUID) e definir os outros dois parâmetros para NULL.

Seu componente TPS deve chamar ZwRecoverTransactionManager depois de chamar ZwOpenTransactionManager.

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

Para obter mais informações sobre como usar ZwOpenTransactionManager, consulte de objetos do Gerenciador de Transações e Criando umdo Resource Manager.

NtOpenTransactionManager e ZwOpenTransactionManager 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