Función NdisSetCoalescableTimerObject (ndis.h)

Artículo
08/07/2023

La función NdisSetCoalescableTimerObject establece un objeto de temporizador que el sistema operativo coordina con otros temporizadores, normalmente para reducir el consumo de energía, cuando la expiración exacta del temporizador no es importante para el funcionamiento del controlador.

Sintaxis

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

Identificador de un objeto de temporizador que proporciona NDIS cuando un controlador llama al Función NdisAllocateTimerObject .

[in] DueTime

Hora absoluta o relativa en la que expirará el temporizador. Si el valor del parámetro DueTime es negativo, la hora de expiración es relativa a la hora actual del sistema. De lo contrario, la hora de expiración es absoluta. La hora de expiración se expresa en unidades de tiempo del sistema (intervalos de 100 nanosegundos). Los tiempos de expiración absolutos realizan un seguimiento de los cambios en la hora del sistema; Los tiempos de expiración relativos no se ven afectados por los cambios de hora del sistema.

[in, optional] MillisecondsPeriod

Intervalo de tiempo periódico opcional, en milisegundos, que transcurre entre cada instancia cuando se activa el temporizador y la siguiente llamada a la función NetTimerCallback , a menos que se cancele el temporizador. El valor de este parámetro debe ser menor o igual que MAXLONG. Este parámetro se puede establecer en cero para indicar que el temporizador no es periódico.

[in, optional] FunctionContext

Puntero a un área de contexto proporcionada por el autor de la llamada que NDIS pasa a la función NetTimerCallback asociada cuando se activa un temporizador. Si este parámetro es NULL, NDIS usa el valor predeterminado especificado en . NDIS_TIMER_CHARACTERISTICS estructura.

[in, optional] Tolerance

Tolerancia, en milisegundos, entre el período de temporizador especificado por MillisecondsPeriod y el intervalo de tiempo inicial especificado por DueTime . Un temporizador periódico expirará primero en el intervalo de tiempo entre (Toleranciaa DueTime - ) y (Tolerancia a DueTime + ). El intervalo de tiempo entre dos expiraciones posteriores de un temporizador periódico estará en el intervalo de ( MilisecondsPeriod - Tolerance ) y ( MilisecondsPeriod + Tolerance ).

Valor devuelto

NdisSetCoalescableTimerObject devuelve TRUE si el objeto del temporizador ya estaba en la cola del temporizador del sistema; de lo contrario, devuelve FALSE.

Comentarios

Un objeto de temporizador establecido por esta función funciona igual que un temporizador establecido por NdisSetTimerObject, con un valor de tolerancia adicional agregado al parámetro de expiración DueTime . El sistema operativo usa este valor de tolerancia adicional para ajustar la hora de expiración del temporizador para que coincida con la expiración de otros temporizadores de software. Al hacerlo, el sistema operativo puede reducir el consumo de energía y mejorar la eficiencia energética.

NdisSetTimerObject funciona de forma similar a NdisSetCoalescableTimerObject cuando Tolerance está establecido en cero.

Después de que un controlador llame a NdisSetCoalescableTimerObject, el objeto de temporizador se pone en cola hasta la expiración de un intervalo que se encuentra en el intervalo de (Tolerancia a DueTime) y (Toleranciaa DueTime + - ). Una vez expirado el intervalo, el sistema operativo quita el objeto de temporizador de la cola y la función NetTimerCallback proporcionada por el autor de la llamada se ejecuta una vez en IRQL = DISPATCH_LEVEL tan pronto como un procesador esté disponible.

Si se especifica un valor distinto de cero en el parámetro MillisecondsPeriod , el objeto de temporizador se pone en cola de nuevo hasta que expire un intervalo en el intervalo de ( MilisecondsPeriod - Tolerance ) y ( MilisecondsPeriod + Tolerance ). Una vez expirado este intervalo, el objeto de temporizador se vuelve a enviar a la cola y la función NetTimerCallback proporcionada por el autor de la llamada se ejecuta una vez en IRQL = DISPATCH_LEVEL tan pronto como un procesador esté disponible.

Para usar el temporizador fusionando eficazmente, un llamador debe especificar un valor de tolerancia de al menos 32 milisegundos. Este valor es igual a aproximadamente dos intervalos de reloj del sistema predeterminados de 15,6 milisegundos. Use un valor de tolerancia mayor si puede hacerlo, como 100 milisegundos.

Se recomienda establecer MilisecondsPeriod y Tolerance en múltiplo de 50 milisegundos. Los valores típicos de MilisecondsPeriod son 50, 100, 250, 500 y 1000 milisegundos. Los valores de tolerancia típicos son 50, 100, 150 y 250 milisegundos.

Normalmente, un temporizador con un valor millisecondsPeriod grande puede usar un valor de tolerancia proporcionalmente grande. Por ejemplo, un temporizador con MilisecondsPeriod = 500 milisegundos podría usar Tolerancia = 50 milisegundos. Pero un temporizador con MilisecondsPeriod = 10 segundos podría usar Tolerancia = 1 segundo.

Para obtener más información sobre el comportamiento del temporizador, vea KeSetTimerEx.

Para cancelar un temporizador, llame a la función NdisCancelTimerObject .

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con NDIS 6.20 y versiones posteriores.
Plataforma de destino	Universal
Encabezado	ndis.h (incluya Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL