Función WdfWorkItemEnqueue (wdfworkitem.h)
[Se aplica a KMDF y UMDF]
El método WdfWorkItemEnqueue agrega un objeto de elemento de trabajo de marco especificado a la cola del elemento de trabajo del sistema.
Sintaxis
void WdfWorkItemEnqueue(
[in] WDFWORKITEM WorkItem
);
Parámetros
[in] WorkItem
Identificador de un objeto de elemento de trabajo de marco que se obtiene de una llamada anterior a WdfWorkItemCreate.
Valor devuelto
None
Observaciones
Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.
Una vez que el controlador llama a WdfWorkItemCreate para crear un elemento de trabajo, el controlador debe llamar a WdfWorkItemEnqueue para agregar el elemento de trabajo a la cola del elemento de trabajo del sistema. Posteriormente, un subproceso de trabajo del sistema quita el elemento de trabajo de la cola y llama a la función de devolución de llamada EvtWorkItem del elemento de trabajo. El sistema quita los elementos de trabajo en el orden en que se agregaron a la cola.
Antes de que los controladores llamen a WdfWorkItemEnqueue, normalmente usan la memoria de contexto del objeto de elemento de trabajo para almacenar información sobre el elemento de trabajo. La función de devolución de llamada EvtWorkItem usa esta información para determinar la operación que debe realizar.
En el caso de las versiones 1.7 y posteriores de KMDF, si el controlador reutiliza sus objetos de elemento de trabajo, el controlador puede llamar de nuevo a WdfWorkItemEnqueue para el mismo elemento de trabajo antes de que un subproceso de trabajo del sistema haya quitado la cola del elemento de trabajo y, posteriormente, llamara a la función de devolución de llamada EvtWorkItem del controlador. Sin embargo, KMDF no agregará el elemento de trabajo a la cola si ya está allí. Por lo tanto, la función de devolución de llamada EvtWorkItem debe procesar todo el trabajo en cola cada vez que se llama a él.
El controlador también puede llamar a WdfWorkItemEnqueue mientras se ejecuta una función de devolución de llamada EvtWorkItem para poner en cola otro elemento de trabajo. La segunda devolución de llamada evtWorkItem del elemento de trabajo podría incluso ejecutarse antes de que se complete la primera.
En versiones de KMDF anteriores a la versión 1.7, si el controlador reutiliza sus objetos de elemento de trabajo, no debe llamar de nuevo a WdfWorkItemEnqueue para el mismo elemento de trabajo hasta que un subproceso de trabajo del sistema haya quitado la cola del elemento de trabajo y llame a su función de devolución de llamada EvtWorkItem .
Para obtener más información sobre los elementos de trabajo, vea Uso de elementos de trabajo de Framework.
Ejemplos
Esta sección contiene dos ejemplos. En el primer ejemplo se muestra cómo agregar elementos de trabajo a una cola para las versiones 1.7 y posteriores de KMDF. En el segundo ejemplo se muestra cómo agregar elementos de trabajo a una cola para las versiones de KMDF anteriores a la versión 1.7
Ejemplo 1: VERSIONES 1.7 y posteriores de KMDF
En el ejemplo de código siguiente se llama a una rutina local que devuelve un puntero a la memoria de contexto de un objeto de elemento de trabajo. En el ejemplo se establece información en la memoria de contexto del objeto y, a continuación, se llama a WdfWorkItemEnqueue. La función de devolución de llamada EvtWorkItem del controlador recuperará más adelante la información del objeto de elemento de trabajo.
PMY_CONTEXT_TYPE context;
context = GetWorkItemContext(hWorkItem);
context->FdoData = FdoData;
context->Argument1 = Context1;
context->Argument2 = Context2;
WdfWorkItemEnqueue(hWorkItem);
La función de devolución de llamada EvtWorkItem del controlador contiene el código siguiente.
MyWorkItemCallback (
IN WDFWORKITEM hWorkItem
)
{
PMY_CONTEXT_TYPE context;
context = GetWorkItemContext(hWorkItem);
//
// Do work here.
//
...
//
return;
}
Ejemplo 2: versiones de KMDF anteriores a la 1.7
En el ejemplo de código siguiente se llama a una rutina local que devuelve un puntero a la memoria de contexto de un objeto de elemento de trabajo. En el ejemplo se establece información en la memoria de contexto del objeto, se establece una variable de estado en "busy" y, a continuación, se llama a WdfWorkItemEnqueue. La función de devolución de llamada EvtWorkItem del controlador recuperará más adelante la información del objeto de elemento de trabajo.
typedef enum _WORKITEM_STATE {
WORKITEM_STATE_FREE =0,
WORKITEM_STATE_BUSY = 1
} WORKITEM_STATE;
...
PMY_CONTEXT_TYPE context;
context = GetWorkItemContext(hWorkItem);
context->FdoData = FdoData;
context->Argument1 = Context1;
context->Argument2 = Context2;
if (InterlockedCompareExchange(
(PLONG)&context->WorkItemState,
WORKITEM_STATE_BUSY,
WORKITEM_STATE_FREE
) == WORKITEM_STATE_FREE) {
WdfWorkItemEnqueue(hWorkItem);
}
La función de devolución de llamada EvtWorkItem del controlador contiene el código siguiente. Justo antes de la instrucción return , el código establece la variable de estado del objeto de elemento de trabajo en "libre" para que el controlador pueda poner en cola el objeto de nuevo.
MyWorkItemCallback (
IN WDFWORKITEM hWorkItem
)
{
PMY_CONTEXT_TYPE context;
LONG result;
context = GetWorkItemContext(hWorkItem);
//
// Do work here.
//
...
//
// Reset object state.
//
result = InterlockedExchange(
(PLONG)&context->WorkItemState,
WORKITEM_STATE_FREE
);
ASSERT(result == WORKITEM_STATE_BUSY);
return;
}
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 (include Wdf.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <= DISPATCH_LEVEL |
| Reglas de cumplimiento de DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf) |