Fonction PoCallDriver (ntifs.h)

Article
02/27/2024

La routine PoCallDriver transmet un IRP d’alimentation au pilote inférieur suivant dans la pile des appareils. (Windows Server 2003, Windows XP et Windows 2000 uniquement.)

Syntaxe

NTSTATUS PoCallDriver(
  [in]      PDEVICE_OBJECT        DeviceObject,
  [in, out] __drv_aliasesMem PIRP Irp
);

Paramètres

[in] DeviceObject

Pointeur vers le DEVICE_OBJECT créé par le pilote vers lequel l’IRP doit être routé.

[in, out] Irp

Pointeur vers un IRP.

Valeur retournée

PoCallDriver retourne STATUS_SUCCESS pour indiquer la réussite. Il retourne STATUS_PENDING s’il a mis en file d’attente l’IRP.

Remarques

À compter de Windows Vista, les pilotes doivent appeler IoCallDriver, et non PoCallDriver pour passer un IRP d’alimentation au pilote inférieur suivant. Toutefois, sur Windows Server 2003, Windows XP et Windows 2000, les pilotes doivent appeler PoCallDriver, et non IoCallDriver pour passer un IRP d’alimentation au pilote inférieur suivant. Sur Windows Server 2003, Windows XP, un Windows 2000, les pilotes doivent également appeler PoStartNextPowerIrp avant d’appeler PoCallDriver.

Un pilote qui nécessite une nouvelle IRP doit appeler PoRequestPowerIrp. Un pilote ne doit pas allouer son propre IRP de puissance.

Lors du passage d’un IRP d’alimentation au pilote inférieur suivant, l’appelant doit utiliser IoSkipCurrentIrpStackLocation ou IoCopyCurrentIrpStackLocationToNext pour définir l’emplacement de la pile IRP, puis appeler PoCallDriver. Utilisez IoCopyCurrentIrpStackLocationToNext si le traitement de l’IRP nécessite la définition d’une routine IoCompletion , ou IoSkipCurrentStackLocation si aucune routine IoCompletion n’est requise.

Lorsqu’un appareil est mis sous tension, ses pilotes doivent définir des routines IoCompletion pour effectuer des tâches de démarrage (initialisation de l’appareil, restauration du contexte, etc.) une fois que le pilote de bus a défini l’appareil à l’état de fonctionnement. Définissez des routines IoCompletion avant d’appeler PoCallDriver.

Lorsqu’un appareil est hors tension, ses pilotes doivent effectuer les tâches de mise hors tension nécessaires avant de passer l’IRP au pilote inférieur suivant. Une fois que l’IRP a atteint le pilote du bus, l’appareil est hors tension et ses pilotes n’y ont plus accès. Sur Windows Server 2003, Windows XP et Windows 2000, une routine IoCompletion associée à un IRP hors tension est uniquement nécessaire pour appeler PoStartNextPowerIrp.

Un seul IRP d’inrush peut être actif dans le système à la fois. Lors de la transmission d’un IRP de mise sous tension pour un appareil qui nécessite un courant d’inrush (en d’autres termes, l’indicateur DO_POWER_INRUSH est défini dans l’objet de l’appareil), PoCallDriver vérifie si un autre IRP d’appel est déjà actif. Si c’est le cas, PoCallDriver met en file d’attente l’IRP actuel pour la gestion une fois l’IRP précédent terminé, puis retourne STATUS_PENDING. Pour plus d’informations sur les IRP d’inrush, consultez Définition d’indicateurs d’objet d’appareil pour la gestion de l’alimentation.

Si une requête IRP_MN_SET_POWER ou IRP_MN_QUERY_POWER est déjà active pour DeviceObject, PoCallDriver met en file d’attente cette IRP et retourne STATUS_PENDING.

Sur les systèmes Windows 2000 et versions ultérieures, les pilotes paginables (l’indicateur DO_POWER_PAGABLE est défini dans l’objet d’appareil) doivent appeler PoCallDriver à l’adresse IRQL = PASSIVE_LEVEL. Les pilotes qui ne peuvent pas être paginés (DO_POWER_PAGABLE n’est pas défini dans l’objet d’appareil) ou qui nécessitent un courant d’inrush (DO_POWER_INRUSH est défini dans l’objet d’appareil) peuvent appeler PoCallDriver à l’adresse IRQL = PASSIVE_LEVEL ou DISPATCH_LEVEL.

Sur Windows 98/Me, tous les pilotes appellent PoCallDriver à l’adresse IRQL = PASSIVE_LEVEL.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000.
Plateforme cible	Universal
En-tête	ntifs.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Consultez la section Notes.
Règles de conformité DDI	CompleteRequestStatusCheck(wdm),CompletionRoutineRegistered(wdm), DeleteDevice(wdm), ForwardedAtBadIrql(wdm), ForwardedAtBadIrqlAllocate(wdm),ForwardedAtBadIrqlFsdAsync(wdm),ForwardedAtBadIrqlFsdSync(wdm),HwStorPortProhibitedDDIs(storport),IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildFsdForward(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IoSetCompletionRoutineExCheck(wdm), IrpProcessingComplete(wdm), LowerDriverReturn(wdm), MarkDevicePower(wdm), MarkingQueuedIrps(wdm), MarkIrpPending(wdm), MarkIrpPending2(wdm), MarkPower(wdm) , MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequest(wdm), PendedCompletedRequest2(wdm), PendedCompletedRequest3(wdm), PendedCompletedRequestEx(wdm), PnpIrpCompletion(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RemoveLockForward(wdm), RemoveLockForward2(wdm), RemoveLockForwardDeviceControl(wdm),RemoveLockForwardDeviceControl2(wdm), RemoveLockForwardDeviceControlInternal(wdm),RemoveLockForwardDeviceControlInternal2(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardRead2(wdm), RemoveLockForwardWrite(wdm), RemoveLockForwardWrite2(wdm), RemoveLockMnRemove2(wdm), RemoveLockMnSurpriseRemove(wdm), RemoveLockQueryMnRemove(wdm),TargetRelationNeedsRef(wdm), WmiForward(wdm)