WdfDeviceCreate method

[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

DeviceInit [in, out]: The address of a pointer to a WDFDEVICE_INIT structure. If WdfDeviceCreate encounters no errors, it sets the pointer to NULL.
DeviceAttributes [in, optional]: 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.
Device [out]: 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.

After the driver calls WdfDeviceCreate, it can no longer access the WDFDEVICE_INIT structure.

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

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, AddPdoToStaticChildList, ChangeQueueState, ChildDeviceInitAPI, ChildListConfiguration, ControlDeviceDeleted, ControlDeviceInitAllocate, ControlDeviceInitAPI, CtlDeviceFinishInitDeviceAdd, CtlDeviceFinishInitDrEntry, DeviceCreateFail, DeviceInitAllocate, DeviceInitAPI, DriverCreate, InitFreeDeviceCreate, InitFreeDeviceCreateType2, InitFreeDeviceCreateType4, InitFreeNull, KmdfIrql, KmdfIrql2, PdoDeviceInitAPI, PdoInitFreeDeviceCreate, PdoInitFreeDeviceCreateType2, PdoInitFreeDeviceCreateType4