Fungsi IoGetDeviceObjectPointer (wdm.h)

Artikel
02/27/2024

Rutinitas IoGetDeviceObjectPointer mengembalikan penunjuk ke objek atas di tumpukan objek perangkat bernama dan penunjuk ke objek file yang sesuai, jika akses yang diminta ke objek dapat diberikan.

Sintaks

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

Parameter

[in] ObjectName

Penunjuk ke buffer yang berisi string Unicode yang merupakan nama objek perangkat.

[in] DesiredAccess

Menentukan nilai ACCESS_MASK yang mewakili akses yang diinginkan. Biasanya DesiredAccess FILE_READ_DATA. Jarang, hak akses FILE_WRITE_DATA, atau FILE_ALL_ACCESS ditentukan.

[out] FileObject

Arahkan ke objek file yang mewakili objek perangkat yang sesuai dengan kode mode pengguna jika panggilan berhasil.

[out] DeviceObject

Arahkan ke objek perangkat yang mewakili perangkat logis, virtual, atau fisik bernama jika panggilan berhasil.

Nilai kembali

IoGetDeviceObjectPointer mengembalikan STATUS_SUCCESS jika berhasil. Kemungkinan nilai pengembalian kesalahan mencakup kode status berikut:

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

Keterangan

IoGetDeviceObjectPointer membuat "koneksi" antara pemanggil dan driver tingkat bawah berikutnya. Penelepon yang berhasil dapat menggunakan penunjuk objek perangkat yang dikembalikan untuk menginisialisasi objek perangkatnya sendiri. Ini juga dapat digunakan sebagai argumen untuk IoAttachDeviceToDeviceStack, IoCallDriver, dan rutinitas apa pun yang membuat RUN untuk driver yang lebih rendah. Penunjuk yang dikembalikan adalah argumen yang diperlukan untuk IoCallDriver.

Rutinitas ini juga mengembalikan penunjuk ke objek file yang sesuai. Saat membongkar, driver dapat mendereferensikan objek file sebagai sarana dereferensi objek perangkat secara tidak langsung. Untuk melakukannya, driver memanggil ObDereferenceObject dari rutinitas Unload-nya, melewati penunjuk objek file yang dikembalikan oleh IoGetDeviceObjectPointer. Kegagalan untuk mendereferensikan objek perangkat dalam rutinitas Bongkar pengandar mencegah driver berikutnya yang lebih rendah dibongkar. Namun, driver yang menutup objek file sebelum proses bongkar harus mengeluarkan referensi tambahan pada objek perangkat sebelum mendereferensikan objek file. Jika tidak, mendereferensikan objek file dapat menyebabkan penghapusan objek perangkat prematur.

Untuk mendapatkan penunjuk ke driver tingkat tertinggi dalam tumpukan driver sistem file, driver harus memastikan bahwa sistem file dipasang; jika tidak, rutinitas ini melintasi tumpukan perangkat penyimpanan. Untuk memastikan bahwa sistem file dipasang pada perangkat penyimpanan, driver harus menentukan masker akses yang sesuai, seperti FILE_READ_DATA atau FILE_WRITE_ATTRIBUTES, dalam parameter DesiredAccess . Menentukan FILE_READ_ATTRIBUTES tidak menyebabkan sistem file dipasang.

Setelah driver tingkat yang lebih tinggi menautkan dirinya sendiri melalui driver lain dengan berhasil memanggil rutinitas ini, driver tingkat yang lebih tinggi harus mengatur bidang StackSize di objek perangkatnya ke objek perangkat driver tingkat lebih rendah berikutnya ditambah satu.

Penelepon IoGetDeviceObjectPointer harus berjalan di IRQL = PASSIVE_LEVEL.

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), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)