IWDFDriver::CreateDevice method (wudfddi.h)
[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]
The CreateDevice method configures and creates a new framework device object.
Syntax
HRESULT CreateDevice(
[in] IWDFDeviceInitialize *pDeviceInit,
[in, optional] IUnknown *pCallbackInterface,
[out] IWDFDevice **ppDevice
);
Parameters
[in] pDeviceInit
A pointer to the IWDFDeviceInitialize interface that represents the configuration properties for the new device to create.
[in, optional] pCallbackInterface
A pointer to the IUnknown interface that the framework uses to obtain the interfaces that the driver provides for the new device object. These interfaces provide the callback functions that the framework calls when relevant events occur. For more information, see the following Remarks section.
[out] ppDevice
A pointer to a buffer that receives a pointer to the IWDFDevice interface for the new device object.
Return value
CreateDevice returns S_OK if the operation succeeds. Otherwise, this method returns one of the error codes that are defined in Winerror.h.
Remarks
The IUnknown interface that the driver supplies for the pCallbackInterface parameter can support several interfaces. The framework calls the QueryInterface method of the supplied IUnknown interface multiple times to retrieve the interfaces that the driver supports. The driver's QueryInterface method can return the following interfaces:
IPowerPolicyCallbackWakeFromS0
IPowerPolicyCallbackWakeFromSx
When the device changes state, the framework calls the method that is related to the change (such as the IPnpCallback::OnD0Entry method) to notify the driver.
If the call to CreateDevice is successful, the driver must eventually call the IWDFDevice::Release method. Note that the framework has its own reference count on the object.
For more information, see Adding a Device.
Examples
The following code example shows an implementation of the OnDeviceAdd method of the IDriverEntry interface. The framework calls OnDeviceAdd when a device is added to a computer.
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;
}
Requirements
Requirement | Value |
---|---|
End of support | Unavailable in UMDF 2.0 and later. |
Target Platform | Desktop |
Minimum UMDF version | 1.5 |
Header | wudfddi.h (include Wudfddi.h) |
DLL | WUDFx.dll |