Metode IWDFDriver::CreateDevice (wudfddi.h)

Artikel
02/27/2024

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode CreateDevice mengonfigurasi dan membuat objek perangkat kerangka kerja baru.

Sintaks

HRESULT CreateDevice(
  [in]           IWDFDeviceInitialize *pDeviceInit,
  [in, optional] IUnknown             *pCallbackInterface,
  [out]          IWDFDevice           **ppDevice
);

Parameter

[in] pDeviceInit

Penunjuk ke antarmuka IWDFDeviceInitialize yang mewakili properti konfigurasi untuk dibuat perangkat baru.

[in, optional] pCallbackInterface

Penunjuk ke antarmuka IUnknown yang digunakan kerangka kerja untuk mendapatkan antarmuka yang disediakan driver untuk objek perangkat baru. Antarmuka ini menyediakan fungsi panggilan balik yang dipanggil kerangka kerja saat peristiwa yang relevan terjadi. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[out] ppDevice

Pointer ke buffer yang menerima pointer ke antarmuka IWDFDevice untuk objek perangkat baru.

Nilai kembali

CreateDevice mengembalikan S_OK jika operasi berhasil. Jika tidak, metode ini mengembalikan salah satu kode kesalahan yang ditentukan dalam Winerror.h.

Keterangan

Antarmuka IUnknown yang disediakan driver untuk parameter pCallbackInterface dapat mendukung beberapa antarmuka. Kerangka kerja memanggil metode QueryInterface dari antarmuka IUnknown yang disediakan beberapa kali untuk mengambil antarmuka yang didukung driver. Metode QueryInterface driver dapat mengembalikan antarmuka berikut:

IPnpCallbackHardware2

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPowerPolicyCallbackWakeFromS0

IPowerPolicyCallbackWakeFromSx

Ketika status perangkat berubah, kerangka kerja memanggil metode yang terkait dengan perubahan (seperti metode IPnpCallback::OnD0Entry ) untuk memberi tahu driver.

Jika panggilan ke CreateDevice berhasil, driver akhirnya harus memanggil metode IWDFDevice::Release . Perhatikan bahwa kerangka kerja memiliki jumlah referensinya sendiri pada objek .

Untuk informasi selengkapnya, lihat Menambahkan Perangkat.

Contoh

Contoh kode berikut menunjukkan implementasi metode OnDeviceAdd antarmuka IDriverEntry . Kerangka kerja memanggil OnDeviceAdd saat perangkat ditambahkan ke komputer.

HRESULT 
CDriver::OnDeviceAdd(
 IWDFDriver* pDriver,
 IWDFDeviceInitialize* pDeviceInit
    )
{
 IUnknown   *pDeviceCallback = NULL;
 IWDFDevice *pIWDFDevice     = NULL;
 IUnknown   *pIUnkQueue      = NULL;    

    //
    // Create the device callback object.
    //
    HRESULT hr = CDevice::CreateInstance(&pDeviceCallback);

    //
    // Set device properties
    //
    if (S_OK == hr) {
        pDeviceInit->SetLockingConstraint(WdfDeviceLevel);
        // To register as the power-policy owner for 
        // the device stack, call the following:
        // pDeviceInit->SetPowerPolicyOwnership(TRUE);

        // For a filter driver, call the following:
        // pDeviceInit->SetFilter();
    }

    //
    // Request that the framework create a device object.
    // The device callback object is passed to inform the 
    // framework about the PnP callback functions the driver supports.
    //
    if (S_OK == hr) {
        hr = pDriver->CreateDevice(pDeviceInit, 
                                   pDeviceCallback,
                                   &pIWDFDevice);
    }

    //
    // Create the queue callback object.
    //

    if (S_OK == hr) {
        hr = CQueue::CreateInstance(&pIUnkQueue);
    }

    //
    // Configure the default queue. 
    // The queue callback object is passed to inform the 
    // framework about the queue callback functions the driver supports.
    //
    if (S_OK == hr) {
        IWDFIoQueue * pDefaultQueue = NULL;
        hr = pIWDFDevice->CreateIoQueue(
                       pIUnkQueue,
                       TRUE,                  // bDefaultQueue
                       WdfIoQueueDispatchParallel,
                       TRUE,                  // bPowerManaged
                       FALSE, //bAllowZeroLengthRequests
                       &pDefaultQueue);
        SAFE_RELEASE(pDefaultQueue);
    }

    SAFE_RELEASE(pDeviceCallback);
    SAFE_RELEASE(pIWDFDevice);
    SAFE_RELEASE(pIUnkQueue);    

    return hr;
}

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1,5
Header	wudfddi.h (termasuk Wudfddi.h)
DLL	WUDFx.dll