Función WdfDpcCreate (wdfdpc.h)

Artículo
08/08/2023

[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 para el 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 devuelto	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 miembro ParentObject 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 nivel de ejecución del objeto primario se establece en WdfExecutionLevelPassive.

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

Este método también podría devolver otros valores NTSTATUS.

Comentarios

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 miembro ParentObject 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 funciones de devolución de llamada EvtCleanupCallback o EvtDestroyCallback para el objeto del 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfdpc.h (incluya Wdf.h)
Library	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)