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:

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

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

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate