Função WdfWorkItemEnqueue (wdfworkitem.h)
[Aplica-se a KMDF e UMDF]
O método WdfWorkItemEnqueue adiciona um objeto de item de trabalho de estrutura especificado à fila de itens de trabalho do sistema.
Sintaxe
void WdfWorkItemEnqueue(
[in] WDFWORKITEM WorkItem
);
Parâmetros
[in] WorkItem
Um identificador para um objeto de item de trabalho da estrutura obtido de uma chamada anterior para WdfWorkItemCreate.
Retornar valor
Nenhum
Comentários
Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.
Depois que o driver chama WdfWorkItemCreate para criar um item de trabalho, o driver deve chamar WdfWorkItemEnqueue para adicionar o item de trabalho à fila de itens de trabalho do sistema. Posteriormente, um thread de trabalho do sistema remove o item de trabalho da fila e chama a função de retorno de chamada EvtWorkItem do item de trabalho. O sistema remove os itens de trabalho na ordem em que foram adicionados à fila.
Antes que os drivers chamem WdfWorkItemEnqueue, eles normalmente usam a memória de contexto do objeto de item de trabalho para armazenar informações sobre o item de trabalho. A função de retorno de chamada EvtWorkItem usa essas informações para determinar a operação que deve ser executada.
Para as versões 1.7 e posteriores do KMDF, se o driver reutilizar seus objetos de item de trabalho, o driver poderá chamar WdfWorkItemEnqueue novamente para o mesmo item de trabalho antes que um thread de trabalho do sistema tenha desativado o item de trabalho e, posteriormente, chamado de função de retorno de chamada EvtWorkItem do driver. No entanto, o KMDF não adicionará o item de trabalho à fila se ele já estiver lá. Portanto, sua função de retorno de chamada EvtWorkItem deve processar todo o trabalho enfileirado sempre que for chamado.
Seu driver também pode chamar WdfWorkItemEnqueue enquanto uma função de retorno de chamada EvtWorkItem está em execução para enfileirar outro item de trabalho. O retorno de chamada EvtWorkItem do segundo item de trabalho pode até mesmo ser executado antes da conclusão do primeiro.
Em versões do KMDF anteriores à versão 1.7, se o driver reutilizar seus objetos de item de trabalho, ele não deverá chamar WdfWorkItemEnqueue novamente para o mesmo item de trabalho até que um thread de trabalho do sistema tenha desativado o item de trabalho e chamado sua função de retorno de chamada EvtWorkItem .
Para obter mais informações sobre itens de trabalho, consulte Usando itens de trabalho da estrutura.
Exemplos
Esta seção contém dois exemplos. O primeiro exemplo mostra como adicionar itens de trabalho a uma fila para as versões 1.7 e posteriores do KMDF. O segundo exemplo mostra como adicionar itens de trabalho a uma fila para versões KMDF antes da versão 1.7
Exemplo 1: kmdf versões 1.7 e posterior
O exemplo de código a seguir chama uma rotina local que retorna um ponteiro para a memória de contexto de um objeto de item de trabalho. O exemplo define informações na memória de contexto do objeto e chama WdfWorkItemEnqueue. A função de retorno de chamada EvtWorkItem do driver recuperará mais tarde as informações do objeto de item de trabalho.
PMY_CONTEXT_TYPE context;
context = GetWorkItemContext(hWorkItem);
context->FdoData = FdoData;
context->Argument1 = Context1;
context->Argument2 = Context2;
WdfWorkItemEnqueue(hWorkItem);
A função de retorno de chamada EvtWorkItem do driver contém o código a seguir.
MyWorkItemCallback (
IN WDFWORKITEM hWorkItem
)
{
PMY_CONTEXT_TYPE context;
context = GetWorkItemContext(hWorkItem);
//
// Do work here.
//
...
//
return;
}
Exemplo 2: versões do KMDF anteriores à 1.7
O exemplo de código a seguir chama uma rotina local que retorna um ponteiro para a memória de contexto de um objeto de item de trabalho. O exemplo define informações na memória de contexto do objeto, define uma variável de estado como "ocupado" e chama WdfWorkItemEnqueue. A função de retorno de chamada EvtWorkItem do driver recuperará mais tarde as informações do objeto de item de trabalho.
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);
}
A função de retorno de chamada EvtWorkItem do driver contém o código a seguir. Pouco antes da instrução return , o código define a variável de estado do objeto de item de trabalho como "livre" para que o driver possa enfileirar o objeto novamente.
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 |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Versão mínima do UMDF | 2,0 |
| Cabeçalho | wdfworkitem.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <= DISPATCH_LEVEL |
| Regras de conformidade de DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf) |