IRP_MN_CHANGE_SINGLE_ITEM
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_ITEM , WMI a su vez llama a la rutina DpWmiSetDataItem del controlador.
Código principal
Cuándo se envió
WMI envía este IRP para cambiar un único elemento de datos en 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 que se va a establecer.
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_ITEM que identifica la instancia del bloque de datos, el identificador del elemento que se va a establecer y un nuevo valor de datos.
Parámetros de salida
Ninguno.
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_WMI_INSTANCE_NOT_FOUND
STATUS_WMI_ITEMID_NOT_FOUND
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_READ_ONLY
STATUS_WMI_SET_FAILURE
Si se ejecuta correctamente, un 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 DpWmiSetDataItem del controlador o devuelve STATUS_WMI_READ_ONLY si el controlador no define la rutina.
Si un controlador controla IRP_MN_CHANGE_SINGLE_ITEM solicitudes, 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.
No implemente la compatibilidad con IRP_MN_CHANGE_SINGLE_ITEM a menos que esté seguro de que un componente de modo de usuario proporcionado por el sistema requiere esta funcionalidad.
Antes de controlar una 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.
Si el controlador admite el bloque de datos, debe comprobar la estructura WNODE_SINGLE_ITEM de entrada a la que Parameters.WMI.Buffer apunta 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 la estructura de WNODE_SINGLE_ITEM 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). Esta longitud incluye el terminador NULL si está presente, seguido 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:
En el caso de los nombres estáticos, compruebe que el miembro InstanceIndex de la estructura WNODE_SINGLE_ITEM 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 el miembro ItemId de la estructura WNODE_SINGLE_ITEM está dentro del intervalo de identificadores de elemento admitidos por el controlador para el bloque de datos.
Compruebe que los miembros DataBlockOffset y SizeDataItem de la estructura WNODE_SINGLE_ITEM describen un bloque de datos de tamaño válido y que el contenido del búfer es válido para el elemento de datos.
Compruebe que el elemento 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 los elementos de datos destinados a ser de solo lectura.
No asuma que el contexto del subproceso es el de la aplicación en modo de usuario que inicia: es posible que un controlador de nivel superior lo haya cambiado.
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, establece el elemento de datos de la instancia en el valor de la WNODE_SINGLE_ITEM. Si el elemento de datos es de solo lectura, el controlador deja el elemento sin cambios, produce un error en el IRP y devuelve 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.
Requisitos
Encabezado |
Wdm.h (incluya Wdm.h, Ntddk.h o Ntifs.h) |