Compartilhar via


Função NtCreateEnlistment (wdm.h)

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

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             ResourceManagerHandle,
  [in]           HANDLE             TransactionHandle,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [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 ZwCreateEnlistment for bem-sucedida.

[in] DesiredAccess

Um valor ACCESS_MASK que especifica o acesso solicitado pelo chamador ao objeto de inscrição. 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 de inscrição:

sinalizador ACCESS_MASK Permite que o chamador
ENLISTMENT_QUERY_INFORMATION Consultar informações sobre a inscrição (consulte ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION Defina informações para a inscrição (consulte ZwSetInformationEnlistment).
ENLISTMENT_RECOVER Recupere a inscrição (consulte ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS Execute operações que um gerenciador de recursos que não é superior executa (consulte ZwRollbackEnlistment, ZwPrePrepareComplete, ZwPrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS Execute operações que um gerenciador de transações superior deve executar (consulte ZwPrepareEnlistment, ZwPrePrepareEnlistment, ZwCommitEnlistment).
 

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.

Direito de acesso genérico Conjunto de direitos de acesso específicos
ENLISTMENT_GENERIC_READ STANDARD_RIGHTS_READ e ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE STANDARD_RIGHTS_WRITE, ENLISTMENT_SET_INFORMATION, ENLISTMENT_RECOVER, ENLISTMENT_REFERENCE, ENLISTMENT_SUBORDINATE_RIGHTS e ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE, ENLISTMENT_RECOVER, ENLISTMENT_SUBORDINATE_RIGHTS e ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS STANDARD_RIGHTS_REQUIRED, ENLISTMENT_GENERIC_READ, ENLISTMENT_GENERIC_WRITE e ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

Um identificador para o objeto do gerenciador de recursos do chamador que foi obtido por uma chamada anterior para ZwCreateResourceManager ou ZwOpenResourceManager.

[in] TransactionHandle

Um identificador para um objeto de transação que foi obtido 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] 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] 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 de valores TRANSACTION_NOTIFY_XXX definidos em Ktmtypes.h. Essa 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

ZwCreateEnlistment 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_HANDLE
Um identificador de objeto é inválido.
STATUS_INVALID_PARAMETER
O valor do parâmetro CreateOptions ou NotificationMask é inválido ou o KTM não pôde localizar a transação especificada pelo parâmetro TransactionHandle .
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 TransactionHandle não está ativa.
STATUS_TRANSACTION_SUPERIOR_EXISTS
O chamador tentou se registrar como um gerenciador de transações superior, mas já existe um gerenciador de transações 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

Um gerenciador de recursos chama ZwCreateEnlistment para se inscrever em uma transação.

Os gerenciadores de recursos que não são superiores devem incluir o sinalizador ENLISTMENT_SUBORDINATE_RIGHTS na máscara de acesso.

Os gerenciadores de transações superiores devem incluir o sinalizador ENLISTMENT_SUPERIOR_RIGHTS em suas máscaras de acesso. Normalmente, um gerenciador de transações superior inclui código que chama ZwRollbackEnlistment, portanto, ele também deve incluir o sinalizador ENLISTMENT_SUBORDINATE_RIGHTS.

Um gerenciador de recursos que chama ZwCreateEnlistment deve eventualmente chamar ZwClose para fechar o identificador de objeto.

Seu gerenciador de recursos pode usar o parâmetro EnlistmentKey para atribuir um valor exclusivo a cada inscrição, como um ponteiro para uma estrutura de dados que contém informações sobre a inscrição. Por exemplo, se o gerenciador de recursos armazenar o identificador do objeto de inscrição na estrutura , o gerenciador de recursos poderá fazer o seguinte:

  1. Chame ZwGetNotificationResourceManager para obter uma notificação.
  2. Obtenha o valor da chave de inscrição da estrutura TRANSACTION_NOTIFICATION .
  3. Use a chave de inscrição para localizar o identificador do objeto de inscrição armazenado.
  4. Rotinas de chamada que exigem o identificador de inscrição como entrada, como ZwCommitComplete ou ZwRollbackComplete.
Para obter mais informações sobre ZwCreateEnlistment, consulte Criando um Resource Manager e Criando um Gerenciador de Transações Superior.

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services 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 Using Nt and Zw Versions of the Native System Services Routines.

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 da DDI HwStorPortProhibitedDDIs, PowerIrpDDis

Confira também

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

TRANSACTION_NOTIFICATION

Usando versões Nt e Zw das rotinas de serviços do sistema nativo

ZwClose

ZwCommitComplete

ZwCommitEnlistment

ZwCreateResourceManager

ZwCreateTransaction

ZwGetNotificationResourceManager

ZwOpenEnlistment

ZwOpenResourceManager

ZwOpenTransaction

ZwPrePrepareComplete

ZwPrePrepareEnlistment

ZwPrepareComplete

ZwPrepareEnlistment

ZwQueryInformationEnlistment

ZwReadOnlyEnlistment

ZwRecoverEnlistment

ZwRollbackComplete

ZwRollbackEnlistment

ZwSetInformationEnlistment

ZwSinglePhaseReject