Fungsi PoFxRegisterDevice (wdm.h)

Artikel
08/08/2023

Rutinitas PoFxRegisterDevice mendaftarkan perangkat dengan kerangka kerja manajemen daya (PoFx).

Sintaks

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

Parameter

[in] Pdo

Penunjuk ke objek perangkat fisik (PDO). Parameter ini menunjuk ke struktur DEVICE_OBJECT yang mewakili perangkat fisik yang sedang didaftarkan. Pemanggil adalah pemilik kebijakan daya untuk perangkat, yang biasanya merupakan driver fungsi perangkat.

[in] Device

Penunjuk ke struktur PO_FX_DEVICE yang dialokasikan penelepon yang berisi informasi pendaftaran untuk perangkat. Struktur ini berisi pointer ke sekumpulan rutinitas panggilan balik yang diimplementasikan oleh driver perangkat. PoFx memanggil rutinitas ini untuk berkomunikasi dengan pengemudi.

[out] Handle

Pointer ke lokasi tempat rutin menulis handel yang mewakili pendaftaran perangkat dengan PoFx. Driver perangkat meneruskan handel ini sebagai parameter input ke rutinitas PoFxXxx lainnya yang dipanggilnya. Driver harus terlebih dahulu memanggil PoFxRegisterDevice untuk mendaftarkan perangkat sebelum driver memanggil rutinitas PoFxXxx lainnya untuk mengelola daya perangkat.

Nilai kembali

PoFxRegisterDevice mengembalikan STATUS_SUCCESS jika rutinitas berhasil mendaftarkan perangkat. Kemungkinan nilai pengembalian kesalahan menyertakan kode status berikut.

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Pdo adalah NULL; atau struktur PPO_FX_DEVICE memiliki nomor versi yang tidak valid atau jumlah komponen nol; atau jumlah status diam yang ditentukan untuk komponen adalah nol; atau deskripsi status diam tidak valid.
STATUS_DEVICE_NOT_READY	Perangkat belum siap.
STATUS_INSUFFICIENT_RESOURCES	Sumber daya yang tidak mencukuum tersedia untuk menyelesaikan pendaftaran.

Keterangan

Driver perangkat biasanya memanggil rutinitas ini dari handler permintaan IRP_MN_START_DEVICE driver. Driver tidak boleh memanggil rutinitas ini sebelum perangkat menerima permintaan IRP_MN_START_DEVICE . Perangkat menerima permintaan IRP_MN_START_DEVICE pertama saat perangkat dimulai untuk pertama kalinya. Perangkat menerima permintaan IRP_MN_START_DEVICE tambahan setiap kali perangkat dimulai ulang setelah dihentikan untuk penyeimbangan sumber daya. Panggilan PoFxRegisterDevice untuk mendaftarkan perangkat yang sudah terdaftar adalah kesalahan fatal dan menyebabkan pemeriksaan bug. Perhatikan bahwa PoFx melakukan salinan mendalam struktur perangkat ke dalam memorinya.

Sebelum driver memanggil PoFxRegisterDevice, perangkat harus memenuhi kondisi berikut:

Perangkat (yaitu, PDO) belum terdaftar di PoFx.
Perangkat dalam status daya D0 (sepenuhnya aktif).
Perangkat dalam kondisi berjalan.
Setiap komponen dalam perangkat berada dalam status daya F0 (sepenuhnya aktif).
Setiap komponen dalam kondisi aktif.

Dengan mendaftarkan perangkat dengan PoFx, driver bertanggung jawab untuk menginformasikan PoFx ketika komponen sedang digunakan secara aktif dan ketika komponen menganggur. Saat perangkat terdaftar, driver harus memanggil rutinitas PoFxActivateComponent untuk mendapatkan akses ke register perangkat keras komponen, dan driver harus memanggil rutinitas PoFxIdleComponent untuk memberi tahu PoFx ketika driver tidak lagi memerlukan akses ke komponen.

Setelah driver memanggil PoFxRegisterDevice untuk mendaftarkan perangkat dengan PoFx, semua komponen dalam perangkat sepenuhnya menyala dan dalam kondisi aktif sehingga driver dapat selesai menginisialisasi perangkat keras. Untuk memulai manajemen daya aktif, driver harus memanggil rutinitas PoFxStartDevicePowerManagement .

Secara default, PoFxStartDevicePowerManagement mengalihkan semua komponen ke kondisi diam. Jika driver memerlukan komponen untuk berada dalam kondisi aktif segera setelah manajemen daya dimulai, driver harus secara eksplisit mengaktifkan komponen dengan memanggil rutinitas PoFxActivateComponent , dan panggilan ini harus terjadi setelah panggilan PoFxRegisterDevice tetapi sebelum panggilan PoFxStartDevicePowerManagement .

Biasanya, driver Kernel-Mode Driver Framework (KMDF) untuk perangkat komponen tunggal tidak memanggil PoFxRegisterDevice untuk mendaftarkan perangkat dengan PoFx. Sebagai gantinya, driver ini menerima handel pendaftaran PoFx ketika KMDF memanggil fungsi panggilan balik EvtDeviceWdmPostPoFxRegisterDevice driver. Untuk informasi selengkapnya, lihat Mendukung Beberapa Status Daya Fungsi untuk Perangkat Single-Component.

Untuk informasi tentang bagaimana driver KMDF untuk perangkat beberapa komponen mendaftar dengan PoFx, lihat Mendukung Beberapa Status Daya Fungsi untuk Perangkat Multiple-Component.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Target Platform	Universal
Header	wdm.h
Pustaka	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL