Função ZwOpenTransactionManager (wdm.h)

Artigo
08/08/2023

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

Sintaxe

NTSYSCALLAPI NTSTATUS ZwOpenTransactionManager(
  [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 pelo 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 pelo 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 é reservado e precisa ser zero.

Valor retornado

ZwOpenTransactionManager retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, essa rotina pode 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.

Comentários

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 arquivo 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 que o chamador especificou anteriormente para a rotina 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 como 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 Objetos do Transaction Manager e Criando um Resource Manager.

NtOpenTransactionManager e ZwOpenTransactionManager são duas versões da mesma rotina do Windows Native System Services.

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do 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 dos Serviços de Sistema Nativo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows Vista e versões posteriores do sistema operacional.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (inclua Wdm.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)