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 de elementos 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
Ninguno
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 del elemento de trabajo EvtWorkItem. 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 a WdfWorkItemEnqueue de nuevo para el mismo elemento de trabajo antes de que un subproceso de trabajo del sistema haya desqueuado el elemento de trabajo y, posteriormente, llamará a la función de devolución de llamada del controlador EvtWorkItem. Sin embargo, KMDF no agregará el elemento de trabajo a la cola si ya está ahí. Por lo tanto, el EvtWorkItem función de devolución de llamada 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. El segundo elemento de trabajo EvtWorkItem devolución de llamada podría incluso ejecutarse antes de que se complete el primero.
En versiones de KMDF anteriores a la versión 1.7, si el controlador reutiliza sus objetos de elemento de trabajo, no debe llamar a WdfWorkItemEnqueue de nuevo para el mismo elemento de trabajo hasta que un subproceso de trabajo del sistema haya desqueuado el elemento de trabajo y llame a su EvtWorkItem función de devolución de llamada.
Para obtener más información sobre los elementos de trabajo, vea Using Framework Work Items.
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 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. El ejemplo establece información en la memoria de contexto del objeto y, a continuación, llama a WdfWorkItemEnqueue. El controlador EvtWorkItem función de devolución de llamada 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 EvtWorkIte m 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 versión 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 "ocupado" y, a continuación, se llama a WdfWorkItemEnqueue. El controlador EvtWorkItem función de devolución de llamada 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 EvtWorkIte m del controlador contiene el código siguiente. Justo antes de que el devuelva instrucción, 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 | Valor |
---|---|
de la plataforma de destino de | Universal |
versión mínima de KMDF | 1.0 |
versión mínima de UMDF | 2.0 |
encabezado de | wdfworkitem.h (incluya Wdf.h) |
biblioteca de | 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) |