IWDFDriver：：CreateDevice 方法 (wudfddi.h)

项目
03/05/2024

[警告： 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