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

Artículo
08/08/2023

La rutina DpWmiQueryReginfo proporciona información sobre los bloques de datos y los bloques de eventos que va a registrar un controlador. Esta rutina es necesaria.

Sintaxis

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

Parámetros

[in] DeviceObject

Puntero a la estructura WDM del controlador DEVICE_OBJECT.

[out] RegFlags

Este parámetro indica las características comunes de todos los bloques que se registran. Cualquier marca establecida en RegFlags se aplica a todos los bloques. Un controlador puede complementar RegFlags para un bloque determinado estableciendo Marcas en la estructura WMIGUIDREGINFO del bloque. Por ejemplo, un controlador podría borrar WMIREG_FLAG_EXPENSIVE en RegFlags, pero establecerlo en Marcas para registrar un bloque determinado como caro de recopilar.

El controlador establece una de las marcas siguientes en RegFlags:

WMIREG_FLAG_INSTANCE_BASENAME

Solicita a WMI que genere nombres de instancia estáticos a partir de un nombre base proporcionado por el controlador en InstanceName. WMI genera nombres de instancia anexando un contador al nombre base.

WMIREG_FLAG_INSTANCE_PDO

Solicita a WMI que genere nombres de instancia estáticos a partir del identificador de instancia de dispositivo para el PDO. Si el controlador establece esta marca, también debe establecer Pdo en el PDO pasado a la rutina AddDevice del controlador. WMI genera nombres de instancia a partir de la ruta de acceso de la instancia de dispositivo del PDO. El uso de la ruta de acceso de la instancia de dispositivo como base para nombres de instancia estáticos es eficaz porque se garantiza que estos nombres son únicos. WMI proporciona automáticamente un nombre "descriptivo" para la instancia como un elemento de un bloque de datos que los consumidores de datos pueden consultar.

Un controlador también puede establecer una o varias de las marcas siguientes en RegFlags, pero más normalmente las establecería en Marcas de la estructura WMIGUIDREGINFO de un bloque:

WMIREG_FLAG_EVENT_ONLY_GUID

Los bloques solo se pueden habilitar o deshabilitar como eventos y no se pueden consultar ni establecer. Si esta marca está desactivada, los bloques también se pueden consultar o establecer.

WMIREG_FLAG_EXPENSIVE

Solicita a WMI que envíe un IRP_MN_ENABLE_COLLECTION solicitud la primera vez que un consumidor de datos abra un bloque de datos y una solicitud de IRP_MN_DISABLE_COLLECTION cuando el último consumidor de datos cierre el bloque de datos. Esto se recomienda si la recopilación de estos datos afecta al rendimiento, ya que un controlador no necesita recopilar los datos hasta que un consumidor de datos lo solicite explícitamente abriendo el bloque .

WMIREG_FLAG_REMOVE_GUID

Solicita a WMI que quite la compatibilidad con los bloques. Esta marca solo es válida en respuesta a una solicitud para actualizar la información de registro (IRP_MN_REGINFO o IRP_MN_REGINFO_EX con Parameters.WMI.DataPath establecido en WMIUPDATE).

[out] InstanceName

Puntero a una sola cadena Unicode con recuento que actúa como nombre base para todas las instancias de todos los bloques que va a registrar el controlador. WMI libera la cadena con ExFreePool. Si WMIREG_FLAG_INSTANCE_BASENAME está claro, se omite InstanceName .

[out] RegistryPath

Puntero a un puntero a una cadena Unicode con recuento que especifica la ruta de acceso del Registro pasada a la rutina DriverEntry del controlador.

[out] MofResourceName

Puntero a una sola cadena Unicode con recuento que indica el nombre del recurso MOF asociado al archivo de imagen binaria del controlador. Normalmente, esta cadena sería una estática definida por el controlador. WMI realiza una copia de esta cadena después de que el controlador vuelva de esta rutina. El controlador puede asignar dinámicamente esta cadena. En el caso de una cadena asignada, el controlador es responsable de liberar la cadena que se debe hacer después de que WmiSystemControl devuelva. Si el controlador no tiene un recurso MOF asociado, puede dejar MofResourceName sin cambios.

[out] Pdo

Puntero al objeto de dispositivo físico (PDO) pasado a la rutina AddDevice del controlador. Si se establece WMIREG_FLAG_INSTANCE_PDO, WMI usa la ruta de acceso de la instancia de dispositivo de este PDO como base a partir de la cual se generan nombres de instancia estáticos. Si WMIREG_FLAG_INSTANCE_PDO está claro, WMI omite Pdo.

Valor devuelto

DpWmiQueryReginfo siempre devuelve STATUS_SUCCESS.

Comentarios

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

WMI envía el IRP después de que un controlador llame a IoWMIRegistrationControl con WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER o WMIREG_ACTION_UPDATE. WMI controla de forma transparente las diferencias entre IRP_MN_REGINFO y IRP_MN_REGINFO_EX en nombre del controlador.

WMI no envía una solicitud de IRP_MN_REGINFO o IRP_MN_REGINFO_EX después de que un controlador llame a IoWMIRegistrationControl con WMIREG_ACTION_DEREGISTER, ya que WMI no requiere más información del controlador. Normalmente, un controlador anula el registro de sus bloques en respuesta a una solicitud de IRP_MN_REMOVE_DEVICE .

El controlador proporciona información de registro nueva o actualizada sobre bloques individuales, o indica los bloques que se van a quitar, en la estructura WMILIB_CONTEXT pasa a WmiSystemControl. Después de la llamada inicial, que establece la ruta de acceso del registro del controlador y el nombre del recurso MOF, la rutina DpWmiQueryReginfo de un controlador puede cambiar las marcas comunes a todos los bloques de un controlador, proporcionar una cadena de nombre base diferente que se usa para generar nombres de instancia o cambiar la base para los nombres de instancia de una cadena a la ruta de acceso de la instancia de dispositivo del PDO.

El controlador no debe devolver STATUS_PENDING ni bloquear la solicitud. El controlador no debe completar la solicitud llamando a WmiCompleteRequest desde su rutina DpWmiQueryReginfo o llamando a IoCompleteRequest después de que WmiSystemControl devuelva.

Esta rutina puede ser paginable.

Para obtener más información sobre cómo implementar esta rutina, vea Llamar a WmiSystemControl para controlar irP de WMI.