WdfDeviceMiniportCreate function (wdfminiport.h)

[Applies to KMDF only]

The WdfDeviceMiniportCreate method creates a framework device object that a miniport driver can use.

Syntax

NTSTATUS WdfDeviceMiniportCreate(
  [in]           WDFDRIVER              Driver,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]           PDEVICE_OBJECT         DeviceObject,
  [in, optional] PDEVICE_OBJECT         AttachedDeviceObject,
  [in, optional] PDEVICE_OBJECT         Pdo,
  [out]          WDFDEVICE              *Device
);

Parameters

[in] Driver

A handle to the driver's framework driver object, obtained by a previous call to WdfDriverCreate.

[in, optional] Attributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[in] DeviceObject

A pointer to a WDM DEVICE_OBJECT structure that represents the functional device object (FDO) for the miniport driver.

[in, optional] AttachedDeviceObject

A pointer to a WDM DEVICE_OBJECT structure that represents the next-lower device object in the device stack.

[in, optional] Pdo

A pointer to a WDM DEVICE_OBJECT structure that represents the physical device object (PDO) for the device.

[out] Device

A pointer to a location that receives a handle to the new framework device object.

Return value

If the WdfDeviceMiniportCreate method encounters no errors, it returns STATUS_SUCCESS. Additional return values include:

Return code	Description
STATUS_INSUFFICIENT_RESOURCES	A device object could not be allocated.

 

For a list of other return values that WdfDeviceMiniportCreate can return, see Framework Object Creation Errors.

The method might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

If your miniport driver uses the framework, the miniport driver should call WdfDeviceMiniportCreate when its port driver informs it that a device is available. Miniport drivers do not call WdfDeviceCreate.

Your miniport driver might receive its DeviceObject, AttachedDeviceObject, and PDO pointers from its port driver. For example, an NDIS miniport driver can obtain these pointers by calling NdisMGetDeviceProperty.

The following restrictions apply to framework device objects that a miniport driver obtains by calling WdfDeviceMiniportCreate:

• The device that the device object represents must support Plug and Play.
• The device object does not support any of the device object's event callback functions. Therefore, the port driver must handle all Plug and Play (PnP) and power management operations.
• The device object handle cannot be passed to WdfWmiProviderCreate, so the port driver must provide any required support for Windows Management Instrumentation (WMI).
• The device object handle cannot be passed to WdfIoQueueCreate, so the framework does not support I/O queues for miniport drivers.
• The device object handle cannot be passed to WdfInterruptCreate, so the framework does not support interrupt objects for miniport drivers.
• The device object handle cannot be passed to any general framework device object methods except WdfDeviceGetIoTarget, WdfDeviceWdmGetDeviceObject, WdfDeviceWdmGetAttachedDevice, and WdfDeviceWdmGetPhysicalDevice.
• The device object handle cannot be passed to any framework FDO methods except WdfFdoQueryForInterface.
• The device object handle cannot be passed to any framework PDO methods or to WdfChildListCreate, so the miniport driver cannot be a bus driver.
• The driver must eventually call WdfObjectDelete to delete the device object that WdfDeviceMiniportCreate creates.

Framework device objects that WdfDeviceMiniportCreate create can be used as a parent object for any subsequently created framework object.

In order to send I/O requests to I/O targets, the miniport driver might pass the device object handle to WdfDeviceGetIoTarget, WdfIoTargetCreate, or WdfUsbTargetDeviceCreateWithParameters.

The miniport driver can pass the device object handle to WdfDmaEnablerCreate if the device supports DMA operations.

For more information about miniport drivers, see Using Kernel-Mode Driver Framework with Miniport Drivers.

Examples

The following code example calls NdisMGetDeviceProperty to obtain DeviceObject, AttachedDeviceObject, and PDO pointers; initializes the device object's context space, and creates a miniport device object.

WDF_OBJECT_ATTRIBUTES  ObjectAttributes;

NdisMGetDeviceProperty(
                       MiniportAdapterHandle,
                       &Adapter->Pdo,
                       &Adapter->Fdo,
                       &Adapter->NextDeviceObject,
                       NULL,
                       NULL
                       );
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ObjectAttributes,
                                        WDF_DEVICE_INFO
                                        );
ntStatus = WdfDeviceMiniportCreate(
                                   WdfGetDriver(),
                                   &ObjectAttributes,
                                   Adapter->Fdo,
                                   Adapter->NextDeviceObject,
                                   Adapter->Pdo,
                                   &Adapter->WdfDevice
                                   );
if (!NT_SUCCESS (ntStatus)) {
    Status = NDIS_STATUS_FAILURE;
    break;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfminiport.h (include Wdfminiport.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

See also

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate

WdfDriverMiniportUnload