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

Artículo
08/08/2023

La rutina DpWmiExecuteMethod ejecuta un método asociado a un bloque de datos. Esta rutina es opcional.

Sintaxis

WMI_EXECUTE_METHOD_CALLBACK WmiExecuteMethodCallback;

NTSTATUS WmiExecuteMethodCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG MethodId,
  [in]      ULONG InBufferSize,
  [in]      ULONG OutBufferSize,
  [in, out] PUCHAR Buffer
)
{...}

Parámetros

[in] DeviceObject

Puntero a la estructura de DEVICE_OBJECT WDM del controlador.

[in] Irp

Puntero al IRP.

[in] GuidIndex

Especifica el bloque de datos proporcionando un índice de base cero en la lista de GUID que el controlador proporcionó en la estructura de WMILIB_CONTEXT que pasó a WmiSystemControl.

[in] InstanceIndex

Si el bloque especificado por GuidIndex tiene varias instancias, InstanceIndex especifica un valor de índice de base cero que identifica la instancia.

[in] MethodId

Especifica el identificador del método que se va a ejecutar. El controlador define el identificador de método como un elemento de un bloque de datos.

[in] InBufferSize

Indica el tamaño en bytes de los datos de entrada. Si no hay datos de entrada, InBufferSize es cero.

[in] OutBufferSize

Indica el número de bytes disponibles en el búfer para los datos de salida.

[in, out] Buffer

Puntero a un búfer que contiene los datos de entrada, si los hay, y recibe los datos de salida, si los hay, para el método . Si el búfer es demasiado pequeño para recibir todos los datos de salida, el controlador devuelve STATUS_BUFFER_TOO_SMALL y llama a WmiCompleteRequest con el tamaño necesario.

Valor devuelto

DpWmiExecuteMethod devuelve STATUS_SUCCESS o un código de error adecuado, como el siguiente:

Comentarios

WMI llama a la rutina DpWmiExecuteMethod de un controlador después de que el controlador llame a WmiSystemControl en respuesta a una solicitud de IRP_MN_EXECUTE_METHOD .

Si un controlador implementa una rutina DpWmiExecuteMethod , el controlador debe colocar la dirección de la rutina en el miembro ExecuteWmiMethod de la estructura WMILIB_CONTEXT que pasa a WmiSystemControl. Si un controlador no implementa una rutina DpWmiExecuteMethod , debe establecer ExecuteWmiMethod en NULL. En este último caso, WMI devuelve STATUS_INVALID_DEVICE_REQUEST al autor de la llamada en respuesta a cualquier solicitud de IRP_MN_EXECUTE_METHOD .

El controlador es responsable de validar todos los argumentos de entrada. En concreto, el controlador debe hacer lo siguiente:

Compruebe que el valor guidIndex está entre cero y GuidCount-1, en función del miembro GuidCount de la estructura WMILIB_CONTEXT .
Compruebe que el controlador no ha marcado el bloque de datos especificado para su eliminación. Si el controlador especificó recientemente la marca WMIREG_FLAG_REMOVE_GUID en una estructura WMIGUIDREGINFO contenida en una estructura de WMILIB_CONTEXT , es posible que llegue una solicitud adicional antes de que se produzca la eliminación.
Compruebe que el valor instanceIndex está dentro del intervalo de índices de instancia admitidos por el controlador para el bloque de datos.
Compruebe que el identificador de método proporcionado por MethodId es un identificador válido para el bloque de datos especificado y que el autor de la llamada puede ejecutar el método.
Compruebe que Buffer e InBufferSize describen un búfer lo suficientemente grande como para contener los parámetros de entrada del método especificado, incluido el relleno si es necesario, y compruebe que los parámetros de entrada son válidos.
Compruebe que Buffer y OutBufferSize describen un búfer lo suficientemente grande como para recibir los datos de salida del método especificado, incluido el relleno si es necesario.

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 método especificado realiza una operación que provoca la pérdida de datos, como capturar y restablecer el contenido de un conjunto de contadores, el controlador debe validar el tamaño del búfer de salida antes de realizar la operación. De este modo, el controlador puede devolver STATUS_BUFFER_TOO_SMALL y permitir que el autor de la llamada vuelva a enviar la solicitud con un búfer mayor, sin restablecer prematuramente los contadores.

Después de ejecutar el método y escribir los datos de salida en el búfer, el controlador llama a WmiCompleteRequest para completar la solicitud.

Esta rutina puede ser paginable.

Para obtener más información sobre la implementación de esta rutina, vea Llamar a WmiSystemControl para controlar los IRP de WMI.