Fonction PoRequestPowerIrp (wdm.h)
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 |
|---|---|
|
L’IRP a été envoyé. |
|
La routine n’a pas pu allouer l’IRP. |
|
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) |