WdfDeviceCreate function (wdfdevice.h)
[Applies to KMDF and UMDF]
The WdfDeviceCreate method creates a framework device object.
Syntax
NTSTATUS WdfDeviceCreate(
[in, out] PWDFDEVICE_INIT *DeviceInit,
[in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
[out] WDFDEVICE *Device
);
Parameters
[in, out] DeviceInit
The address of a pointer to a WDFDEVICE_INIT structure. If WdfDeviceCreate encounters no errors, it sets the pointer to NULL.
[in, optional] DeviceAttributes
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new object. (The structure's ParentObject member must be NULL.) This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
[out] Device
A pointer to a location that receives a handle to the new framework device object.
Return value
If the WdfDeviceCreate method encounters no errors, it returns STATUS_SUCCESS. Additional return values include:
| Return code | Description |
|---|---|
| STATUS_INVALID_PARAMETER | An invalid Device or DeviceInit handle is supplied. |
| STATUS_INVALID_DEVICE_STATE | The driver has already created a device object for the device. |
| STATUS_INVALID_SECURITY_DESCR | The driver called WdfDeviceInitAssignSDDLString or WdfDeviceInitSetDeviceClass but did not provide a name for the device object. |
| STATUS_INSUFFICIENT_RESOURCES | A device object could not be allocated. |
| STATUS_OBJECT_NAME_COLLISION | The device name that was specified by a call to WdfDeviceInitAssignName already exists. The driver can call WdfDeviceInitAssignName again to assign a new name. |
For a list of other return values that WdfDeviceCreate can return, see Framework Object Creation Errors.
The method might return other NTSTATUS values.
Remarks
Before calling WdfDeviceCreate, the driver must call framework-supplied functions that initialize the WDFDEVICE_INIT structure. For more information about initializing this structure, see WDFDEVICE_INIT. If the driver encounters errors while calling the initialization functions, it must not call WdfDeviceCreate. In this case, the driver might have to call WdfDeviceInitFree. For information about when to call WdfDeviceInitFree, see WdfDeviceInitFree.
A call to WdfDeviceCreate creates a framework device object that represents either a functional device object (FDO) or a physical device object (PDO). The type of device object that the function creates depends on how the driver obtained the WDFDEVICE_INIT structure:
- If the driver received the WDFDEVICE_INIT structure from an EvtDriverDeviceAdd callback, WdfDeviceCreate creates an FDO.
- If the driver received the WDFDEVICE_INIT structure from an EvtChildListCreateDevice callback, or from a call to WdfPdoInitAllocate, WdfDeviceCreate creates a PDO.
Miniport drivers that use the framework must call WdfDeviceMiniportCreate instead of WdfDeviceCreate.
The parent of each framework device object is the driver's framework driver object. The driver cannot change this parent, and the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure must be NULL. The framework deletes each framework device object (except for some control device objects) when the Plug and Play (PnP) manager determines that the device has been removed.
If your driver provides EvtCleanupCallback or EvtDestroyCallback callback functions for the framework device object, note that the framework calls these callback functions at IRQL = PASSIVE_LEVEL.
For more information about creating device objects, see Creating a Framework Device Object.
Examples
The following code example shows how an EvtDriverDeviceAdd callback function might initialize and create a device object.
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;
}
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfdevice.h (include Wdf.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| DDI compliance rules | 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) |
See also
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE
WDF_PNPPOWER_EVENT_CALLBACKS_INIT