WdfDpcCreate function (wdfdpc.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfDpcCreate method creates a framework DPC object and registers an EvtDpcFunc callback function.

Syntax

NTSTATUS WdfDpcCreate(
  [in]  PWDF_DPC_CONFIG        Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFDPC                 *Dpc
);

Parameters

[in] Config

A pointer to a caller-allocated WDF_DPC_CONFIG structure.

[in] Attributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies attributes for the new DPC object.

[out] Dpc

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

Return value

WdfDpcCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was specified.
STATUS_INSUFFICIENT_RESOURCES	A DPC object could not be allocated.
STATUS_WDF_PARENT_NOT_SPECIFIED	A parent object was not specified in the WDF_OBJECT_ATTRIBUTES structure.
STATUS_INVALID_DEVICE_REQUEST	The ParentObject member of the WDF_OBJECT_ATTRIBUTES structure does not reference a framework device object or an object whose chain of parents leads to a framework device object.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	The AutomaticSerialization member of the WDF_DPC_CONFIG structure is set to TRUE, but the parent object's execution level is set to WdfExecutionLevelPassive.

For a list of other return values that the WdfDpcCreate method might return, see Framework Object Creation Errors.

This method also might return other NTSTATUS values.

Remarks

A driver typically calls WdfDpcCreate from within its EvtDriverDeviceAdd callback function.

When a driver creates a DPC object, it must specify a parent object in the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure. The parent object can be a framework device object or any object whose chain of parents leads to a framework device object. The framework will delete the DPC object when it deletes the device object.

Calling WdfDpcCreate creates a framework DPC object and registers an EvtDpcFunc callback function. To schedule execution of the callback function, the driver must call WdfDpcEnqueue.

If your driver provides EvtCleanupCallback or EvtDestroyCallback callback functions for the framework timer object, note that the framework calls these callback functions at IRQL = PASSIVE_LEVEL.

For more information about using DPC objects, see Servicing an Interrupt.

Examples

The following code example initializes a WDF_DPC_CONFIG_INIT structure and then creates a DPC object.

WDF_DPC_CONFIG dpcConfig;
WDF_OBJECT_ATTRIBUTES dpcAttributes;
NTSTATUS status;

WDF_DPC_CONFIG_INIT(
                    &dpcConfig,
                    MyEvtDpcFunc
                    );
dpcConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&dpcAttributes);
dpcAttributes.ParentObject = pDevExt->WdfDevice;
status = WdfDpcCreate(
                      &dpcConfig,
                      &dpcAttributes,
                      &pDevExt->CompleteWriteDpc
                      );
if (!NT_SUCCESS(status)) {
    return status;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfdpc.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via