Função WdfWorkItemCreate (wdfworkitem.h)

[Aplica-se a KMDF e UMDF]

O método WdfWorkItemCreate cria um objeto de item de trabalho da estrutura, que pode ser adicionado posteriormente à fila de itens de trabalho do sistema.

Sintaxe

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

Parâmetros

[in] Config

Um ponteiro para uma estrutura de WDF_WORKITEM_CONFIG alocada pelo chamador que o driver já deve ter inicializado chamando WDF_WORKITEM_CONFIG_INIT.

[in] Attributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que especifica atributos para o objeto de item de trabalho.

[out] WorkItem

Um ponteiro para uma variável que recebe um identificador para o novo objeto de item de trabalho.

Retornar valor

WdfWorkItemCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi fornecido.
STATUS_INVALID_DEVICE_REQUEST	O pai do objeto de item de trabalho não é um objeto de dispositivo ou o ancestral de um objeto de dispositivo.
STATUS_INSUFFICIENT_RESOURCES	Não havia recursos suficientes do sistema para criar um objeto de item de trabalho.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	O membro AutomaticSerialization na estrutura WDF_WORKITEM_CONFIG para a qual o parâmetro Config aponta é TRUE, mas o nível de execução do objeto pai não é WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED	O parâmetro Attributes era NULL ou o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES especificada por Attributes era NULL.

Comentários

Depois que um driver chama WdfWorkItemCreate para criar um item de trabalho, ele normalmente armazena informações específicas do item na memória de contexto do objeto de item de trabalho. A função de retorno de chamada EvtWorkItem do driver, que executa as tarefas do item de trabalho, pode acessar essas informações para determinar as tarefas que ele deve executar. (Para obter mais informações sobre como armazenar informações na memória de contexto, consulte Espaço de contexto do objeto framework.)

Depois de armazenar informações de item de trabalho, o driver deve chamar WdfWorkItemEnqueue para adicionar o item de trabalho à fila de itens de trabalho do sistema. Quando um thread de trabalho do sistema fica disponível, o thread remove o item de trabalho da fila e chama a função de retorno de chamada EvtWorkItem .

Quando o driver cria um objeto de item de trabalho, ele deve especificar um objeto pai para o objeto de item de trabalho no membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES . O objeto pai deve ser um objeto de dispositivo de estrutura ou qualquer objeto cuja cadeia de pais leva a um objeto de dispositivo de estrutura. A estrutura excluirá o objeto de item de trabalho quando excluir o objeto do dispositivo.

Para excluir o objeto de item de trabalho anteriormente, o driver pode chamar WdfObjectDelete, conforme descrito em Usando itens de trabalho da estrutura.

O driver pode recuperar o objeto pai de um item de trabalho chamando WdfWorkItemGetParentObject.

Se o driver fornecer funções de retorno de chamada EvtCleanupCallback ou EvtDestroyCallback para o objeto de item de trabalho, observe que a estrutura chama essas funções de retorno de chamada em IRQL = PASSIVE_LEVEL.

Para obter mais informações sobre itens de trabalho, consulte Usando itens de trabalho da estrutura.

Exemplos

O exemplo de código a seguir inicializa uma estrutura WDF_OBJECT_ATTRIBUTES , inicializa uma estrutura WDF_WORKITEM_CONFIG e chama 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	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 da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Confira também

WdfWorkItemEnqueue