Função WdfTimerCreate (wdftimer.h)

Artigo
02/29/2024

[Aplica-se a KMDF e UMDF]

O método WdfTimerCreate cria um objeto de temporizador de estrutura.

Sintaxe

NTSTATUS WdfTimerCreate(
  [in]  PWDF_TIMER_CONFIG      Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFTIMER               *Timer
);

Parâmetros

[in] Config

Um ponteiro para uma estrutura WDF_TIMER_CONFIG .

[in] Attributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que contém atributos de objeto para o novo objeto de temporizador.

[out] Timer

Um ponteiro para um local que recebe um identificador para o novo objeto de temporizador de estrutura.

Retornar valor

WdfTimerCreate 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_WDF_PARENT_NOT_SPECIFIED	O parâmetro Attributes era NULL ou o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES especificada por Attributes era NULL.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_INVALID_DEVICE_REQUEST	O membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES não fez 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_INSUFFICIENT_RESOURCES	Não havia memória suficiente.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	O membro AutomaticSerialization da estrutura WDF_TIMER_CONFIG foi definido como TRUE, mas o nível de execução do objeto de dispositivo pai foi definido como WdfExecutionLevelPassive.

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

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

Comentários

Quando o driver chama WdfTimerCreate, ele deve fornecer uma estrutura WDF_OBJECT_ATTRIBUTES e deve especificar um objeto pai no membro ParentObject da estrutura. 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 de temporizador quando excluir o objeto do dispositivo.

Depois de criar um objeto de temporizador, o driver deve chamar WdfTimerStart para iniciar o relógio do temporizador, independentemente de o temporizador ser periódico ou não.

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 objetos de temporizador de estrutura, consulte Usando temporizadores.

Exemplos

O exemplo de código a seguir inicializa uma estrutura WDF_TIMER_CONFIG e uma estrutura WDF_OBJECT_ATTRIBUTES e, em seguida, chama WdfTimerCreate.

WDF_TIMER_CONFIG  timerConfig;
WDF_OBJECT_ATTRIBUTES  timerAttributes;
WDFTIMER  timerHandle;
NTSTATUS  status;

WDF_TIMER_CONFIG_INIT(
                      &timerConfig,
                      MyEvtTimerFunc
                      );

timerConfig.AutomaticSerialization = TRUE;

WDF_OBJECT_ATTRIBUTES_INIT(&timerAttributes);
timerAttributes.ParentObject = DeviceHandle;

status = WdfTimerCreate(
                        &timerConfig,
                        &timerAttributes,
                        &timerHandle
                        );

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	wdftimer.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)