Função WdfDpcCreate (wdfdpc.h)

Artigo
03/05/2024

[Aplica-se somente ao KMDF]

O método WdfDpcCreate cria um objeto DPC de estrutura e registra uma função de retorno de chamada EvtDpcFunc .

Sintaxe

NTSTATUS WdfDpcCreate(
  [in]  PWDF_DPC_CONFIG        Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFDPC                 *Dpc
);

Parâmetros

[in] Config

Um ponteiro para uma estrutura de WDF_DPC_CONFIG alocada pelo chamador.

[in] Attributes

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

[out] Dpc

Um ponteiro para um local que recebe um identificador para o novo objeto DPC da estrutura.

Retornar valor

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

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um objeto DPC.
STATUS_WDF_PARENT_NOT_SPECIFIED	Um objeto pai não foi especificado na estrutura WDF_OBJECT_ATTRIBUTES .
STATUS_INVALID_DEVICE_REQUEST	O membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES não faz referência a um objeto de dispositivo de estrutura ou a um objeto cuja cadeia de pais leva a um objeto de dispositivo de estrutura.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	O membro AutomaticSerialization da estrutura WDF_DPC_CONFIG é definido como TRUE, mas o nível de execução do objeto pai é definido como WdfExecutionLevelPassive.

Para obter uma lista de outros valores retornados que o método WdfDpcCreate pode retornar, consulte Erros de criação de objeto de estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Comentários

Um driver normalmente chama WdfDpcCreate de dentro de sua função de retorno de chamada EvtDriverDeviceAdd .

Quando um driver cria um objeto DPC, ele deve especificar um objeto pai no membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES . O objeto pai pode 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 DPC quando excluir o objeto do dispositivo.

Chamar WdfDpcCreate cria um objeto DPC de estrutura e registra uma função de retorno de chamada EvtDpcFunc . Para agendar a execução da função de retorno de chamada, o driver deve chamar WdfDpcEnqueue.

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

Para obter mais informações sobre como usar objetos DPC, consulte Manutenção de uma interrupção.

Exemplos

O exemplo de código a seguir inicializa uma estrutura WDF_DPC_CONFIG_INIT e cria um objeto DPC.

WDF_DPC_CONFIG dpcConfig;
WDF_OBJECT_ATTRIBUTES dpcAttributes;
NTSTATUS status;

WDF_DPC_CONFIG_INIT(
                    &dpcConfig,
                    MyEvtDpcFunc
                    );
dpcConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&dpcAttributes);
dpcAttributes.ParentObject = pDevExt->WdfDevice;
status = WdfDpcCreate(
                      &dpcConfig,
                      &dpcAttributes,
                      &pDevExt->CompleteWriteDpc
                      );
if (!NT_SUCCESS(status)) {
    return status;
}

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfdpc.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)