IRP_MN_EXECUTE_METHOD

Artículo
06/15/2023

Todos los controladores que admiten métodos dentro de bloques de datos 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_EXECUTE_METHOD , WMI a su vez llama a la rutina DpWmiExecuteMethod del controlador.

Código principal

IRP_MJ_SYSTEM_CONTROL

Cuándo se envió

WMI envía este IRP para ejecutar un método asociado a un bloque de datos.

WMI envía este IRP en IRQL = PASSIVE_LEVEL en un contexto de subproceso arbitrario.

WMI enviará 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 de IRP_MN_QUERY_SINGLE_INSTANCE para el mismo bloque de datos cuyo método se está ejecutando.

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 el IRP.

Parameters.WMI.DataPath apunta a un GUID que identifica el bloque de datos asociado al método que se va a ejecutar.

Parameters.WMI.BufferSize indica el tamaño del búfer no paginado en Parameters.WMI.Buffer que debe ser >= sizeof(WNODE_METHOD_ITEM) más el tamaño de los datos de salida del método.

Parameters.WMI.Buffer apunta a una estructura de WNODE_METHOD_ITEM en la que MethodID indica el identificador del método que se va a ejecutar y DataBlockOffset indica el desplazamiento en bytes desde el principio de la estructura hasta el primer byte de datos de entrada, si existe. Parameters.WMI.Buffer-> SizeDataBlock indica el tamaño en bytes del WNODE_METHOD_ITEM de entrada, incluidos los datos de entrada, o cero si no hay ninguna entrada.

Parámetros de salida

Si el controlador controla los IRP de WMI llamando a WmiSystemControl, WMI rellena el WNODE_METHOD_ITEM con los datos devueltos por la rutina DpWmiExecuteMethod del controlador.

De lo contrario, el controlador rellena la estructura de WNODE_METHOD_ITEM a la que Parameters.WMI.Buffer apunta de la siguiente manera:

Novedades WnodeHeader.BufferSize con el tamaño del WNODE_METHOD_ITEM de salida, incluidos los datos de salida.
Novedades SizeDataBlock con el tamaño de los datos de salida o cero si no hay datos de salida.
Comprueba Parameters.WMI.Buffersize para determinar si el búfer es lo suficientemente grande como para recibir el WNODE_METHOD_ITEM de salida, incluidos los datos de salida. Si el búfer no es lo suficientemente grande, el controlador rellena el tamaño necesario en una estructura de WNODE_TOO_SMALL a la que apunta 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.
Escribe los datos de salida, si los hay, sobre los datos de entrada a partir de DataBlockOffset. El controlador no debe cambiar el valor de entrada de DataBlockOffset.

Bloque de estado de entrada/salida

Si el controlador controla el IRP llamando 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

STATUS_WMI_ITEMID_NOT_FOUND

Si se ejecuta correctamente, un controlador establece Irp-IoStatus.Information> en el número de bytes escritos en el búfer en Parameters.WMI.Buffer.

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 los IRP de WMI llamando a WmiSystemControl, esa rutina llama a la rutina DpWmiExecuteMethod del controlador o devuelve STATUS_INVALID_DEVICE_REQUEST si el controlador no define la rutina.

Si un controlador controla una solicitud de IRP_MN_EXECUTE_METHOD , solo debe hacerlo si Parameters.WMI.ProviderId apunta al mismo objeto de dispositivo que el puntero que el controlador pasó a IoWMIRegistrationControl. De lo contrario, el controlador debe reenviar la solicitud al controlador inferior siguiente.

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_METHOD_ITEM se encuentra 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 el miembro MethodId de la estructura de WNODE_METHOD_ITEM se encuentra dentro del intervalo de identificadores de método admitidos por el controlador para el bloque de datos y que el autor de la llamada puede ejecutar el método.
Compruebe que los miembros DataBlockOffset y SizeDataBlock de la estructura WNODE_METHOD_ITEM describen un búfer lo suficientemente grande como para contener los parámetros del método especificado y que los parámetros son válidos para el método.
Compruebe que Parameters.WMI.Buffersize especifica un búfer lo suficientemente grande como para recibir la estructura de WNODE_METHOD_ITEM después de actualizarla con los datos de salida.

No supongamos que el contexto del subproceso es el de la aplicación en modo de usuario iniciado: es posible que un controlador de nivel superior lo haya cambiado.

Antes de controlar la solicitud, el controlador debe determinar si Parameters.WMI.DataPath apunta a un GUID admitido por el controlador. Si no es así, el controlador debe producir un error en el IRP y devolver STATUS_WMI_GUID_NOT_FOUND.

Si el controlador admite el bloque de datos, comprueba el WNODE_METHOD_ITEM de entrada en Parameters.WMI.Buffer para el nombre de 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_METHOD_ITEM 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), incluida la terminación null si está presente, seguida de la cadena de nombre de instancia en Unicode.

Si el controlador no encuentra la instancia especificada, debe producir un error en el 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 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.

A continuación, el controlador comprueba el identificador del método en el WNODE_METHOD_ITEM de entrada para determinar si es un método válido para ese bloque de datos. Si no es así, el controlador produce un error en el IRP y devuelve STATUS_WMI_ITEMID_NOT_FOUND.

Si el método genera la salida, el controlador debe comprobar el tamaño del búfer de salida en Parameters.WMI.BufferSize antes de realizar cualquier operación que pueda tener efectos secundarios o que no se deben realizar dos veces. Por ejemplo, si un método devuelve los valores de un grupo de contadores y, a continuación, restablece los contadores, el controlador debe comprobar el tamaño del búfer (y producir un error en el IRP si el búfer es demasiado pequeño) antes de restablecer los contadores. Esto garantiza que WMI pueda volver a enviar la solicitud de forma segura con un búfer mayor.

Si la instancia y el identificador de método son válidos y el búfer es adecuado en tamaño, el controlador ejecuta el método . Si SizeDataBlock en el WNODE_METHOD_ITEM de entrada no es cero, el controlador usa los datos que comienzan en DataBlockOffset como entrada para el método .

Si el método genera la salida, el controlador escribe los datos de salida en el búfer a partir de DataBlockOffset y establece SizeDataBlock en el WNODE_METHOD_ITEM de salida en el número de bytes de datos de salida. Si el método no tiene datos de salida, el controlador establece SizeDataBlock en cero. El controlador no debe cambiar el valor de entrada de DataBlockOffset.

Si la instancia es válida, pero el controlador no puede controlar la solicitud, puede devolver cualquier estado de error adecuado.