Fungsi IoAttachDevice (wdm.h)

Artikel
03/01/2024

Rutinitas IoAttachDevice melampirkan objek perangkat penelepon ke objek perangkat target bernama, sehingga permintaan I/O yang terikat untuk perangkat target dirutekan terlebih dahulu ke pemanggil.

Sintaks

NTSTATUS IoAttachDevice(
  [in]  PDEVICE_OBJECT  SourceDevice,
  [in]  PUNICODE_STRING TargetDevice,
  [out] PDEVICE_OBJECT  *AttachedDevice
);

Parameter

[in] SourceDevice

Arahkan ke objek perangkat yang dibuat penelepon.

[in] TargetDevice

Penunjuk ke buffer yang berisi nama objek perangkat tempat SourceDevice yang ditentukan akan dilampirkan.

[out] AttachedDevice

Penunjuk ke penyimpanan yang dialokasikan penelepon untuk penunjuk. Saat kembali, berisi penunjuk ke objek perangkat target jika lampiran berhasil.

Nilai kembali

IoAttachDevice dapat mengembalikan salah satu nilai NTSTATUS berikut:

Keterangan

IoAttachDevice menetapkan lapisan antara driver sehingga IRP yang sama dapat dikirim ke setiap driver dalam rantai.

Rutinitas ini digunakan oleh driver perantara selama inisialisasi. Ini memungkinkan driver seperti itu untuk melampirkan objek perangkatnya sendiri ke perangkat lain sedemikian sehingga setiap permintaan yang dibuat ke perangkat asli diberikan terlebih dahulu ke driver perantara.

Pemanggil hanya dapat dilapisi di bagian atas rantai driver berlapis yang ada. IoAttachDevice mencari objek perangkat tertinggi yang berlapis di atas TargetDevice dan melampirkan ke objek tersebut (yang dapat berupa TargetDevice). Oleh karena itu, rutinitas ini tidak boleh dipanggil jika driver yang harus tingkat lebih tinggi telah melapisi dirinya sendiri di atas perangkat target.

Perhatikan bahwa untuk driver dan driver sistem file di tumpukan penyimpanan, IoAttachDevice membuka perangkat target dengan FILE_READ_ATTRIBUTES lalu memanggil IoGetRelatedDeviceObject. Ini tidak menyebabkan sistem file dipasang. Dengan demikian, panggilan yang berhasil ke IoAttachDevice mengembalikan objek perangkat driver penyimpanan, bukan driver sistem file.

Rutinitas ini mengatur AlignmentRequirement di SourceDevice ke nilai di objek perangkat berikutnya yang lebih rendah dan mengatur StackSize ke nilai di objek berikutnya yang lebih rendah ditambah satu.

Peringatan

AttachedDevice harus menunjuk ke lokasi memori global, seperti ekstensi perangkat driver. IoAttachDevice membuka objek file untuk perangkat target, memperbarui AttachedDevice, melakukan lampiran, lalu menutup objek file. Dengan demikian, perangkat sumber menerima permintaan IRP_MJ_CLEANUP dan IRP_MJ_CLOSE untuk objek file sebelum IoAttachDevice kembali. Driver harus meneruskan permintaan ini ke perangkat target, dan AttachedDevice harus merupakan lokasi memori yang dapat diakses oleh rutinitas DispatchCleanup dan DispatchClose driver.

Persyaratan

Persyaratan	Nilai
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), IrqlIoPassive1(wdm)