WMI_FUNCTION_CONTROL_CALLBACK função de retorno de chamada (wmilib.h)

Artigo
02/07/2025

A rotina DpWmiFunctionControl habilita ou desabilita a notificação de eventos e habilita ou desabilita a coleta de dados para blocos de dados que o driver registrou como caros de coletar. Essa rotina é opcional.

Sintaxe

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

Parâmetros

[in] DeviceObject

Ponteiro para a estrutura de DEVICE_OBJECT WDM do driver.

[in] Irp

Ponteiro para o IRP.

[in] GuidIndex

Especifica o bloco de dados fornecendo um índice baseado em zero na lista de GUIDs fornecidos pelo driver na estrutura WMILIB_CONTEXT passada para WmiSystemControl.

[in] Function

Especifica o que habilitar ou desabilitar. WmiEventControl indica um evento e WmiDataBlockControl indica a coleta de dados de um bloco registrado como caro de coletar (ou seja, um bloco para o qual o conjunto de drivers WMIREG_FLAG_EXPENSIVE em Flags da estrutura WMIGUIDREGINFO usada para registrar o bloco).

[in] Enable

Especifica TRUE para habilitar o evento ou a coleta de dados ou FALSE para desabilitá-lo.

Valor de retorno

DpWmiFunctionControl retorna STATUS_SUCCESS ou um status de erro apropriado, como:

Observações

O WMI chama a rotina de DpWmiFunctionControl do driver depois que o driver chama WmiSystemControl em resposta a uma das seguintes solicitações:

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

Se um driver implementar uma rotina DpWmiFunctionControl, o driver deverá colocar o endereço da rotina no membro WmiFunctionControl da estrutura WMILIB_CONTEXT que ele passa para WmiSystemControl. Se um driver não implementar um rotina de DpWmiFunctionControl, ele deverá definir WmiFunctionControl para NULL. No último caso, o WMI retorna STATUS_SUCCESS ao chamador.

O driver é responsável por validar todos os argumentos de entrada. Especificamente, o driver deve fazer o seguinte:

Verifique se o guidIndex valor está entre zero e GuidCount-1, com base no GuidCount membro da estrutura WMILIB_CONTEXT.
Verifique se o driver não sinalizou o bloco de dados especificado para remoção. Se o driver especificou recentemente o sinalizador WMIREG_FLAG_REMOVE_GUID em uma estrutura de WMIGUIDREGINFO que está contida em uma estrutura WMILIB_CONTEXT, é possível que uma solicitação adicional chegue antes da remoção ocorrer.

É desnecessário que o driver verifique se eventos ou coleta de dados já estão habilitados para um bloco, pois o WMI envia uma única solicitação de habilitação quando o primeiro consumidor de dados habilita o bloco e envia uma única solicitação de desabilitação quando o último consumidor de dados desabilita o bloco. O WMI não chamará DpWmiFunctionControl para habilitar um bloco sem uma chamada intervindo para desabilitá-lo.

Depois de habilitar ou desabilitar o evento ou a coleta de dados do bloco, o driver chama WmiCompleteRequest para concluir a solicitação.

Essa rotina pode ser paginável.

Para obter mais informações sobre como implementar essa rotina, consulte Chamando WmiSystemControl para lidar comde IRPs WMI.