WMI_QUERY_DATABLOCK_CALLBACK función de devolución de llamada (wmilib.h)

Artículo
08/08/2023

La rutina DpWmiQueryDataBlock devuelve una sola instancia o todas las instancias de un bloque de datos. Esta rutina es necesaria.

Sintaxis

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

Puntero a la estructura de DEVICE_OBJECT WDM del controlador.

[in] Irp

Puntero al IRP.

[in] GuidIndex

Especifica el bloque de datos proporcionando un índice de base cero en la lista de GUID que el controlador proporcionó en la estructura de WMILIB_CONTEXT que pasó a WmiSystemControl.

[in] InstanceIndex

Si se llama a DpWmiQueryDataBlock en respuesta a una solicitud de IRP_MN_QUERY_SINGLE_INSTANCE , InstanceIndex especifica un índice de base cero que indica la instancia del bloque de datos especificado que se va a consultar. Si se llama a DpWmiQueryDataBlock en respuesta a una solicitud de IRP_MN_QUERY_ALL_DATA , InstanceIndex es cero.

[in] InstanceCount

Si se llama a DpWmiQueryDataBlock en respuesta a una solicitud de IRP_MN_QUERY_SINGLE_INSTANCE , InstanceCount es 1. Si se llama a DpWmiQueryDataBlock en respuesta a una solicitud de IRP_MN_QUERY_ALL_DATA , InstanceCount es el número de instancias que se van a devolver.

[in, out] InstanceLengthArray

Puntero a una matriz de elementos ULONG proporcionada por el autor de la llamada y de tamaño InstanceCount. El controlador rellena cada elemento de matriz para indicar la longitud de cada instancia devuelta. Si BufferAvail es cero, InstanceLengthArray es NULL.

[in] BufferAvail

Especifica el número máximo de bytes que están disponibles para recibir datos en el búfer en buffer. Si este valor es cero, el autor de la llamada solicita que el controlador especifique el tamaño de búfer necesario en su llamada a WmiCompleteRequest. Vea la sección Comentarios para obtener más información.

[out] Buffer

Puntero al búfer para recibir datos de instancia. Si el búfer es lo suficientemente grande como para recibir todos los datos, el controlador escribe los datos de instancia en el búfer con cada instancia alineada en un límite de 8 bytes. Si el búfer es demasiado pequeño para recibir todos los datos, el controlador llama a WmiCompleteRequest con BufferUsed establecido en el tamaño necesario.

Valor devuelto

DpWmiQueryDataBlock devuelve STATUS_SUCCESS o un estado de error como el siguiente:

Si el controlador no puede completar la solicitud inmediatamente, puede devolver STATUS_PENDING.

Comentarios

WMI llama a la rutina DpWmiQueryDataBlock de un controlador después de que el controlador llame a WmiSystemControl en respuesta a una solicitud de IRP_MN_QUERY_SINGLE_INSTANCE o IRP_MN_QUERY_ALL_DATA . El controlador debe colocar la dirección de su rutina DpWmiQueryDataBlock en la estructura WMILIB_CONTEXT que pasa a WmiSystemControl.

El controlador es responsable de validar todos los argumentos de entrada. En concreto, el controlador debe hacer lo siguiente:

Compruebe que el valor guidIndex está entre cero y GuidCount-1, en función del miembro GuidCount de la estructura WMILIB_CONTEXT .
Compruebe que el controlador no ha marcado el bloque de datos especificado para su eliminación. Si el controlador especificó recientemente la marca WMIREG_FLAG_REMOVE_GUID en una estructura WMIGUIDREGINFO contenida en una estructura de WMILIB_CONTEXT , es posible que una consulta llegue antes de que se produzca la eliminación.
Compruebe que los valores InstanceIndex e InstanceCount , juntos, especifiquen una serie de instancias de bloque de datos que se encuentran dentro del intervalo admitido por el controlador para el bloque de datos. Si InstanceIndex no es cero, InstanceCount debe ser 1. Si InstanceIndex es 0, InstanceCount no debe ser mayor que el número de instancias admitidas.
Compruebe que el búfer descrito por Buffer y BufferAvail es lo suficientemente grande como para contener todas las instancias solicitadas del bloque de datos. Cada instancia debe comenzar en un límite de 8 bytes y el relleno adicional puede existir entre los elementos de datos de cada instancia.

Después de escribir datos de instancia en el búfer, el controlador llama a WmiCompleteRequest para completar la solicitud. Si el búfer descrito por Buffer y BufferAvail es cero, o es demasiado pequeño para recibir todos los datos solicitados, la llamada a WmiCompleteRequest debe especificar STATUS_BUFFER_TOO_SMALL para el parámetro Status y el tamaño de búfer necesario para el parámetro BufferUsed .

Esta rutina puede ser paginable.

Para obtener más información sobre la implementación de esta rutina, vea Llamar a WmiSystemControl para controlar los IRP de WMI.