Função NdisSetCoalescableTimerObject (ndis.h)

Artigo
02/26/2024

A função NdisSetCoalescableTimerObject define um objeto de temporizador que o sistema operacional coordena com outros temporizadores, normalmente para reduzir o consumo de energia, quando a expiração exata do temporizador não é importante para a operação do driver.

Sintaxe

BOOLEAN NdisSetCoalescableTimerObject(
  [in]           NDIS_HANDLE   TimerObject,
  [in]           LARGE_INTEGER DueTime,
  [in, optional] LONG          MillisecondsPeriod,
  [in, optional] PVOID         FunctionContext,
  [in, optional] ULONG         Tolerance
);

Parâmetros

[in] TimerObject

Um identificador para um objeto de temporizador que o NDIS fornece quando um driver chama o Função NdisAllocateTimerObject .

[in] DueTime

O tempo absoluto ou relativo em que o temporizador expirará. Se o valor do parâmetro DueTime for negativo, o tempo de expiração será relativo à hora atual do sistema. Caso contrário, o tempo de expiração será absoluto. O tempo de expiração é expresso em unidades de tempo do sistema (intervalos de 100 nanossegundos). Os tempos de expiração absolutos acompanham as alterações na hora do sistema; os tempos de expiração relativos não são afetados pelas alterações de tempo do sistema.

[in, optional] MillisecondsPeriod

O intervalo de tempo periódico opcional, em milissegundos, decorrido entre cada instância quando o temporizador é acionado e a próxima chamada para a função NetTimerCallback , a menos que o temporizador seja cancelado. O valor desse parâmetro deve ser menor ou igual a MAXLONG. Esse parâmetro pode ser definido como zero para indicar que o temporizador não é periódico.

[in, optional] FunctionContext

Um ponteiro para uma área de contexto fornecida pelo chamador que o NDIS passa para a função NetTimerCallback associada quando um temporizador é acionado. Se esse parâmetro for NULL, o NDIS usará o valor padrão especificado no NDIS_TIMER_CHARACTERISTICS estrutura.

[in, optional] Tolerance

A tolerância, em milissegundos, entre o período de temporizador especificado por MilissegundosPeriod e o intervalo de tempo inicial especificado por DueTime . Um temporizador periódico expirará primeiro no intervalo de tempo entre (Tolerância ao DueTime - ) e (Tolerânciaa DueTime + ). O intervalo de tempo entre duas expirações posteriores de um temporizador periódico estará no intervalo de ( Tolerância a MilissegundosPeriod - ) e (Tolerânciaa MilissegundosPeriod + ).

Retornar valor

NdisSetCoalescableTimerObject retornará TRUE se o objeto de temporizador já estivesse na fila do temporizador do sistema; caso contrário, retornará FALSE.

Comentários

Um objeto timer definido por essa função opera o mesmo que um temporizador definido por NdisSetTimerObject, com um valor de tolerância adicional adicionado ao parâmetro de expiração DueTime . O sistema operacional usa esse valor de tolerância adicional para ajustar o tempo de expiração do temporizador para coincidir com a expiração de outros temporizadores de software. Ao fazer isso, o sistema operacional pode reduzir o consumo de energia e melhorar a eficiência energética.

NdisSetTimerObject opera de forma semelhante a NdisSetCoalescableTimerObject quando Tolerance é definido como zero.

Depois que um driver chama NdisSetCoalescableTimerObject, o objeto timer é enfileirado até a expiração de um intervalo que está no intervalo de (Tolerância ao DueTime - ) e (Tolerânciaao DueTime + ). Depois que o intervalo expira, o sistema operacional remove o objeto timer da fila e a função NetTimerCallback fornecida pelo chamador é executada uma vez em IRQL = DISPATCH_LEVEL assim que um processador fica disponível.

Se um valor diferente de zero for especificado no parâmetro MillisecondsPeriod, o objeto timer será enfileirado novamente até que um intervalo no intervalo de ( Tolerância de MilissegundosPeriod - ) e ( MillisecondsPeriod + Tolerance ) expire. Depois que esse intervalo expira, o objeto timer é reenviado para a fila e a função NetTimerCallback fornecida pelo chamador é executada uma vez em IRQL = DISPATCH_LEVEL assim que um processador fica disponível.

Para usar a união do temporizador com eficiência, um chamador deve especificar um valor de Tolerância de pelo menos 32 milissegundos. Esse valor é igual a aproximadamente dois intervalos padrão de relógio do sistema de 15,6 milissegundos. Use um valor de Tolerância maior se você puder fazer isso, como 100 milissegundos.

Recomendamos que MilissegundosPeriod e Tolerância sejam definidos como múltiplos de 50 milissegundos. Os valores típicos de MilissegundosPeriod são 50, 100, 250, 500 e 1000 milissegundos. Os valores típicos de Tolerância são 50, 100, 150 e 250 milissegundos.

Normalmente, um temporizador com um valor MilissegundosPeriod grande pode usar um valor de Tolerância proporcionalmente grande. Por exemplo, um temporizador com MilissegundosPeriod = 500 milissegundos pode usar Tolerância = 50 milissegundos. Mas um temporizador com MilissegundosPeriod = 10 segundos pode usar Tolerância = 1 segundo.

Para obter mais informações sobre o comportamento do temporizador, consulte KeSetTimerEx.

Para cancelar um temporizador, chame a função NdisCancelTimerObject .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.20 e posterior.
Plataforma de Destino	Universal
Cabeçalho	ndis.h (inclua Ndis.h)
Biblioteca	Ndis.lib
IRQL	<= DISPATCH_LEVEL