Função ZwOpenEnlistment (wdm.h)

Artigo
02/27/2024

A rotina ZwOpenEnlistment obtém um identificador para um objeto de alistamento existente.

Sintaxe

NTSYSCALLAPI NTSTATUS ZwOpenEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             RmHandle,
  [in]           LPGUID             EnlistmentGuid,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes
);

Parâmetros

[out] EnlistmentHandle

Um ponteiro para uma variável alocada pelo chamador que recebe um identificador para um objeto de alistamento se a chamada para ZwOpenEnlistment for bem-sucedida.

[in] DesiredAccess

Um valor do tipo ACCESS_MASK que especifica o acesso solicitado ao objeto de inscrição. Para obter mais informações sobre como especificar esse parâmetro, consulte o parâmetro DesiredAccess de ZwCreateEnlistment. Esse parâmetro não pode ser zero.

[in] RmHandle

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

[in] EnlistmentGuid

Um ponteiro para um GUID que identifica o alistamento. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] ObjectAttributes

Um ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica os atributos do objeto. Use a rotina InitializeObjectAttributes para inicializar essa estrutura, mas especifique apenas os parâmetros InitializedAttributes e Attributes dessa rotina. Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá definir o sinalizador OBJ_KERNEL_HANDLE no parâmetro Attributes . Esse parâmetro é opcional e pode ser NULL.

Retornar valor

ZwOpenEnlistment 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	O identificador do objeto é inválido.
STATUS_ACCESS_DENIED	O chamador não tem acesso apropriado ao objeto de inscrição.
STATUS_INVALID_PARAMETER	O valor do parâmetro DesiredAccess é zero ou o valor do parâmetro EnlistmentGuid é NULL.
STATUS_ENLISTMENT_NOT_FOUND	A inscrição especificada pelo parâmetro EnlistmentGuid não existe para o gerenciador de recursos especificado pelo parâmetro RmHandle .
STATUS_ACCESS_DENIED	O valor do parâmetro DesiredAccess é inválido.

A rotina pode retornar outros valores NTSTATUS.

Comentários

Normalmente, um componente TPS chama ZwOpenEnlistment depois de receber um GUID de inscrição de outro componente TPS que anteriormente havia chamado ZwCreateEnlistment. A maioria dos designs de TPS não exige chamar ZwOpenEnlistment.

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

Para obter mais informações sobre ZwOpenEnlistment, consulte Objetos de inscrição.

NtOpenEnlistment e ZwOpenEnlistment são duas versões da mesma rotina dos Serviços do Sistema Nativo do Windows.

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)