Función WdfDpcCreate (wdfdpc.h)

2025-03-22

[Solo se aplica a KMDF]

El método WdfDpcCreate crea un objeto DPC de marco y registra una función de devolución de llamada EvtDpcFunc.

Sintaxis

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

Parámetros

[in] Config

Puntero a una estructura de WDF_DPC_CONFIG asignada por el autor de la llamada.

[in] Attributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES asignada por el autor de la llamada que especifica atributos para el nuevo objeto DPC.

[out] Dpc

Puntero a una ubicación que recibe un identificador del nuevo objeto DPC de marco.

Valor devuelto

WdfDpcCreate devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los siguientes valores:

Código de retorno	Descripción
STATUS_INVALID_PARAMETER	Se especificó un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar un objeto DPC.
STATUS_WDF_PARENT_NOT_SPECIFIED	No se especificó un objeto primario en la estructura WDF_OBJECT_ATTRIBUTES.
STATUS_INVALID_DEVICE_REQUEST	El ParentObject miembro de la estructura WDF_OBJECT_ATTRIBUTES no hace referencia a un objeto de dispositivo de marco ni a un objeto cuya cadena de elementos primarios conduce a un objeto de dispositivo de marco.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	El miembro AutomaticSerialization de la estructura WDF_DPC_CONFIG se establece en TRUE, pero el de nivel de ejecución del objeto primario se establece en WdfExecutionLevelPassive.

Para obtener una lista de otros valores devueltos que podría devolver el método WdfDpcCreate, consulte Errores de creación de objetos de marco.

Este método también puede devolver otros valores de NTSTATUS.

Observaciones

Normalmente, un controlador llama a WdfDpcCreate desde su Función de devolución de llamada EvtDriverDeviceAdd.

Cuando un controlador crea un objeto DPC, debe especificar un objeto primario en el parentObject miembro de la estructura WDF_OBJECT_ATTRIBUTES. El objeto primario puede ser un objeto de dispositivo de marco o cualquier objeto cuya cadena de elementos primarios conduce a un objeto de dispositivo de marco. El marco eliminará el objeto DPC cuando elimine el objeto de dispositivo.

Al llamar a WdfDpcCreate se crea un objeto DPC de marco y se registra una función de devolución de llamada EvtDpcFunc. Para programar la ejecución de la función de devolución de llamada, el controlador debe llamar a WdfDpcEnqueue.

Si el controlador proporciona EvtCleanupCallback o EvtDestroyCallback funciones de devolución de llamada para el objeto de temporizador del marco, tenga en cuenta que el marco llama a estas funciones de devolución de llamada en IRQL = PASSIVE_LEVEL.

Para obtener más información sobre el uso de objetos DPC, vea Mantenimiento de una interrupción.

Ejemplos

En el ejemplo de código siguiente se inicializa una estructura de WDF_DPC_CONFIG_INIT y, a continuación, se crea un objeto DPC.

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;
}

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
encabezado	wdfdpc.h (incluya Wdf.h)
Biblioteca	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
irQL	<=DISPATCH_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)