Bagikan melalui


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)

Lihat juga

CM_RESOURCE_LIST

DEVICE_REMOVAL_POLICY

ExAllocatePoolWithTag

GUID

INTERFACE_TYPE

IO_RESOURCE_REQUIREMENTS_LIST