Função ZwCreateTransaction (wdm.h)

Artigo
03/14/2023

A rotina ZwCreateTransaction cria um objeto de transação.

Sintaxe

NTSYSCALLAPI NTSTATUS ZwCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

Parâmetros

[out] TransactionHandle

Um ponteiro para uma variável alocada pelo chamador que recebe um identificador para o novo objeto de transação, se a chamada para ZwCreateTransaction for bem-sucedida.

[in] DesiredAccess

Um valor ACCESS_MASK que especifica o acesso solicitado pelo chamador ao objeto de transação. Além dos direitos de acesso definidos para todos os tipos de objetos (consulte ACCESS_MASK), o chamador pode especificar qualquer um dos sinalizadores a seguir para objetos de transação.

Máscara de acesso	Permite que o chamador
TRANSACTION_COMMIT	Confirme a transação (consulte ZwCommitTransaction).
TRANSACTION_ENLIST	Crie uma inscrição para a transação (consulte ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Não use.
TRANSACTION_QUERY_INFORMATION	Obtenha informações sobre a transação (consulte ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Reverter a transação (consulte ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Defina informações para a transação (consulte ZwSetInformationTransaction).

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 STANDARD_RIGHTS_XXX descritos na página de referência do 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
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION e SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT e SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK e SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE e TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE e SYNCHRONIZE

Normalmente, um gerenciador de recursos especifica TRANSACTION_RESOURCE_MANAGER_RIGHTS.

O valor DesiredAccess não pode ser zero.

[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] Uow

Um ponteiro para um GUID que o KTM usa como o identificador UOW (unidade de trabalho) do novo objeto de transação. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for NULL, KTM gerará um GUID e o atribuirá ao objeto de transação. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] TmHandle

Um identificador para um objeto do gerenciador de transações que foi obtido por uma chamada anterior para ZwCreateTransactionManager ou ZwOpenTransactionManager. KTM atribui o novo objeto de transação ao objeto do gerenciador de transações especificado. Se esse parâmetro for NULL, o KTM atribuirá o novo objeto de transação a um gerenciador de transações posteriormente, quando um gerenciador de recursos criar uma inscrição para a transação.

[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_DO_NOT_PROMOTE	Reservado para uso futuro.

[in, optional] IsolationLevel

Reservado para uso futuro. Os chamadores devem definir esse parâmetro como zero.

[in, optional] IsolationFlags

Reservado para uso futuro. Os chamadores devem definir esse parâmetro como zero.

[in, optional] Timeout

Um ponteiro para um valor de tempo limite. Se a transação não tiver sido confirmada até o momento especificado por esse parâmetro, o KTM reverterá a transação. O valor de tempo limite é expresso em unidades de tempo do sistema (intervalos de 100 nanossegundos) e pode especificar um tempo absoluto ou um tempo relativo. Se o valor apontado por Timeout for negativo, o tempo de expiração será relativo à hora atual do sistema. Caso contrário, o tempo de expiração será absoluto. Esse ponteiro é opcional e pode ser NULL se você não quiser que a transação tenha um valor de tempo limite. Se Timeout = NULL ou *Timeout = 0, a transação nunca atingirá o tempo limite. (Você também pode usar ZwSetInformationTransaction para definir um valor de tempo limite.)

[in, optional] Description

Um ponteiro para uma estrutura de UNICODE_STRING fornecida pelo chamador que contém uma cadeia de caracteres terminada em NULL. A cadeia de caracteres fornece uma descrição da transação. A KTM armazena uma cópia da cadeia de caracteres e inclui a cadeia de caracteres em mensagens que ela grava no fluxo de log. O comprimento máximo da cadeia de caracteres é MAX_TRANSACTION_DESCRIPTION_LENGTH. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

ZwCreateTransaction 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 parâmetro CreateOptions contém um sinalizador inválido, o parâmetro DesiredAccess é zero ou a cadeia de caracteres do parâmetro Description é muito longa.
STATUS_INSUFFICIENT_RESOURCES	O KTM não pôde alocar recursos do sistema (normalmente memória).
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_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.

Comentários

O chamador pode usar o parâmetro Uow para especificar um identificador UOW para o objeto de transação. Se o chamador não especificar um identificador UOW, o KTM gerará um GUID e o atribuirá ao objeto de transação. Posteriormente, o chamador pode obter esse GUID chamando ZwQueryInformationTransaction.

Normalmente, você deve permitir que o KTM gere um GUID para o objeto de transação, a menos que o componente se comunique com outro componente TPS que já tenha gerado um identificador UOW para a transação.

Para fechar o identificador de transação, o componente chamado ZwCreateTransaction deve chamar ZwClose. Se o último identificador de transação for fechado antes que qualquer componente chame ZwCommitTransaction para a transação, o KTM reverterá a transação.

Para obter mais informações sobre como os clientes de transação devem usar ZwCreateTransaction, consulte Criando um cliente transacional.

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 (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)