Fungsi WdfDeviceCreate (wdfdevice.h)
[Berlaku untuk KMDF dan UMDF]
Metode WdfDeviceCreate membuat objek perangkat kerangka kerja.
Sintaks
NTSTATUS WdfDeviceCreate(
[in, out] PWDFDEVICE_INIT *DeviceInit,
[in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
[out] WDFDEVICE *Device
);
Parameter
[in, out] DeviceInit
Alamat pointer ke struktur WDFDEVICE_INIT . Jika WdfDeviceCreate tidak mengalami kesalahan, WdfDeviceCreate mengatur penunjuk ke NULL.
[in, optional] DeviceAttributes
Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan pemanggil yang berisi atribut untuk objek baru. (Anggota ParentObject struktur harus NULL.) Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.
[out] Device
Penunjuk ke lokasi yang menerima handel ke objek perangkat kerangka kerja baru.
Mengembalikan nilai
Jika metode WdfDeviceCreate tidak mengalami kesalahan, metode tersebut mengembalikan STATUS_SUCCESS. Nilai pengembalian tambahan meliputi:
|Mengembalikan kode|Deskripsi| |--- |--- | |STATUS_INVALID_PARAMETER|Handel Device atau DeviceInit tidak valid disediakan.| |STATUS_INVALID_DEVICE_STATE|Driver telah membuat objek perangkat untuk perangkat.| |STATUS_INVALID_SECURITY_DESCR|driver bernama WdfDeviceInitAssignSDDLString atau WdfDeviceInitSetDeviceClass tetapi tidak memberikan nama untuk objek perangkat.| |STATUS_INSUFFICIENT_RESOURCES|Objek perangkat tidak dapat dialokasikan.| |STATUS_OBJECT_NAME_COLLISION|Nama perangkat yang ditentukan oleh panggilan ke WdfDeviceInitAssignName sudah ada. Driver dapat memanggil WdfDeviceInitAssignName lagi untuk menetapkan nama baru.| Untuk daftar nilai pengembalian lain yang dapat dikembalikan WdfDeviceCreate, lihat Kesalahan Pembuatan Objek Kerangka Kerja.
Metode ini mungkin mengembalikan nilai NTSTATUS lainnya.
Keterangan
Sebelum memanggil WdfDeviceCreate, driver harus memanggil fungsi yang disediakan kerangka kerja yang menginisialisasi struktur WDFDEVICE_INIT. Untuk informasi selengkapnya tentang menginisialisasi struktur ini, lihat WDFDEVICE_INIT. Jika driver mengalami kesalahan saat memanggil fungsi inisialisasi, driver tidak boleh memanggil WdfDeviceCreate. Dalam hal ini, driver mungkin harus memanggil WdfDeviceInitFree. Untuk informasi tentang kapan harus memanggil WdfDeviceInitFree, lihat WdfDeviceInitFree.
Panggilan ke WdfDeviceCreate membuat objek perangkat kerangka kerja yang mewakili objek perangkat fungsional (FDO) atau objek perangkat fisik (PDO). Jenis objek perangkat yang dibuat fungsi tergantung pada bagaimana driver memperoleh struktur WDFDEVICE_INIT:
- Jika driver menerima struktur WDFDEVICE_INIT dari panggilan balik EvtDriverDeviceAdd , WdfDeviceCreate membuat FDO.
- Jika driver menerima struktur WDFDEVICE_INIT dari panggilan balik EvtChildListCreateDevice , atau dari panggilan ke WdfPdoInitAllocate, WdfDeviceCreate membuat PDO.
Driver miniport yang menggunakan kerangka kerja harus memanggil WdfDeviceMiniportCreate alih-alih WdfDeviceCreate.
Induk dari setiap objek perangkat kerangka kerja adalah objek driver kerangka kerja driver. Driver tidak dapat mengubah induk ini, dan anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES harus NULL. Kerangka kerja menghapus setiap objek perangkat kerangka kerja (kecuali untuk beberapa objek perangkat kontrol) ketika manajer Plug and Play (PnP) menentukan bahwa perangkat telah dihapus.
Jika driver Anda menyediakan fungsi panggilan balik EvtCleanupCallback atau EvtDestroyCallback untuk objek perangkat kerangka kerja, perhatikan bahwa kerangka kerja memanggil fungsi panggilan balik ini di IRQL = PASSIVE_LEVEL.
Untuk informasi selengkapnya tentang membuat objek perangkat, lihat Membuat Objek Perangkat Kerangka Kerja.
Contoh
Contoh kode berikut menunjukkan bagaimana fungsi panggilan balik EvtDriverDeviceAdd mungkin menginisialisasi dan membuat objek perangkat.
NTSTATUS
MyEvtDeviceAdd(
IN WDFDRIVER Driver,
IN PWDFDEVICE_INIT DeviceInit
)
{
WDF_PNPPOWER_EVENT_CALLBACKS pnpPowerCallbacks;
WDF_OBJECT_ATTRIBUTES attributes;
NTSTATUS status;
WDFDEVICE device;
//
// Initialize the WDF_PNPPOWER_EVENT_CALLBACKS structure.
//
WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtDevicePrepareHardware;
pnpPowerCallbacks.EvtDeviceD0Entry = MyEvtDeviceD0Entry;
pnpPowerCallbacks.EvtDeviceD0Exit = MyEvtDeviceD0Exit;
WdfDeviceInitSetPnpPowerEventCallbacks(
DeviceInit,
&pnpPowerCallbacks
);
//
// This driver uses buffered I/O.
//
WdfDeviceInitSetIoType(
DeviceInit,
WdfDeviceIoBuffered
);
//
// Specify the device object's context space by
// using a driver-defined DEVICE_CONTEXT structure.
//
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
&attributes,
DEVICE_CONTEXT
);
//
// Create the device object.
//
status = WdfDeviceCreate(
&DeviceInit,
&attributes,
&device
);
if (!NT_SUCCESS(status)) {
return status;
}
return STATUS_SUCCESS;
}
Persyaratan
Persyaratan | Nilai |
---|---|
Target Platform | Universal |
Versi KMDF minimum | 1,0 |
Versi UMDF minimum | 2.0 |
Header | wdfdevice.h (termasuk Wdf.h) |
Pustaka | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
Aturan kepatuhan DDI | AccessHardwareKey(kmdf), AddPdoToStaticChildList(kmdf), ChangeQueueState(kmdf), ChildDeviceInitAPI(kmdf), ChildListConfiguration(kmdf), ControlDeviceDeleted(kmdf), ControlDeviceInitAllocate(kmdf), ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDrEntry(kmdf), DeviceCreateFail(kmdf), DeviceInitAllocate(kmdf), DeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCreate(kmdf), PdoInitFreeDeviceCreateType2(kmdf), PdoInitFreeDeviceCreateType4(kmdf) |
Lihat juga
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
WDF_PNPPOWER_EVENT_CALLBACKS_INIT