Fungsi IoCreateDevice (wdm.h)

Artikel
08/08/2023

Rutinitas IoCreateDevice membuat objek perangkat untuk digunakan oleh driver.

Sintaks

NTSTATUS IoCreateDevice(
  [in]           PDRIVER_OBJECT  DriverObject,
  [in]           ULONG           DeviceExtensionSize,
  [in, optional] PUNICODE_STRING DeviceName,
  [in]           DEVICE_TYPE     DeviceType,
  [in]           ULONG           DeviceCharacteristics,
  [in]           BOOLEAN         Exclusive,
  [out]          PDEVICE_OBJECT  *DeviceObject
);

Parameter

[in] DriverObject

Arahkan ke objek driver untuk pemanggil. Setiap driver menerima penunjuk ke objek drivernya dalam parameter untuk rutinitas DriverEntry-nya . Fungsi WDM dan driver filter juga menerima penunjuk objek driver dalam rutinitas AddDevice mereka.

[in] DeviceExtensionSize

Menentukan jumlah byte yang ditentukan driver yang akan dialokasikan untuk ekstensi perangkat objek perangkat. Struktur internal ekstensi perangkat ditentukan driver.

[in, optional] DeviceName

Secara opsional menunjuk ke buffer yang berisi string Unicode yang dihentikan null yang memberi nama objek perangkat. String harus berupa nama jalur lengkap. Filter WDM dan driver fungsi tidak memberi nama objek perangkat mereka. Untuk informasi selengkapnya, lihat Objek Perangkat Bernama.

Jika nama perangkat tidak disediakan (yaitu, DeviceName adalah NULL), objek perangkat yang dibuat oleh IoCreateDevice tidak akan (dan tidak dapat) memiliki daftar kontrol akses diskresi (DACL) yang terkait dengannya. Untuk informasi tambahan, lihat Deskriptor Keamanan.

[in] DeviceType

Menentukan salah satu konstanta FILE_DEVICE_XXXX yang ditentukan sistem yang menunjukkan jenis perangkat (seperti FILE_DEVICE_DISK atau FILE_DEVICE_KEYBOARD) atau nilai yang ditentukan vendor untuk jenis perangkat baru. Untuk informasi selengkapnya, lihat Menentukan Jenis Perangkat.

[in] DeviceCharacteristics

Menentukan satu atau beberapa konstanta yang ditentukan sistem, ORed bersama-sama, yang memberikan informasi tambahan tentang perangkat driver. Untuk daftar karakteristik perangkat yang mungkin, lihat DEVICE_OBJECT. Untuk informasi selengkapnya tentang cara menentukan karakteristik perangkat, lihat Menentukan Karakteristik Perangkat. Sebagian besar driver menentukan FILE_DEVICE_SECURE_OPEN untuk parameter ini.

[in] Exclusive

Menentukan apakah objek perangkat mewakili perangkat eksklusif. Sebagian besar driver mengatur nilai ini ke FALSE. Untuk informasi selengkapnya tentang akses eksklusif, lihat Menentukan Akses Eksklusif ke Objek Perangkat.

[out] DeviceObject

Penunjuk ke variabel yang menerima penunjuk ke struktur DEVICE_OBJECT yang baru dibuat. Struktur DEVICE_OBJECT dialokasikan dari kumpulan yang tidak disebarkan. Ekstensi perangkat objek perangkat dinilai nol.

Nilai kembali

IoCreateDevice mengembalikan STATUS_SUCCESS pada keberhasilan, atau kode kesalahan NTSTATUS yang sesuai pada kegagalan. Daftar parsial kode kegagalan yang dikembalikan oleh fungsi ini meliputi:

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION

Keterangan

IoCreateDevice membuat objek perangkat dan mengembalikan penunjuk ke objek . Pemanggil bertanggung jawab untuk menghapus objek ketika tidak lagi diperlukan dengan memanggil IoDeleteDevice.

IoCreateDevice hanya dapat digunakan untuk membuat objek perangkat yang tidak disebutkan namanya, atau objek perangkat bernama yang deskriptor keamanannya diatur oleh file INF. Jika tidak, driver harus menggunakan IoCreateDeviceSecure untuk membuat objek perangkat bernama. Untuk informasi selengkapnya, lihat Membuat Objek Perangkat. Pemanggil bertanggung jawab untuk mengatur anggota tertentu dari objek perangkat yang dikembalikan. Untuk informasi selengkapnya, lihat Menginisialisasi Objek Perangkat dan dokumentasi khusus jenis perangkat untuk perangkat Anda.

Berhati-hatilah untuk menentukan nilai DeviceType dan DeviceCharacteristics dalam parameter yang benar. Kedua parameter menggunakan konstanta FILE_XXX yang ditentukan sistem dan beberapa penulis driver menentukan nilai dalam parameter yang salah secara tidak sengaja.

Sistem file jarak jauh yang membuat objek perangkat bernama untuk pengalih jaringan, dan yang mendaftar menggunakan FsRtlRegisterUncProvider, harus menentukan FILE_REMOTE_DEVICE sebagai salah satu opsi dalam parameter DeviceCharacteristics IoCreateDevice.

Objek perangkat untuk disk, kaset, CD-ROM, dan disk RAM diberi Blok Parameter Volume (VPB) yang diinisialisasi untuk menunjukkan bahwa volume belum pernah dipasang pada perangkat.

Jika panggilan driver ke IoCreateDevice mengembalikan kesalahan, driver harus merilis sumber daya apa pun yang dialokasikan untuk perangkat tersebut.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Aturan kepatuhan DDI	AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf)