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)

Confira também

EvtWorkItem

Interlockedcompareexchange

InterlockedExchange

WdfWorkItemCreate