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

Artigo
02/27/2024

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 do 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 que o driver forneceu 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 que foi registrado como caro de coletar (ou seja, um bloco para o qual o driver definido WMIREG_FLAG_EXPENSIVE em Sinalizadores 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.

Retornar valor

DpWmiFunctionControl retorna STATUS_SUCCESS ou um erro apropriado status como:

Comentários

O WMI chama a rotina DpWmiFunctionControl de um 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 uma rotina DpWmiFunctionControl , ele deverá definir WmiFunctionControl como NULL. No último caso, o WMI retorna STATUS_SUCCESS para o chamador.

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

Verifique se o valor guidIndex está entre zero e GuidCount-1, com base no membro GuidCount 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 WMIGUIDREGINFO contida em uma estrutura WMILIB_CONTEXT , é possível que uma solicitação adicional chegue antes que a remoção ocorra.

É desnecessário que o driver marcar se os eventos ou a 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 intermediária para desabilitá-lo.

Depois de habilitar ou desabilitar o evento ou a coleta de dados para o 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 com IRPs WMI.