Función WdfWorkItemCreate (wdfworkitem.h)

[Se aplica a KMDF y UMDF]

El método WdfWorkItemCreate crea un objeto de elemento de trabajo de marco, que posteriormente se puede agregar a la cola de elementos de trabajo del sistema.

Sintaxis

NTSTATUS WdfWorkItemCreate(
  [in]  PWDF_WORKITEM_CONFIG   Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFWORKITEM            *WorkItem
);

Parámetros

[in] Config

Puntero a una estructura de WDF_WORKITEM_CONFIG asignada por el autor de la llamada que el controlador debe haber inicializado llamando a WDF_WORKITEM_CONFIG_INIT.

[in] Attributes

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

[out] WorkItem

Puntero a una variable que recibe un identificador para el nuevo objeto de elemento de trabajo.

Valor devuelto

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

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se proporcionó un parámetro no válido.
STATUS_INVALID_DEVICE_REQUEST	El elemento primario del objeto de elemento de trabajo no es un objeto de dispositivo ni el antecesor de un objeto de dispositivo.
STATUS_INSUFFICIENT_RESOURCES	No había recursos del sistema suficientes para crear un objeto de elemento de trabajo.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	El miembro AutomaticSerialization de la estructura WDF_WORKITEM_CONFIG a la que apunta el parámetro Config es TRUE, pero el nivel de ejecución del objeto primario no es WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED	El parámetro Attributes era NULL o el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES que Attributes especifica era NULL.

Comentarios

Una vez que un controlador llama a WdfWorkItemCreate para crear un elemento de trabajo, normalmente almacena información específica del elemento en la memoria contextual del objeto de elemento de trabajo. La función de devolución de llamada EvtWorkItem del controlador, que realiza las tareas del elemento de trabajo, puede acceder a esta información para determinar las tareas que debe realizar. (Para obtener más información sobre cómo almacenar información en la memoria de contexto, vea Espacio de contexto de objetos de marco).

Después de almacenar la información del elemento de trabajo, el controlador debe llamar a WdfWorkItemEnqueue para agregar el elemento de trabajo a la cola del elemento de trabajo del sistema. Cuando un subproceso de trabajo del sistema está disponible, el subproceso quita el elemento de trabajo de la cola y llama a la función de devolución de llamada EvtWorkItem .

Cuando el controlador crea un objeto de elemento de trabajo, debe especificar un objeto primario para el objeto de elemento de trabajo en el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES . El objeto primario debe 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 de elemento de trabajo cuando elimine el objeto de dispositivo.

Para eliminar el objeto de elemento de trabajo anteriormente, el controlador puede llamar a WdfObjectDelete, como se describe en Uso de elementos de trabajo de Framework.

El controlador puede recuperar el objeto primario de un elemento de trabajo llamando a WdfWorkItemGetParentObject.

Si el controlador proporciona funciones de devolución de llamada EvtCleanupCallback o EvtDestroyCallback para el objeto de elemento de trabajo, 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 los elementos de trabajo, vea Uso de elementos de trabajo de framework.

Ejemplos

En el ejemplo de código siguiente se inicializa una estructura de WDF_OBJECT_ATTRIBUTES , se inicializa una estructura de WDF_WORKITEM_CONFIG y se llama a WdfWorkItemCreate.

NTSTATUS  status = STATUS_SUCCESS;
PWORKER_ITEM_CONTEXT  context;
WDF_OBJECT_ATTRIBUTES  attributes;
WDF_WORKITEM_CONFIG  workitemConfig;
WDFWORKITEM  hWorkItem;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &attributes,
                                       WORKER_ITEM_CONTEXT
                                       );
attributes.ParentObject = FdoData->WdfDevice;

WDF_WORKITEM_CONFIG_INIT(
                         &workitemConfig,
                         CallbackFunction
                         );

status = WdfWorkItemCreate(
                            &workitemConfig,
                            &attributes,
                            &hWorkItem
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfworkitem.h (incluya Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte también

WdfWorkItemEnqueue