Funzione PoRequestPowerIrp (wdm.h)

Articolo
03/08/2023

La routine PoRequestPowerIrp alloca un'IRP di alimentazione e la invia al driver superiore nello stack di dispositivi per il dispositivo specificato.

Sintassi

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
);

Parametri

[in] DeviceObject

Puntatore al DEVICE_OBJECT di destinazione per l'IRP. In Windows 2000 e versioni successive di Windows questo parametro può puntare a un oggetto dispositivo fisico (PDO) o a un oggetto dispositivo funzionale (FDO). In Windows 98/Me questo parametro deve puntare al PDO del dispositivo sottostante.

[in] MinorFunction

Specifica uno dei codici IRP di alimentazione secondari seguenti: IRP_MN_QUERY_POWER, IRP_MN_SET_POWER o IRP_MN_WAIT_WAKE.

[in] PowerState

Specifica un valore POWER_STATE da passare all'IRP. Per IRP_MN_SET_POWER e IRP_MN_QUERY_POWER specificare lo stato di alimentazione del nuovo dispositivo richiesto. I valori possibili sono DEVICE_POWER_STATE valori.

Per IRP_MN_WAIT_WAKE, specificare lo stato di alimentazione del sistema minimo (meno alimentato) da cui il dispositivo deve essere autorizzato a riattivare il sistema. I valori possibili sono SYSTEM_POWER_STATE valori.

[in, optional] CompletionFunction

Puntatore alla routine di callback di PowerCompletion del chiamante. Il gestore di I/O chiama questa routine al termine dell'IRP. Questo parametro è facoltativo e può essere impostato su NULL se non è necessaria alcuna routine di callback di PowerCompletion .

[in, optional] Context

Puntatore a un contesto fornito dal chiamante da passare al callback di PowerCompletion . Quando il chiamante richiede un'IRP di set-power del dispositivo in risposta a un'IRP di set-power del sistema, Il contesto deve contenere l'IRP del set di sistema che ha attivato la richiesta.

[out] Irp

Puntatore a una variabile fornita dal chiamante in cui PoRequestPowerIrp restituisce un puntatore all'IRP allocato. Specificare un valore per Irp solo se il parametro MinorFunction è impostato su IRP_MN_WAIT_WAKE. In caso contrario, questo parametro deve essere sempre NULL perché l'IRP potrebbe essere completato prima che PoRequestPowerIrp restituisca, causando che questo parametro punti alla memoria che è già stato rimosso.

Valore restituito

PoRequestPowerIrp restituisce uno dei seguenti:

Codice restituito	Descrizione
STATUS_PENDING	L'IRP è stato inviato.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare la routine all'IRP.
STATUS_INVALID_PARAMETER_2	MinorFunction non firma un codice IRP di alimentazione secondaria valido.

Commenti

Un proprietario di criteri di alimentazione del dispositivo chiama questa routine per inviare un'attività di attesa/riattivazione, una query o un'IRP di alimentazione impostata.

Un driver chiama PoRequestPowerIrp, non IoAllocateIrp, per allocare e inviare un'IRP di alimentazione con codice IRP secondario IRP_MN_SET_POWER, IRP_MN_QUERY_POWER o IRP_MN_WAIT_WAKE. Un driver deve chiamare IoAllocateIrp per inviare un'IRP di alimentazione con codice IRP secondario IRP_MN_POWER_SEQUENCE.

Se PoRequestPowerIrp restituisce un valore di stato di STATUS_PENDING, la routine ha assegnato correttamente un'IRP di alimentazione del dispositivo e l'ha inviata all'inizio dello stack di dispositivi per il dispositivo. Dopo che il driver del bus e tutti gli altri driver hanno completato l'IRP e il gestore I/O ha chiamato tutte le routine IoCompletion impostate dai driver quando hanno passato l'IRP verso il basso lo stack di dispositivi, il gestore I/O chiama la routine PowerCompletion e passa a questa routine il valore di contesto specificato. Se PoRequestPowerIrp restituisce uno stato diverso da STATUS_PENDING, la routine non ha inviato un'IRP di alimentazione del dispositivo e la routine PowerCompletion non viene chiamata.

La routine PowerCompletion esegue tutte le attività aggiuntive richieste dal mittente dell'IRP dopo che tutti gli altri driver hanno completato l'IRP. Non è necessario liberare l'IRP; il risparmio energia lo fa. In Windows 2000 e versioni successive di Windows, la routine PowerCompletion può essere chiamata in IRQL = PASSIVE_LEVEL o IRQL = DISPATCH_LEVEL. In Windows 98/Me, la routine PowerCompletion viene sempre chiamata in IRQL = PASSIVE_LEVEL e i driver devono completare i criteri di integrazione in IRQL = PASSIVE_LEVEL.

Un proprietario dei criteri di alimentazione del dispositivo chiama PoRequestPowerIrp per inviare una query del dispositivo o un'IRP di set-power quando riceve una query di sistema o un'IRP di set-power. Il driver deve impostare una routine IoCompletion nell'IRP di sistema e passare l'IRP di sistema al driver inferiore successivo. La routine IoCompletion chiama PoRequestPowerIrp per inviare l'IRP del dispositivo, passando il sistema IRP nel parametro Context . Il parametro Context viene successivamente passato alla routine PowerCompletion per l'IRP del dispositivo. Nella routine PowerCompletion il driver può completare l'IRP di sistema. Per altre informazioni, vedere Invio di IRP_MN_QUERY_POWER o IRP_MN_SET_POWER per Gli stati di alimentazione del dispositivo e le routine di callback di attesa/riattivazione.

I driver possono usare l'Irp restituito per annullare un IRP_MN_WAIT_WAKE IRP. I driver che richiedono altri tipi di irp di alimentazione devono passare NULL per questo parametro.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 2000.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm)