Fonction PoRequestPowerIrp (wdm.h)

Article
08/08/2023

La routine PoRequestPowerIrp alloue un IRP d’alimentation et l’envoie au pilote supérieur de la pile d’appareils pour l’appareil spécifié.

Syntaxe

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

Paramètres

[in] DeviceObject

Pointeur vers le DEVICE_OBJECT cible pour l’IRP. Dans Windows 2000 et versions ultérieures de Windows, ce paramètre peut pointer vers un objet d’appareil physique (PDO) ou un objet d’appareil fonctionnel (FDO). Dans Windows 98/Me, ce paramètre doit pointer vers l’AOP de l’appareil sous-jacent.

[in] MinorFunction

Spécifie l’un des codes IRP d’alimentation mineurs suivants : IRP_MN_QUERY_POWER, IRP_MN_SET_POWER ou IRP_MN_WAIT_WAKE.

[in] PowerState

Spécifie une valeur POWER_STATE à passer dans l’IRP. Pour IRP_MN_SET_POWER et IRP_MN_QUERY_POWER, spécifiez le nouvel état d’alimentation de l’appareil demandé. Les valeurs possibles sont DEVICE_POWER_STATE valeurs.

Pour IRP_MN_WAIT_WAKE, spécifiez l’état d’alimentation du système le plus bas (le moins alimenté) à partir duquel l’appareil doit être autorisé à sortir du système. Les valeurs possibles sont SYSTEM_POWER_STATE valeurs.

[in, optional] CompletionFunction

Pointeur vers la routine de rappel PowerCompletion de l’appelant. Le gestionnaire d’E/S appelle cette routine une fois l’IRP terminée. Ce paramètre est facultatif et peut être défini sur NULL si aucune routine de rappel PowerCompletion n’est nécessaire.

[in, optional] Context

Pointeur vers un contexte fourni par l’appelant à passer au rappel PowerCompletion . Lorsque l’appelant demande un IRP set-power d’appareil en réponse à un IRP set-power du système, Context doit contenir l’IRP set-power du système qui a déclenché la demande.

[out] Irp

Pointeur vers une variable fournie par l’appelant dans laquelle PoRequestPowerIrp retourne un pointeur vers l’IRP qu’il alloue. Spécifiez une valeur pour Irp uniquement si le paramètre MinorFunction est défini sur IRP_MN_WAIT_WAKE. Sinon, ce paramètre doit toujours avoir la valeur NULL , car l’IRP peut être terminé avant le retour de PoRequestPowerIrp , ce qui entraîne le pointage de ce paramètre vers la mémoire qui a déjà été ignorée.

Valeur retournée

PoRequestPowerIrp retourne l’un des éléments suivants :

Code de retour	Description
STATUS_PENDING	L’IRP a été envoyé.
STATUS_INSUFFICIENT_RESOURCES	La routine n’a pas pu allouer l’IRP.
STATUS_INVALID_PARAMETER_2	MinorFunction ne signifie pas un code IRP d’alimentation mineure valide.

Remarques

Un propriétaire de stratégie d’alimentation de l’appareil appelle cette routine pour envoyer un IRP d’attente/veille, une requête ou une commande d’alimentation.

Un pilote appelle PoRequestPowerIrp( et non IoAllocateIrp) pour allouer et envoyer un IRP d’alimentation qui a un code IRP mineur IRP_MN_SET_POWER, IRP_MN_QUERY_POWER ou IRP_MN_WAIT_WAKE. (Un pilote doit appeler IoAllocateIrp pour envoyer un IRP d’alimentation avec un code IRP mineur IRP_MN_POWER_SEQUENCE.)

Si PoRequestPowerIrp renvoie une valeur status de STATUS_PENDING, la routine a correctement alloué un IRP d’alimentation de l’appareil et l’a envoyé en haut de la pile de l’appareil pour l’appareil. Une fois que le pilote de bus et tous les autres pilotes ont terminé l’IRP, et que le gestionnaire d’E/S a appelé toutes les routines IoCompletion définies par les pilotes lorsqu’ils transmettaient l’IRP dans la pile d’appareils, le gestionnaire d’E/S appelle la routine PowerCompletion et passe à cette routine la valeur de contexte spécifiée. Si PoRequestPowerIrp retourne une status autre que STATUS_PENDING, la routine n’a pas envoyé d’IRP d’alimentation de l’appareil et la routine PowerCompletion n’est pas appelée.

La routine PowerCompletion effectue toutes les tâches supplémentaires requises par l’expéditeur de l’IRP une fois que tous les autres pilotes ont terminé l’IRP. Il n’a pas besoin de libérer l’IRP ; le gestionnaire d’alimentation le fait. Dans Windows 2000 et versions ultérieures de Windows, la routine PowerCompletion peut être appelée dans IRQL = PASSIVE_LEVEL ou IRQL = DISPATCH_LEVEL. Dans Windows 98/Me, la routine PowerCompletion est toujours appelée dans IRQL = PASSIVE_LEVEL, et les pilotes doivent effectuer les IIP à IRQL = PASSIVE_LEVEL.

Un propriétaire de stratégie d’alimentation de l’appareil appelle PoRequestPowerIrp pour envoyer une IRP de requête ou de puissance d’alimentation d’appareil lorsqu’il reçoit un IRP de requête système ou de puissance définie. Le pilote doit définir une routine IoCompletion dans l’IRP système et passer l’IRP système au pilote inférieur suivant. La routine IoCompletion appelle PoRequestPowerIrp pour envoyer l’IRP de l’appareil, en passant l’IRP système dans le paramètre Context . Le paramètre Context est ensuite passé à la routine PowerCompletion pour l’IRP de l’appareil. Dans la routine PowerCompletion , le pilote peut effectuer l’IRP système. Pour plus d’informations, consultez Envoi de IRP_MN_QUERY_POWER ou de IRP_MN_SET_POWER pour device Power States et Wait/Wake Callback Routines.

Les pilotes peuvent utiliser l’Irp retourné pour annuler un IRP IRP_MN_WAIT_WAKE . Les pilotes qui demandent d’autres types d’IRP d’alimentation doivent passer la valeur NULL pour ce paramètre.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),MarkDevicePower(wdm),PowerDownFail(wdm),PowerUpFail(wdm), RequestedPowerIrp(wdm)