Função WmiSystemControl (wmilib.h)

Artigo
08/08/2023

A rotina WmiSystemControl é uma rotina de expedição para drivers que usam rotinas de suporte da biblioteca WMI para lidar com IRPs WMI.

Sintaxe

NTSTATUS WmiSystemControl(
  [in]      PWMILIB_CONTEXT         WmiLibInfo,
  [in]      PDEVICE_OBJECT          DeviceObject,
  [in, out] PIRP                    Irp,
  [out]     PSYSCTL_IRP_DISPOSITION IrpDisposition
);

Parâmetros

[in] WmiLibInfo

Um ponteiro para uma estrutura WMILIB_CONTEXT que contém informações de registro para blocos de dados e blocos de eventos de um driver e define pontos de entrada para as rotinas de retorno de chamada da biblioteca WMI do driver.

[in] DeviceObject

Um ponteiro para o DEVICE_OBJECT do driver.

[in, out] Irp

Um ponteiro para o IRP.

[out] IrpDisposition

Um ponteiro para um valor de enumeração do tipo SYSCTL_IRP_DISPOSITION que indica como o IRP foi tratado. WmiSystemControl sempre define esse valor, mesmo quando retorna um código NTSTATUS sem êxito.

SYSCTL_IRP_DISPOSITION é uma enumeração em Wmilib.h e contém os seguintes valores:

IrpProcessed

O IRP foi processado e possivelmente concluído. Se a rotina DpWmiXxx do driver chamada por WmiSystemControl não tiver concluído o IRP, o driver deverá chamar WmiCompleteRequest para concluir o IRP depois que WmiSystemControl retornar.

IrpNotCompleted

O IRP foi processado, mas não concluído, porque o WMI detectou um erro e configurou o IRP com um código de erro apropriado ou processou uma solicitação de IRP_MN_REGINFO ou IRP_MN_REGINFO_EX . O driver deve concluir o IRP chamando IoCompleteRequest.

IrpNotWmi

O IRP não é uma solicitação WMI (ou seja, o WMI não reconhece o código secundário do IRP). Se o driver manipular solicitações IRP_MJ_SYSTEM_CONTROL com esse IRP_MN_XXX, ele deverá manipular o IRP; caso contrário, o driver deve encaminhar o IRP para o próximo driver inferior. Se o driver for o driver de nível mais baixo, ele deverá concluir o IRP.

IrpForward

O IRP é direcionado a outro objeto de dispositivo (ou seja, o ponteiro do objeto do dispositivo em Parameters.WMI.ProviderId no IRP não corresponde ao ponteiro passado pelo driver em sua chamada para IoWMIRegistrationControl). O driver deve encaminhar o IRP para o próximo driver inferior. Se o driver for o driver de nível mais baixo, ele deverá concluir o IRP.

Retornar valor

WmiSystemControl retorna STATUS_SUCCESS ou um dos seguintes códigos de erro:

Comentários

Quando um driver recebe uma solicitação IRP_MJ_SYSTEM_CONTROL com um código secundário WMI IRP, ele chama WmiSystemControl com um ponteiro para a estrutura de WMILIB_CONTEXT do driver, um ponteiro para seu objeto de dispositivo e um ponteiro para o IRP. A estrutura WMILIB_CONTEXT contém informações de registro para blocos de dados e blocos de eventos do driver e define pontos de entrada para suas rotinas de retorno de chamada da biblioteca WMI.

WmiSystemControl confirma que o IRP é uma solicitação WMI e determina se o bloco especificado pela solicitação é válido para o driver. Nesse caso, ele processa o IRP chamando o ponto de entrada DpWmiXxx apropriado na estrutura de WMILIB_CONTEXT do driver. O WMI está em execução no IRQL PASSIVE_LEVEL quando chama a rotina DpWmiXxx do driver.

Um driver deve estar em execução no IRQL PASSIVE_LEVEL quando encaminha uma solicitação de IRP_MJ_SYSTEM_CONTROL para o driver inferior seguinte.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 2000 e versões posteriores do Windows.
Plataforma de Destino	Universal
Cabeçalho	wmilib.h (inclua Wmilib.h)
Biblioteca	Wmilib.lib
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade da DDI	WmiComplete(wdm)