IWDFDriver：：CreateDevice 方法（wudfddi.h）

项目
02/07/2025

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。没有将新功能添加到 UMDF 1，并且对较新版本的 Windows 10 上的 UMDF 1 的支持有限。通用 Windows 驱动程序必须使用 UMDF 2。有关详细信息，请参阅 UMDF入门。]

CreateDevice 方法配置并创建新的框架设备对象。

语法

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

参数

[in] pDeviceInit

指向 IWDFDeviceInitialize 接口的指针，该接口表示要创建的新设备的配置属性。

[in, optional] pCallbackInterface

指向框架用于获取驱动程序为新设备对象提供的接口的 IUnknown 接口的指针。这些接口提供框架在发生相关事件时调用的回调函数。有关详细信息，请参阅以下“备注”部分。

[out] ppDevice

指向缓冲区的指针，该缓冲区接收指向新设备对象的 IWDFDevice 接口的指针。

返回值

如果作成功，CreateDevice 返回S_OK。否则，此方法返回在 Winerror.h 中定义的错误代码之一。

言论

驱动程序为 pCallbackInterface 参数提供的 IUnknown 接口可以支持多个接口。该框架多次调用提供的 IUnknown 接口的 QueryInterface 方法，以检索驱动程序支持的接口。驱动程序的 QueryInterface 方法可以返回以下接口：

IPnpCallbackHardware2

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPowerPolicyCallbackWakeFromS0

IPowerPolicyCallbackWakeFromSx

当设备更改状态时，框架将调用与更改相关的方法（如 IPnpCallback：：OnD0Entry 方法），以通知驱动程序。

如果调用 CreateDevice 成功，驱动程序最终必须调用 IWDFDevice：：Release 方法。请注意，框架对对象具有自己的引用计数。

有关详细信息，请参阅添加设备。

例子

下面的代码示例演示 IDriverEntry 接口的 OnDeviceAdd 方法的实现。将设备添加到计算机时，框架将调用 OnDeviceAdd。

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;
}

要求

要求	价值
终止支持	在 UMDF 2.0 及更高版本中不可用。
目标平台	桌面
最低 UMDF 版本	1.5
标头	wudfddi.h （包括 Wudfddi.h）
DLL	WUDFx.dll