IRP_MN_QUERY_SINGLE_INSTANCE
Todos los controladores que admiten WMI deben controlar este IRP. Un controlador puede controlar los IRP de WMI llamando a WmiSystemControl o controlando el PROPIO IRP, como se describe en Control de solicitudes WMI.
Si un controlador llama a WmiSystemControl para controlar una solicitud de IRP_MN_QUERY_SINGLE_INSTANCE , WMI a su vez llama a la rutina DpWmiQueryDataBlock del controlador.
Código principal
Cuándo se envió
WMI envía este IRP para consultar una sola instancia de un bloque de datos determinado.
WMI envía un IRP_MN_QUERY_SINGLE_INSTANCE antes de enviar un IRP_MN_EXECUTE_METHOD. Si un controlador admite IRP_MN_EXECUTE_METHOD, debe tener un controlador IRP_MN_QUERY_SINGLE_INSTANCE para el mismo bloque de datos cuyo método se está ejecutando.
WMI envía este IRP en IRQL = PASSIVE_LEVEL en un contexto de subproceso arbitrario.
Parámetros de entrada
Parameters.WMI.ProviderId apunta al objeto de dispositivo del controlador que debe responder a la solicitud. Este puntero se encuentra en la ubicación de la pila de E/S del controlador en irP.
Parameters.WMI.DataPath apunta a un GUID que identifica el bloque de datos que se va a consultar.
Parameters.WMI.BufferSize indica el tamaño máximo del búfer no paginado en Parameters.WMI.Buffer, que apunta a una estructura WNODE_SINGLE_INSTANCE que identifica la instancia que se va a consultar.
Parámetros de salida
Si el controlador controla los IRP de WMI mediante una llamada a WmiSystemControl, WMI rellena una estructura de WNODE_SINGLE_INSTANCE con los datos proporcionados por la rutina DpWmiQueryDataBlock del controlador.
De lo contrario, el controlador rellena la estructura de WNODE_SINGLE_INSTANCE en Parameters.WMI.Buffer como se indica a continuación:
Novedades WnodeHeader.BufferSize con el tamaño, en bytes, de la estructura de WNODE_SINGLE_INSTANCE de salida, incluidos los datos de instancia. Este valor debe incluir la longitud del nombre de instancia (rellenado de forma que los datos de instancia comiencen en un límite de palabra cuádruple), incluso si la clase que se consulta nombres de instancia estática registrados y el escritor de controladores no proporciona explícitamente el nombre al atender este IRP.
Establece SizeDataBlock en el tamaño, en bytes, de los datos de instancia. Si los nombres de instancia estáticos están en uso, este valor no debe incluir el tamaño del nombre de instancia.
Escribe los datos de instancia en Parameters.WMI.Buffer a partir de DataBlockOffset. El controlador no debe cambiar el valor de entrada de DataBlockOffset.
Si el búfer de Parameters.WMI.Buffer es demasiado pequeño para recibir todos los datos, el controlador rellena el tamaño necesario en una estructura de WNODE_TOO_SMALL en Parameters.WMI.Buffer. Si el búfer es menor que sizeof(WNODE_TOO_SMALL), el controlador produce un error en el IRP y devuelve STATUS_BUFFER_TOO_SMALL.
Bloque de estado de entrada/salida
Si el controlador controla el IRP mediante una llamada a WmiSystemControl, WMI establece Irp-IoStatus.Status> e Irp-IoStatus.Information> en el bloque de estado de E/S.
De lo contrario, el controlador establece Irp-IoStatus.Status> en STATUS_SUCCESS o en un estado de error adecuado, como el siguiente:
STATUS_BUFFER_TOO_SMALL
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_INSTANCE_NOT_FOUND
Si se ejecuta correctamente, un controlador establece Irp-IoStatus.Information> en el valor especificado en WnodeHeader.BufferSize. Este valor incluye la longitud del nombre de la instancia estática.
Operación
Un controlador puede controlar los IRP de WMI llamando a WmiSystemControl o controlando el PROPIO IRP, como se describe en Control de solicitudes WMI.
Si un controlador controla irPs de WMI llamando a WmiSystemControl, WmiSystemControl llama a la rutina DpWmiQueryDataBlock del controlador.
Si un controlador controla una solicitud de IRP_MN_QUERY_SINGLE_INSTANCE , solo debe hacerlo si Parameters.WMI.ProviderId apunta al mismo objeto de dispositivo que el puntero que el controlador pasó en su llamada a IoWMIRegistrationControl. De lo contrario, el controlador debe reenviar la solicitud al siguiente controlador inferior de la pila de dispositivos.
Antes de controlar la solicitud, el controlador debe determinar si Parameters.WMI.DataPath apunta a un GUID que admite el controlador. Si no es así, el controlador debe producir un error en el IRP y devolver STATUS_WMI_GUID_NOT_FOUND.
El controlador es responsable de validar todos los valores de entrada. En concreto, el controlador debe hacer lo siguiente si controla la propia solicitud IRP:
En el caso de los nombres estáticos, compruebe que el miembro InstanceIndex de la estructura WNODE_SINGLE_INSTANCE está dentro del intervalo de índices de instancia admitidos por el controlador para el bloque de datos.
Para los nombres dinámicos, compruebe que la cadena de nombre de instancia identifica una instancia de bloque de datos compatible con el controlador.
Compruebe que Parameters.WMI.BufferSize especifica un búfer lo suficientemente grande como para recibir todos los datos que devolverá el controlador.
Si el controlador admite el bloque de datos, comprueba la entrada WNODE_SINGLE_INSTANCE en Parameters.WMI.Buffer para el nombre de la instancia, como se indica a continuación:
Si WNODE_FLAG_STATIC_INSTANCE_NAMES se establece en WnodeHeader.Flags, el controlador usa InstanceIndex como índice en la lista de nombres de instancia estáticos del controlador para ese bloque. WMI obtiene el índice de los datos de registro proporcionados por el controlador cuando registró el bloque.
Si WNODE_FLAG_STATIC_INSTANCE_NAMES está desactivada en WnodeHeader.Flags, el controlador usa el desplazamiento en OffsetInstanceName para buscar la cadena de nombre de instancia en el WNODE_SINGLE_INSTANCE de entrada. OffsetInstanceName es el desplazamiento, en bytes, desde el principio de la estructura a un USHORT, que es la longitud de la cadena de nombre de instancia en bytes (no caracteres), incluido el valor NULL de terminación si está presente, seguido de la cadena de nombre de instancia en Unicode.
Si el controlador no encuentra la instancia especificada, debe producir un error en irP y devolver STATUS_WMI_INSTANCE_NOT_FOUND. En el caso de una instancia con un nombre de instancia dinámico, este estado indica que el controlador no admite la instancia. Por lo tanto, WMI puede seguir consultando a otros proveedores de datos y devolver un error adecuado al consumidor de datos si otro proveedor encuentra la instancia, pero no puede controlar la solicitud por algún otro motivo.
Si el controlador localiza la instancia y puede controlar la solicitud, rellena la estructura de WNODE_SINGLE_INSTANCE en Parameters.WMI.Buffer con datos para la instancia.
Si la instancia es válida, pero el controlador no puede controlar la solicitud, puede devolver cualquier estado de error adecuado.
Requisitos
Encabezado |
Wdm.h (incluya Wdm.h, Ntddk.h o Ntifs.h) |