Función PoRequestPowerIrp (wdm.h)

Artículo
02/27/2024

La rutina PoRequestPowerIrp asigna un IRP de energía y lo envía al controlador superior de la pila de dispositivos para el dispositivo especificado.

Sintaxis

NTSTATUS PoRequestPowerIrp(
  [in]           PDEVICE_OBJECT          DeviceObject,
  [in]           UCHAR                   MinorFunction,
  [in]           POWER_STATE             PowerState,
  [in, optional] PREQUEST_POWER_COMPLETE CompletionFunction,
  [in, optional] __drv_aliasesMem PVOID  Context,
  [out]          PIRP                    *Irp
);

Parámetros

[in] DeviceObject

Puntero al DEVICE_OBJECT de destino del IRP. En Windows 2000 y versiones posteriores de Windows, este parámetro puede apuntar a un objeto de dispositivo físico (PDO) o a un objeto de dispositivo funcional (FDO). En Windows 98/Me, este parámetro debe apuntar al PDO del dispositivo subyacente.

[in] MinorFunction

Especifica uno de los siguientes códigos irP de potencia secundaria: IRP_MN_QUERY_POWER, IRP_MN_SET_POWER o IRP_MN_WAIT_WAKE.

[in] PowerState

Especifica un valor de POWER_STATE que se va a pasar en el IRP. Para IRP_MN_SET_POWER y IRP_MN_QUERY_POWER, especifique el nuevo estado de alimentación del dispositivo solicitado. Los valores posibles son DEVICE_POWER_STATE valores.

Para IRP_MN_WAIT_WAKE, especifique el estado de alimentación del sistema más bajo (menos alimentado) desde el que se debe permitir que el dispositivo despierte el sistema. Los valores posibles son SYSTEM_POWER_STATE valores.

[in, optional] CompletionFunction

Puntero a la rutina de devolución de llamada de PowerCompletion del autor de la llamada. El administrador de E/S llama a esta rutina cuando se haya completado el IRP. Este parámetro es opcional y se puede establecer en NULL si no se necesita ninguna rutina de devolución de llamada de PowerCompletion .

[in, optional] Context

Puntero a un contexto proporcionado por el autor de la llamada que se va a pasar a la devolución de llamada de PowerCompletion . Cuando el autor de la llamada solicita un IRP de alimentación de conjunto de dispositivos en respuesta a un IRP de energía establecida por el sistema, Context debe contener el IRP de set-power del sistema que desencadenó la solicitud.

[out] Irp

Puntero a una variable proporcionada por el autor de la llamada en la que PoRequestPowerIrp devuelve un puntero al IRP que asigna. Especifique un valor para Irp solo si el parámetro MinorFunction está establecido en IRP_MN_WAIT_WAKE. De lo contrario, este parámetro siempre debe ser NULL porque el IRP se puede completar antes de que PoRequestPowerIrp devuelva, lo que hace que este parámetro apunte a la memoria que ya se ha descartado.

Valor devuelto

PoRequestPowerIrp devuelve una de las siguientes opciones:

Código devuelto	Descripción
STATUS_PENDING	Se ha enviado el IRP.
STATUS_INSUFFICIENT_RESOURCES	La rutina no pudo asignar el IRP.
STATUS_INVALID_PARAMETER_2	MinorFunction no significa un código IRP de energía secundaria válido.

Comentarios

Un propietario de la directiva de energía del dispositivo llama a esta rutina para enviar un IRP de espera/reactivación, consulta o set-power.

Un controlador llama a PoRequestPowerIrp (no IoAllocateIrp) para asignar y enviar un IRP de energía que tenga código IRP menor IRP_MN_SET_POWER, IRP_MN_QUERY_POWER o IRP_MN_WAIT_WAKE. (Un controlador debe llamar a IoAllocateIrp para enviar un IRP de alimentación con código IRP secundario IRP_MN_POWER_SEQUENCE).

Si PoRequestPowerIrp devuelve un valor de estado de STATUS_PENDING, la rutina asignó correctamente un IRP de alimentación del dispositivo y lo envió a la parte superior de la pila de dispositivos para el dispositivo. Después de que el controlador de autobús y todos los demás controladores hayan completado el IRP, y el administrador de E/S ha llamado a todas las rutinas de IoCompletion establecidas por los controladores a medida que pasaron el IRP a la pila del dispositivo, el administrador de E/S llama a la rutina PowerCompletion y pasa a esta rutina el valor de Contexto especificado. Si PoRequestPowerIrp devuelve un estado distinto de STATUS_PENDING, la rutina no envió un IRP de alimentación del dispositivo y no se llama a la rutina PowerCompletion .

La rutina PowerCompletion realiza cualquier tarea adicional que requiera el remitente del IRP después de que todos los demás controladores hayan completado el IRP. No necesita liberar el IRP; el administrador de energía lo hace. En Windows 2000 y versiones posteriores de Windows, se puede llamar a la rutina PowerCompletion en IRQL = PASSIVE_LEVEL o IRQL = DISPATCH_LEVEL. En Windows 98/Me, siempre se llama a la rutina PowerCompletion en IRQL = PASSIVE_LEVEL y los controladores deben completar irP en IRQL = PASSIVE_LEVEL.

Un propietario de la directiva de energía de dispositivo llama a PoRequestPowerIrp para enviar una consulta de dispositivo o IRP de set-power cuando recibe una consulta del sistema o IRP de set-power. El controlador debe establecer una rutina de IoCompletion en el IRP del sistema y pasar el IRP del sistema al siguiente controlador inferior. La rutina IoCompletion llama a PoRequestPowerIrp para enviar el IRP del dispositivo, pasando el IRP del sistema en el parámetro Context . El parámetro Context se pasa posteriormente a la rutina PowerCompletion para el IRP del dispositivo. En la rutina PowerCompletion , el controlador puede completar el IRP del sistema. Para obtener más información, consulte Envío de IRP_MN_QUERY_POWER o IRP_MN_SET_POWER para estados de energía del dispositivo y rutinas de devolución de llamada de espera/reactivación.

Los controladores pueden usar irp devuelto para cancelar un IRP de IRP_MN_WAIT_WAKE . Los controladores que solicitan otros tipos de IRP de energía deben pasar NULL para este parámetro.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 2000.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm)