Fungsi WdfDeviceCreate (wdfdevice.h)

Artikel
08/08/2023

[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 penunjuk ke struktur WDFDEVICE_INIT . Jika WdfDeviceCreate tidak mengalami kesalahan, WdfDeviceCreate mengatur pointer ke NULL.

[in, optional] DeviceAttributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan penelepon 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.

Nilai kembali

Jika metode WdfDeviceCreate tidak mengalami kesalahan, metode mengembalikan STATUS_SUCCESS. Nilai pengembalian tambahan meliputi:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Handel Device atau DeviceInit tidak valid disediakan.
STATUS_INVALID_DEVICE_STATE	Pengandar telah membuat objek perangkat untuk perangkat.
STATUS_INVALID_SECURITY_DESCR	driver yang disebut 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.

Setelah driver memanggil WdfDeviceCreate, driver tidak dapat lagi mengakses struktur WDFDEVICE_INIT.

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)