Fungsi PoCallDriver (ntifs.h)

Artikel
07/11/2023

Rutinitas PoCallDriver meneruskan IRP daya ke driver berikutnya yang lebih rendah di tumpukan perangkat. (Hanya Windows Server 2003, Windows XP, dan Windows 2000.)

Sintaks

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

Parameter

[in] DeviceObject

Penunjuk ke DEVICE_OBJECT yang dibuat driver tempat IRP akan dirutekan.

[in, out] Irp

Penunjuk ke IRP.

Nilai kembali

PoCallDriver mengembalikan STATUS_SUCCESS untuk menunjukkan keberhasilan. Ini mengembalikan STATUS_PENDING jika telah mengantre IRP.

Keterangan

Dimulai dengan Windows Vista, driver harus memanggil IoCallDriver, bukan PoCallDriver untuk meneruskan IRP daya ke driver berikutnya yang lebih rendah. Namun, pada Windows Server 2003, Windows XP, dan Windows 2000, driver harus memanggil PoCallDriver, bukan IoCallDriver untuk meneruskan IRP daya ke driver berikutnya yang lebih rendah. Pada Windows Server 2003, Windows XP, Windows 2000, driver juga harus memanggil PoStartNextPowerIrp sebelum memanggil PoCallDriver.

Driver yang memerlukan IRP baru harus memanggil PoRequestPowerIrp. Driver tidak boleh mengalokasikan IRP dayanya sendiri.

Saat meneruskan IRP daya ke driver yang lebih rendah berikutnya, pemanggil harus menggunakan IoSkipCurrentIrpStackLocation atau IoCopyCurrentIrpStackLocationToNext untuk mengatur lokasi tumpukan IRP, lalu memanggil PoCallDriver. Gunakan IoCopyCurrentIrpStackLocationToNext jika memproses IRP memerlukan pengaturan rutinitas IoCompletion , atau IoSkipCurrentStackLocation jika tidak diperlukan rutinitas IoCompletion .

Saat perangkat menyala, drivernya harus mengatur rutinitas IoCompletion untuk melakukan tugas start-up (menginisialisasi perangkat, memulihkan konteks, dan sebagainya) setelah driver bus mengatur perangkat dalam status kerja. Atur rutinitas IoCompletion sebelum memanggil PoCallDriver.

Ketika perangkat mati, drivernya harus melakukan tugas matikan yang diperlukan sebelum meneruskan IRP ke driver bawah berikutnya. Setelah IRP mencapai driver bus, perangkat akan dimatikan dan drivernya tidak akan lagi memiliki akses ke dalamnya. Pada Windows Server 2003, Windows XP, dan Windows 2000, rutinitas IoCompletion yang terkait dengan power-down IRP hanya diperlukan untuk memanggil PoStartNextPowerIrp.

Hanya satu IRP inrush yang dapat aktif dalam sistem pada satu waktu. Saat meneruskan IRP power-up untuk perangkat yang memerlukan arus masuk (dengan kata lain, bendera DO_POWER_INRUSH diatur di objek perangkat), PoCallDriver memeriksa apakah IRP inrush lain sudah aktif. Jika demikian, PoCallDriver mengantrekan IRP saat ini untuk penanganan setelah IRP sebelumnya selesai, lalu mengembalikan STATUS_PENDING. Untuk informasi selengkapnya tentang IRP inrush, lihat Mengatur Bendera Objek Perangkat untuk Power Management.

Jika permintaan IRP_MN_SET_POWER atau IRP_MN_QUERY_POWER sudah aktif untuk DeviceObject, PoCallDriver mengantrekan IRP ini dan mengembalikan STATUS_PENDING.

Pada sistem Windows 2000 dan yang lebih baru, driver yang dapat di-pageable (bendera DO_POWER_PAGABLE diatur dalam objek perangkat) harus memanggil PoCallDriver di IRQL = PASSIVE_LEVEL. Driver yang tidak dapat di-page (DO_POWER_PAGABLE tidak diatur dalam objek perangkat) atau yang memerlukan arus inrush (DO_POWER_INRUSH diatur dalam objek perangkat) dapat memanggil PoCallDriver di IRQL = PASSIVE_LEVEL atau DISPATCH_LEVEL.

Pada Windows 98/Me, semua driver memanggil PoCallDriver di IRQL = PASSIVE_LEVEL.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000.
Target Platform	Universal
Header	ntifs.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Lihat bagian Keterangan.
Aturan kepatuhan 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)