Função KsAllocateDefaultClockEx (ks.h)

Artigo
02/29/2024

A função KsAllocateDefaultClockEx aloca e inicializa a estrutura de relógio padrão.

Sintaxe

KSDDKAPI NTSTATUS KsAllocateDefaultClockEx(
  [out]          PKSDEFAULTCLOCK     *DefaultClock,
  [in, optional] PVOID               Context,
  [in, optional] PFNKSSETTIMER       SetTimer,
  [in, optional] PFNKSCANCELTIMER    CancelTimer,
  [in, optional] PFNKSCORRELATEDTIME CorrelatedTime,
  [in, optional] const KSRESOLUTION  *Resolution,
  [in]           ULONG               Flags
);

Parâmetros

[out] DefaultClock

Especifica a estrutura de relógio padrão compartilhada alocada pelo chamador. A hora atual é definida como zero e o estado é definido como KSSTATE_STOP. Após a conclusão bem-sucedida dessa rotina, a estrutura indicada por esse ponteiro conterá uma referência ao relógio padrão. Os dados retornados devem ser tratados como opacos e reservados para uso do sistema.

[in, optional] Context

Opcionalmente, contém o contexto dos recursos de tempo alternativos. Isso deve ser definido se uma função de temporizador ou correlacionada for usada.

[in, optional] SetTimer

Opcionalmente, contém um ponteiro para uma função KStrSetTimer definida pelo driver a ser usada para gerar retornos de chamada de temporizador de DPC com base em um Tempo de Apresentação. Se isso for definido, a função será usada para definir temporizadores com base em deltas para o Tempo de Apresentação atual, a fim de gerar notificações de eventos. Se você fornecer uma função KStrSetTimer para definir temporizadores, também deverá fornecer uma função KStrCancelTimer correspondente. Passe NULL nesse parâmetro se a função KeSetTimerEx padrão for usada para aproximar a próxima hora de notificação. Normalmente, esse parâmetro seria definido somente se uma função KStrCorrelatedTime também estivesse sendo usada. A função KStrSetTimer deve ter as mesmas características que KeSetTimerEx.

[in, optional] CancelTimer

Opcionalmente, contém um ponteiro para uma função KStrCancelTimer definida pelo driver a ser usada para cancelar retornos de chamada de temporizador pendentes. Se você fornecer uma função KStrCancelTimer para cancelar temporizadores, também deverá fornecer uma função KStrSetTimer correspondente. Passe NULL nesse parâmetro se a função KeCancelTimer padrão for usada para cancelar temporizadores. A função KStrCancelTimer deve ter as mesmas características que KeCancelTimer.

[in, optional] CorrelatedTime

Opcionalmente, contém um ponteiro para uma função KStrCorrelatedTime definida pelo driver para recuperar a Apresentação e o Tempo Físico de maneira correlacionada. Isso permite que o proprietário do relógio determine completamente a hora atual. Passe NULL se a função KeQueryPerformanceCounter padrão for usada para regular a progressão de tempo.

[in, optional] Resolution

Opcionalmente, contém uma Granularidade alternativa e/ou Fator de erro para o relógio. Isso só poderá ser usado se um temporizador alternativo ou uma função de tempo correlacionada estiver sendo fornecida. Uma Granularidade alternativa poderá ser especificada se um tempo correlacionado alternativo estiver sendo usado, caso contrário, o elemento de estrutura deverá ser zero. Um Erro alternativo poderá ser especificado se um temporizador alternativo estiver sendo usado, caso contrário, o elemento de estrutura deverá ser zero.

[in] Flags

Reservado, definido como zero.

Retornar valor

A função KsAllocateDefaultClockEx retorna STATUS_SUCCESS se tiver êxito ou um erro de memória, se não for bem-sucedido.

Comentários

O elemento DefaultClock.ReferenceCount interno é inicializado para um pela função KsAllocateDefaultClock . O elemento é incrementado e decrementado à medida que cada DPC de notificação é enfileirada e concluída. Quando a estrutura deve ser liberada, o elemento é usado para determinar se o proprietário do relógio deve liberar a estrutura ou se um DPC pendente deve liberá-lo de forma assíncrona.