Função TmCreateEnlistment (wdm.h)

Artigo
02/27/2024

A rotina TmCreateEnlistment cria um novo objeto de inscrição para uma transação.

Sintaxe

NTSTATUS TmCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           KPROCESSOR_MODE    PreviousMode,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           PRKRESOURCEMANAGER ResourceManager,
  [in]           PKTRANSACTION      Transaction,
  [in, optional] ULONG              CreateOptions,
  [in]           NOTIFICATION_MASK  NotificationMask,
  [in, optional] PVOID              EnlistmentKey
);

Parâmetros

[out] EnlistmentHandle

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

[in] PreviousMode

O modo de processador do processo que usará o identificador de inscrição para acessar o objeto de inscrição. Esse valor deve ser UserMode ou KernelMode.

[in] DesiredAccess

Um valor ACCESS_MASK que especifica o acesso solicitado pelo chamador ao objeto de inscrição. Para obter mais informações sobre esse parâmetro, consulte a descrição do parâmetro DesiredAccess para ZwCreateEnlistment.

[in] 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] ResourceManager

Um ponteiro para um objeto do gerenciador de recursos. Para obter esse ponteiro, seu componente deve chamar ObReferenceObjectByHandle e fornecer o identificador de objeto fornecido por uma chamada anterior para ZwCreateResourceManager ou ZwOpenResourceManager .

[in] Transaction

Um ponteiro para um objeto de transação. Para obter esse ponteiro, seu componente deve chamar ObReferenceObjectByHandle e fornecer o identificador de objeto fornecido por uma chamada anterior para ZwCreateTransaction ou ZwOpenTransaction . KTM adiciona essa transação à lista de transações que o gerenciador de recursos de chamada está tratando.

[in, optional] CreateOptions

Sinalizadores de opção de inscrição. A tabela a seguir contém o único sinalizador disponível.

Sinalizador CreateOptions	Significado
ENLISTMENT_SUPERIOR	O chamador está se inscrevendo como um gerenciador de transações superior para a transação especificada.

Esse parâmetro é opcional e pode ser zero.

[in] NotificationMask

Um OR bit a bit dos valores TRANSACTION_NOTIFY_XXX definidos em Ktmtypes.h. Esse valor de máscara especifica os tipos de notificações de transação que o KTM envia ao chamador.

[in, optional] EnlistmentKey

Um ponteiro para informações definidas pelo chamador que identifica exclusivamente a inscrição. O gerenciador de recursos recebe esse ponteiro quando chama ZwGetNotificationResourceManager ou quando KTM chama a rotina de retorno de chamada ResourceManagerNotification . O gerenciador de recursos pode manter uma contagem de referência para essa chave chamando TmReferenceEnlistmentKey e TmDereferenceEnlistmentKey. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

TmCreateEnlistment 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 do parâmetro CreateOptions ou NotificationMask é inválido ou KTM não pôde encontrar a transação especificada pelo parâmetro Transaction .
STATUS_INSUFFICIENT_RESOURCES	Falha na alocação de memória.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	A inscrição falhou porque o KTM ou o gerenciador de recursos não está em um estado operacional.
STATUS_TRANSACTION_NOT_ACTIVE	A inscrição falhou porque a transação especificada pelo parâmetro Transaction não está ativa.
STATUS_TRANSACTION_SUPERIOR_EXISTS	O chamador tentou se registrar como um gerenciador de transações superior , mas já existe uma inscrição superior.
STATUS_TM_VOLATILE	O chamador está tentando se registrar como um gerenciador de transações superior, mas o objeto do gerenciador de recursos do chamador é volátil enquanto o objeto do gerenciador de transações associado não é volátil.
STATUS_ACCESS_DENIED	O valor do parâmetro DesiredAccess é inválido.

A rotina pode retornar outros valores NTSTATUS.

Comentários

A rotina TmCreateEnlistment é uma versão baseada em ponteiro da rotina ZwCreateEnlistment .

Para obter informações sobre quando usar as rotinas TmXxx da KTM em vez de rotinas ZwXxx , consulte Usando rotinas TmXxx.

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