WdfDpcCreate method

[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

Config [in]

A pointer to a caller-allocated WDF_DPC_CONFIG structure.

Attributes [in]

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

Dpc [out]

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 codeDescription
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

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, KmdfIrql, KmdfIrql2

See also

WdfDpcEnqueue
WDF_DPC_CONFIG
WDF_DPC_CONFIG_INIT
WDF_OBJECT_ATTRIBUTES
WDF_OBJECT_ATTRIBUTES_INIT
EvtDpcFunc
EvtDriverDeviceAdd

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft