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

Artigo
03/01/2024

A rotina DpWmiQueryDataBlock retorna uma única instância ou todas as instâncias de um bloco de dados. Essa rotina é necessária.

Sintaxe

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [out]     PUCHAR Buffer
)
{...}

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 de WMILIB_CONTEXT que ele passou para WmiSystemControl.

[in] InstanceIndex

Se DpWmiQueryDataBlock for chamado em resposta a uma solicitação de IRP_MN_QUERY_SINGLE_INSTANCE , InstanceIndex especificará um índice baseado em zero que indica a instância do bloco de dados especificado a ser consultado. Se DpWmiQueryDataBlock for chamado em resposta a uma solicitação IRP_MN_QUERY_ALL_DATA , InstanceIndex será zero.

[in] InstanceCount

Se DpWmiQueryDataBlock for chamado em resposta a uma solicitação de IRP_MN_QUERY_SINGLE_INSTANCE , InstanceCount será 1. Se DpWmiQueryDataBlock for chamado em resposta a uma solicitação de IRP_MN_QUERY_ALL_DATA , InstanceCount será o número de instâncias a serem retornadas.

[in, out] InstanceLengthArray

Ponteiro para uma matriz de elementos ULONG do tamanho de InstanceCount fornecida pelo chamador. O driver preenche cada elemento de matriz para indicar o comprimento de cada instância que foi retornada. Se BufferAvail for zero, InstanceLengthArray será NULL.

[in] BufferAvail

Especifica o número máximo de bytes disponíveis para receber dados no buffer em Buffer. Se esse valor for zero, o chamador solicitará que o driver especifique o tamanho do buffer necessário em sua chamada para WmiCompleteRequest. Consulte a seção Comentários para obter mais informações.

[out] Buffer

Ponteiro para o buffer para receber dados da instância. Se o buffer for grande o suficiente para receber todos os dados, o driver gravará os dados da instância no buffer com cada instância alinhada em um limite de 8 bytes. Se o buffer for muito pequeno para receber todos os dados, o driver chamará WmiCompleteRequest com BufferUsed definido como o tamanho necessário.

Retornar valor

DpWmiQueryDataBlock retorna STATUS_SUCCESS ou um erro status como o seguinte:

Se o driver não puder concluir a solicitação imediatamente, ele poderá retornar STATUS_PENDING.

Comentários

A WMI chama a rotina DpWmiQueryDataBlock de um driver depois que o driver chama WmiSystemControl em resposta a uma solicitação de IRP_MN_QUERY_SINGLE_INSTANCE ou IRP_MN_QUERY_ALL_DATA . O driver deve colocar o endereço de sua rotina DpWmiQueryDataBlock na estrutura WMILIB_CONTEXT que ele passa para WmiSystemControl.

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 tiver especificado recentemente o sinalizador WMIREG_FLAG_REMOVE_GUID em uma estrutura WMIGUIDREGINFO contida em uma estrutura WMILIB_CONTEXT , é possível que uma consulta chegue antes da remoção ocorrer.
Verifique se os valores InstanceIndex e InstanceCount , juntos, especificam várias instâncias de bloco de dados que estão dentro do intervalo com suporte do driver para o bloco de dados. Se InstanceIndex não for zero, InstanceCount deverá ser 1. Se InstanceIndex for 0, InstanceCount não deverá ser maior do que o número de instâncias com suporte.
Verifique se o buffer descrito por Buffer e BufferAvail é grande o suficiente para manter todas as instâncias solicitadas do bloco de dados. Cada instância deve começar em um limite de 8 bytes e pode existir preenchimento adicional entre itens de dados em cada instância.

Depois de gravar dados de instância no buffer, o driver chama WmiCompleteRequest para concluir a solicitação. Se o buffer descrito por Buffer e BufferAvail for zero ou for muito pequeno para receber todos os dados solicitados, a chamada para WmiCompleteRequest deverá especificar STATUS_BUFFER_TOO_SMALL para o parâmetro Status e o tamanho do buffer necessário para o parâmetro BufferUsed .

Essa rotina pode ser paginável.

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