IRP_MN_CHANGE_SINGLE_INSTANCE

Artículo
06/15/2023

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_CHANGE_SINGLE_INSTANCE , WMI a su vez llama a la rutina DpWmiSetDataBlock del controlador.

Código principal

IRP_MJ_SYSTEM_CONTROL

Cuándo se envió

WMI envía este IRP para cambiar todos los elementos de datos de una sola instancia de un bloque de datos.

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 asociado a la instancia que se va a cambiar.

Parameters.WMI.BufferSize indica el tamaño del búfer no paginado en Parameters.WMI.Buffer.

Parameters.WMI.Buffer apunta a una estructura de WNODE_SINGLE_INSTANCE que identifica la instancia y especifica nuevos valores de datos.

Parámetros de salida

Ninguno.

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_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

Si se ejecuta correctamente, el controlador establece Irp-IoStatus.Information> en cero.

Operación

Si un controlador controla los IRP de WMI llamando a WmiSystemControl, esa rutina llama a la rutina DpWmiSetDataBlock del controlador o devuelve STATUS_WMI_READ_ONLY si el controlador no define la rutina.

Si un controlador controla una solicitud de IRP_MN_CHANGE_SINGLE_INSTANCE , solo lo hace si el puntero del objeto de dispositivo en Parameters.WMI.ProviderId coincide con el puntero pasado por el controlador en su llamada a IoWMIRegistrationControl. De lo contrario, el controlador debe reenviar la solicitud al controlador inferior siguiente.

Si el controlador controla la solicitud, primero debe comprobar el GUID en Parameters.WMI.DataPath para determinar si identifica un bloque de datos 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, debe comprobar la estructura de WNODE_SINGLE_INSTANCE recibida 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_SINGLE_INSTANCE de entrada. OffsetInstanceName es el desplazamiento en bytes desde el principio de la estructura hasta una longitud de tamaño USHORT 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.

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:

Para los nombres estáticos, compruebe que el miembro InstanceIndex de la estructura de WNODE_SINGLE_INSTANCE 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 los miembros DataBlockOffset y SizeDataBlock de la estructura de WNODE_SINGLE_INSTANCE describen un bloque de datos de tamaño válido, incluido cualquier relleno que exista entre los elementos de datos y que el contenido del búfer sea válido para el bloque de datos.
Compruebe que el bloque de datos especificado es uno para el que el controlador permite modificaciones iniciadas por el autor de la llamada. En otras palabras, el controlador no debe permitir modificaciones en bloques de datos destinados a ser de solo lectura.

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.

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

Si el controlador localiza la instancia y puede controlar la solicitud, establece los elementos de datos grabables en la instancia en los valores de la estructura WNODE_SINGLE_INSTANCE , dejando los elementos de solo lectura sin cambios. Si todo el bloque de datos es de solo lectura, el controlador debe producir un error en el IRP y devolver STATUS_WMI_READ_ONLY.

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