Fungsi IoGetDeviceProperty (wdm.h)
Rutinitas IoGetDeviceProperty mengambil informasi tentang perangkat seperti informasi konfigurasi dan nama PDO-nya.
Sintaks
NTSTATUS IoGetDeviceProperty(
[in] PDEVICE_OBJECT DeviceObject,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Parameter
[in] DeviceObject
Arahkan ke objek perangkat fisik (PDO) untuk perangkat yang sedang dikueri.
[in] DeviceProperty
Menentukan properti perangkat yang diminta. Harus salah satu nilai enumerasi DEVICE_REGISTRY_PROPERTY berikut:
DevicePropertyAddress
Meminta alamat perangkat di bus. PropertyBuffer menunjuk ke ULONG.
Interpretasi alamat ini khusus bus. Pemanggil rutin ini harus memanggil rutinitas lagi untuk meminta DevicePropertyBusTypeGuid, atau mungkin DevicePropertyLegacyBusType, sehingga dapat menafsirkan alamat. Nilai alamat 0xFFFFFFFF menunjukkan bahwa driver bus yang mendasar tidak menyediakan alamat bus untuk perangkat.
Daftar berikut ini menjelaskan informasi yang disimpan driver bus tertentu di PropertyBuffer untuk perangkat anak mereka:
| Bus | Deskripsi |
|---|---|
| 1394 | Tidak menyediakan alamat karena alamat tidak stabil. Default ke 0xFFFFFFFF. |
| EISA | Nomor Slot (0-F). |
| IDE | Untuk perangkat IDE, alamat berisi ID target dan LUN. Untuk saluran IDE, alamatnya adalah nol atau satu (0 = saluran utama dan 1 = saluran sekunder). |
| ISApnp | Tidak menyediakan alamat. Default ke 0xFFFFFFFF. |
| Kartu PC (PCMCIA) | Nomor soket (biasanya 0x00 atau 0x40). |
| PCI | Nomor perangkat dalam kata tinggi dan nomor fungsi dalam kata rendah. |
| SCSI | ID target. |
| USB | Nomor port. |
DevicePropertyBootConfiguration
Meminta sumber daya perangkat keras yang ditetapkan ke perangkat oleh firmware, dalam bentuk mentah. PropertyBuffer menunjuk ke struktur CM_RESOURCE_LIST .
DevicePropertyBootConfigurationTranslated
Sumber daya perangkat keras yang ditetapkan ke perangkat oleh firmware, dalam bentuk terjemahan. PropertyBuffer menunjuk ke struktur CM_RESOURCE_LIST .
DevicePropertyBusNumber
Meminta nomor bus warisan dari bus yang tersambung dengan perangkat. PropertyBuffer menunjuk ke ULONG.
DevicePropertyBusTypeGuid
Meminta GUID untuk bus yang tersambung dengan perangkat. GUID jenis bus yang ditentukan sistem tercantum dalam file header Wdmguid.h. PropertyBuffer menunjuk ke GUID, yang merupakan struktur 16-byte yang berisi GUID dalam bentuk biner.
DevicePropertyClassGuid
Meminta GUID untuk kelas penyiapan perangkat. PropertyBuffer menunjuk ke array WCHAR yang dihentikan NULL. Rutinitas ini mengembalikan GUID dalam format string sebagai berikut, di mana setiap "c" mewakili karakter heksadesimal: {cccccc-cc-cc-cc-cc-cc}
DevicePropertyClassName
Meminta nama kelas penyiapan perangkat, dalam format teks. PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyCompatibleIDs
Meminta ID yang kompatibel yang dilaporkan oleh perangkat. PropertyBuffer menunjuk ke nilai REG_MULTI_SZ.
DevicePropertyDeviceDescription
Meminta string yang menjelaskan perangkat, seperti "Microsoft PS/2 Port Mouse", biasanya didefinisikan oleh produsen. PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyDriverKeyName
Meminta nama kunci registri khusus driver. PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyEnumeratorName
Meminta nama enumerator untuk perangkat, seperti "PCI" atau "root". PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyFriendlyName
Meminta string yang dapat digunakan untuk membedakan antara dua perangkat serupa, biasanya didefinisikan oleh penginstal kelas. PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyHardwareID
Meminta ID perangkat keras yang disediakan oleh perangkat yang mengidentifikasi perangkat. PropertyBuffer menunjuk ke nilai REG_MULTI_SZ.
DevicePropertyInstallState
Meminta status penginstalan perangkat. Status penginstalan dikembalikan sebagai nilai enumerasi DEVICE_INSTALL_STATE .
DevicePropertyLegacyBusType
Meminta jenis bus, seperti PCIBus atau PCMCIABus. PropertyBuffer menunjuk ke nilai enumerasi INTERFACE_TYPE .
DevicePropertyLocationInformation
Meminta informasi tentang lokasi perangkat di bus; interpretasi informasi ini khusus untuk bus. PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyManufacturer
Meminta string yang mengidentifikasi produsen perangkat. PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyPhysicalDeviceObjectName
Meminta nama PDO untuk perangkat ini. PropertyBuffer menunjuk ke string WCHAR yang dihentikan NULL.
DevicePropertyRemovalPolicy
Meminta kebijakan penghapusan perangkat saat ini. Sistem operasi menggunakan nilai ini sebagai petunjuk untuk menentukan bagaimana perangkat biasanya dihapus. Parameter PropertyBuffer menunjuk ke nilai enumerasi DEVICE_REMOVAL_POLICY .
DevicePropertyUINumber
Meminta nomor yang terkait dengan perangkat yang dapat ditampilkan di antarmuka pengguna. PropertyBuffer menunjuk ke nilai ULONG.
Nomor ini biasanya merupakan nomor slot yang dirasakan pengguna, seperti nomor yang dicetak di samping slot di papan, atau beberapa nomor lain yang membuat menemukan perangkat fisik lebih mudah bagi pengguna. Jika perangkat berada di bus yang tidak memiliki konvensi nomor UI, atau jika driver bus untuk perangkat tidak dapat menentukan nomor UI, nilai ini 0xFFFFFFFF.
[in] BufferLength
Menentukan ukuran, dalam byte, dari PropertyBuffer yang disediakan pemanggil.
[out, optional] PropertyBuffer
Arahkan ke buffer yang disediakan penelepon untuk menerima informasi properti. Buffer dapat dialokasikan dari memori yang dapat di-pageable. Jenis buffer ditentukan oleh DeviceProperty (lihat di atas).
[out] ResultLength
Arahkan ke ULONG untuk menerima ukuran informasi properti yang dikembalikan di PropertyBuffer. Jika IoGetDeviceProperty mengembalikan STATUS_BUFFER_TOO_SMALL, IoGetDeviceProperty mengatur parameter ini ke panjang buffer yang diperlukan.
Mengembalikan nilai
IoGetDeviceProperty mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan termasuk yang berikut ini.
| Menampilkan kode | Deskripsi |
|---|---|
| STATUS_BUFFER_TOO_SMALL | Buffer di PropertyBuffer terlalu kecil. ResultLength menunjuk ke panjang buffer yang diperlukan. |
| STATUS_INVALID_PARAMETER_2 | DeviceProperty yang diberikan bukan salah satu properti yang ditangani oleh rutinitas ini. |
| STATUS_INVALID_DEVICE_REQUEST | Mungkin menunjukkan bahwa DeviceObject yang diberikan bukan penunjuk PDO yang valid. |
Keterangan
IoGetDeviceProperty mengambil informasi penyiapan perangkat dari registri. Gunakan rutinitas ini, daripada mengakses registri secara langsung, untuk mengisolasi driver dari perbedaan di seluruh platform dan dari kemungkinan perubahan dalam struktur registri.
Untuk banyak permintaan DeviceProperty , diperlukan dua panggilan atau lebih ke IoGetDeviceProperty untuk menentukan BufferLength yang diperlukan. Panggilan pertama harus menggunakan nilai tebakan terbaik. Jika status pengembalian STATUS_BUFFER_TOO_SMALL, driver harus membebaskan buffer saat ini, mengalokasikan buffer ukuran yang dikembalikan di ResultLength, dan memanggil IoGetDeviceProperty lagi. Karena beberapa properti penyiapan bersifat dinamis, ukuran data dapat berubah antara waktu ukuran yang diperlukan dikembalikan dan driver memanggil rutinitas ini lagi. Oleh karena itu, driver harus memanggil IoGetDeviceProperty di dalam perulangan yang berjalan sampai status pengembalian tidak STATUS_BUFFER_TOO_SMALL.
Driver fungsi yang mendukung perangkat pada bus warisan dan bus PnP dapat menggunakan properti DevicePropertyBusNumber, DevicePropertyBusTypeGuid, dan DevicePropertyLegacyBusType untuk membedakan antara bus.
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 | PASSIVE_LEVEL |
| Aturan kepatuhan DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |