Fungsi PoRequestPowerIrp (wdm.h)

Artikel
03/08/2023

Rutinitas PoRequestPowerIrp mengalokasikan IRP daya dan mengirimkannya ke driver teratas di tumpukan perangkat untuk perangkat yang ditentukan.

Sintaks

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

Parameter

[in] DeviceObject

Penunjuk ke DEVICE_OBJECT target untuk IRP. Di Windows 2000 dan versi Windows yang lebih baru, parameter ini dapat menunjuk ke objek perangkat fisik (PDO) atau objek perangkat fungsi (FDO). Di Windows 98/Me, parameter ini harus menunjuk ke PDO perangkat yang mendasar.

[in] MinorFunction

Menentukan salah satu kode IRP daya minor berikut: IRP_MN_QUERY_POWER, IRP_MN_SET_POWER, atau IRP_MN_WAIT_WAKE.

[in] PowerState

Menentukan nilai POWER_STATE untuk diteruskan dalam IRP. Untuk IRP_MN_SET_POWER dan IRP_MN_QUERY_POWER, tentukan status daya perangkat baru yang diminta. Nilai yang mungkin adalah nilai DEVICE_POWER_STATE .

Untuk IRP_MN_WAIT_WAKE, tentukan status daya sistem terendah (paling sedikit bertenaga) dari mana perangkat harus diizinkan untuk membangunkan sistem. Nilai yang mungkin adalah nilai SYSTEM_POWER_STATE .

[in, optional] CompletionFunction

Penunjuk ke rutinitas panggilan balik PowerCompletion penelepon. Manajer I/O memanggil rutinitas ini ketika IRP telah selesai. Parameter ini bersifat opsional dan dapat diatur ke NULL jika tidak ada rutinitas panggilan balik PowerCompletion yang diperlukan.

[in, optional] Context

Penunjuk ke konteks yang disediakan penelepon untuk diteruskan ke panggilan balik PowerCompletion . Ketika pemanggil meminta IRP set-power perangkat sebagai respons terhadap IRP set-power sistem, Context harus berisi IRP set-power sistem yang memicu permintaan.

[out] Irp

Pointer ke variabel yang disediakan penelepon di mana PoRequestPowerIrp mengembalikan pointer ke IRP yang dialokasikannya. Tentukan nilai untuk Irp hanya jika parameter MinorFunction diatur ke IRP_MN_WAIT_WAKE. Jika tidak, parameter ini harus selalu NULL karena IRP mungkin selesai sebelum PoRequestPowerIrp kembali, menyebabkan parameter ini menunjuk ke memori yang telah dibuang.

Nilai kembali

PoRequestPowerIrp mengembalikan salah satu hal berikut ini:

Menampilkan kode	Deskripsi
STATUS_PENDING	IRP telah dikirim.
STATUS_INSUFFICIENT_RESOURCES	Rutinitas tidak dapat mengalokasikan IRP.
STATUS_INVALID_PARAMETER_2	MinorFunction tidak menandakan kode IRP daya minor yang valid.

Keterangan

Pemilik kebijakan daya perangkat memanggil rutinitas ini untuk mengirim IRP tunggu/bangun, kueri, atau set-power.

Driver memanggil PoRequestPowerIrp—bukan IoAllocateIrp—untuk mengalokasikan dan mengirim IRP daya yang memiliki kode IRP kecil IRP_MN_SET_POWER, IRP_MN_QUERY_POWER, atau IRP_MN_WAIT_WAKE. (Driver harus memanggil IoAllocateIrp untuk mengirim IRP daya dengan kode IRP kecil IRP_MN_POWER_SEQUENCE.)

Jika PoRequestPowerIrp mengembalikan nilai status STATUS_PENDING, rutinitas berhasil mengalokasikan IRP daya perangkat dan mengirimkannya ke bagian atas tumpukan perangkat untuk perangkat. Setelah pengemudi bus dan semua driver lainnya menyelesaikan IRP, dan manajer I/O telah memanggil semua rutinitas IoCompletion yang ditetapkan oleh driver saat mereka melewati IRP ke tumpukan perangkat, manajer I/O memanggil rutinitas PowerCompletion dan meneruskan ke rutinitas ini nilai Konteks yang ditentukan. Jika PoRequestPowerIrp mengembalikan status selain STATUS_PENDING, rutinitas tidak mengirim IRP daya perangkat dan rutinitas PowerCompletion tidak dipanggil.

Rutinitas PowerCompletion melakukan tugas tambahan yang diperlukan pengirim IRP setelah semua driver lain menyelesaikan IRP. Tidak perlu membebaskan IRP; manajer daya melakukan itu. Di Windows 2000 dan versi Windows yang lebih baru, rutinitas PowerCompletion dapat dipanggil di IRQL = PASSIVE_LEVEL atau IRQL = DISPATCH_LEVEL. Di Windows 98/Me, rutinitas PowerCompletion selalu dipanggil di IRQL = PASSIVE_LEVEL, dan driver harus menyelesaikan RUNP di IRQL = PASSIVE_LEVEL.

Pemilik kebijakan daya perangkat memanggil PoRequestPowerIrp untuk mengirim IRP kueri perangkat- atau set-power saat menerima IRP kueri sistem atau set-power. Driver harus mengatur rutinitas IoCompletion di IRP sistem dan meneruskan IRP sistem ke driver yang lebih rendah berikutnya. Rutinitas IoCompletion memanggil PoRequestPowerIrp untuk mengirim IRP perangkat, melewati IRP sistem dalam parameter Konteks . Parameter Konteks kemudian diteruskan ke rutinitas PowerCompletion untuk IRP perangkat. Dalam rutinitas PowerCompletion , driver dapat menyelesaikan IRP sistem. Untuk informasi selengkapnya, lihat Mengirim IRP_MN_QUERY_POWER atau IRP_MN_SET_POWER untuk Status Daya Perangkat dan Rutinitas Panggilan Balik Tunggu/Bangun.

Driver dapat menggunakan Irp yang dikembalikan untuk membatalkan IRP IRP_MN_WAIT_WAKE . Driver yang meminta jenis runtime integrasi daya lainnya harus melewati NULL untuk parameter ini.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 2000.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm)