Função NtCreateEnlistment (wdm.h)
A rotina de 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 por 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 do 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 alistamento:
| 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 | Recuperar a inscrição (consulte ZwRecoverEnlistment). |
| ENLISTMENT_SUBORDINATE_RIGHTS | Executar operações que um gerenciador de recursos que não é superior executa (consulte ZwRollbackEnlistment, ZwPrepareComplete, ZwPrepareComplete, Z, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment). |
| ENLISTMENT_SUPERIOR_RIGHTS | Execute operações que um gerente 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 deXXX STANDARD_RIGHTS_ descritos na página de referência 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 do objeto do gerenciador de recursos do chamador que foi obtido por uma chamada anterior para ZwCreateResourceManager ou ZwOpenResourceManager.
[in] TransactionHandle
Um identificador de um objeto de transação obtido por uma chamada anterior para ZwCreateTransaction ou ZwOpenTransaction. A 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 superior do gerenciador de transações para a transação especificada. |
Esse parâmetro é opcional e pode ser zero.
[in] NotificationMask
Um OR bit a bit de TRANSACTION_NOTIFY_valores de XXX definidos em Ktmtypes.h. Essa máscara especifica os tipos de notificações de transação que a 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 a KTM chama o ResourceManagerNotification rotina de retorno de chamada. 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.
Valor de retorno
ZwCreateEnlistment retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, essa rotina poderá retornar um dos seguintes valores:
A rotina pode retornar outros valores NTSTATUS .
Observações
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 de ENLISTMENT_SUBORDINATE_RIGHTS na máscara de acesso.
gerentes 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.
O 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:
- Chame ZwGetNotificationResourceManager para obter uma notificação.
- Obtenha o valor da chave de inscrição da estrutura de TRANSACTION_NOTIFICATION.
- Use a chave de inscrição para localizar o identificador de objeto de inscrição armazenado.
- Rotinas de chamadas que exigem o identificador de inscrição como entrada, como ZwCommitComplete ou ZwRollbackComplete.
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, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs, PowerIrpDDis |
Consulte também
usando versões Nt e Zw das rotinas de serviços do sistema nativo