PoCallDriver 函式 (ntifs.h)

發行項
03/01/2024

PoCallDriver 例程會將電源 IRP 傳遞至裝置堆疊中的下一個較低驅動程式。 (Windows Server 2003、Windows XP 和 Windows 2000 only.)

語法

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

參數

[in] DeviceObject

要路由傳送 IRP 的驅動程式建立DEVICE_OBJECT 指標。

[in, out] Irp

IRP 的指標。

傳回值

PoCallDriver 會傳回STATUS_SUCCESS，以指出成功。如果已將 IRP 排入佇列，則會傳回STATUS_PENDING。

備註

從 Windows Vista 開始，驅動程式應該呼叫 IoCallDriver，而不是 PoCallDriver ，將電源 IRP 傳遞至下一個較低的驅動程式。不過，在 Windows Server 2003、Windows XP 和 Windows 2000 上，驅動程式必須呼叫 PoCallDriver，而不是 IoCallDriver ，才能將電源 IRP 傳遞至下一個較低的驅動程式。在 Windows Server 2003 上，Windows XP 是 Windows 2000，驅動程式也必須呼叫 PoStartNextPowerIrp ，再呼叫 PoCallDriver。

需要新 IRP 的驅動程式應該呼叫 PoRequestPowerIrp。驅動程式不得配置自己的電源 IRP。

將電源 IRP 向下傳遞至下一個較低的驅動程式時，呼叫端應該使用 IoSkipCurrentIrpStackLocation 或 IoCopyCurrentIrpStackLocationToNext 來設定 IRP 堆棧位置，然後呼叫 PoCallDriver。如果處理 IRP 需要設定 IoCompletion 例程，請使用 IoCopyCurrentIrpStackLocationToNext，如果不需要 IoCompletion 例程，請使用 IoSkipCurrentStackLocation。

當裝置電源啟動時，其驅動程式必須設定 IoCompletion 例程，以執行啟動工作， (初始化裝置、還原內容等等，在總線驅動程式設定裝置處於工作狀態之後) 。呼叫 PoCallDriver 之前，請先設定 IoCompletion 例程。

當裝置關閉電源時，其驅動程式必須先執行必要的關機工作，才能將 IRP 傳遞至下一個較低的驅動程式。 IRP 到達總線驅動程序之後，裝置將會關閉電源，而且其驅動程式將無法再存取它。在 Windows Server 2003、Windows XP 和 Windows 2000 上，只有呼叫 PoStartNextPowerIrp 才需要與關機 IRP 相關聯的 IoCompletion 例程。

系統一次只能有一個無作用中的 IRP。針對需要內嵌目前 (的裝置傳遞電源 IRP 時，DO_POWER_INRUSH旗標會在裝置物件中設定 ) ，PoCallDriver 會檢查另一個內嵌 IRP 是否已經作用中。如果是， PoCallDriver 會將目前的 IRP 排入佇列，以便在先前的 IRP 完成之後進行處理，然後傳回STATUS_PENDING。如需內嵌 IRP 的詳細資訊，請參閱設定電源管理的裝置物件旗標。

如果 DeviceObject 已使用IRP_MN_SET_POWER或IRP_MN_QUERY_POWER要求，PoCallDriver 會將此 IRP 排入佇列，並傳回STATUS_PENDING。

在 Windows 2000 和更新版本系統上， (DO_POWER_PAGABLE 旗標的可分頁驅動程式是在裝置物件中設定，) 必須在 IRQL = PASSIVE_LEVEL呼叫 PoCallDriver 。無法分頁 (DO_POWER_PAGABLE 的驅動程式未在裝置物件中設定) ，或需要在裝置物件中設定目前 (DO_POWER_INRUSH 的驅動程式，) 可以在 IRQL = PASSIVE_LEVEL或DISPATCH_LEVEL呼叫 PoCallDriver 。

在 Windows 98/Me 上，所有驅動程式都會在 IRQL = PASSIVE_LEVEL呼叫 PoCallDriver 。

規格需求

需求	值
最低支援的用戶端	Windows 2000。
目標平台	Universal
標頭	ntifs.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	請參閱一節。
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) 、 MarkQueuedIrps (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)