Función SetCoalescableTimer (winuser.h)

Artículo
08/28/2023

Crea un temporizador con el valor de tiempo de espera especificado y un retraso de tolerancia combinado.

Sintaxis

UINT_PTR SetCoalescableTimer(
  [in, optional] HWND      hWnd,
  [in]           UINT_PTR  nIDEvent,
  [in]           UINT      uElapse,
  [in, optional] TIMERPROC lpTimerFunc,
  [in]           ULONG     uToleranceDelay
);

Parámetros

[in, optional] hWnd

Tipo: HWND

Identificador de la ventana que se va a asociar al temporizador. Esta ventana debe ser propiedad del subproceso que realiza la llamada. Si se pasa un valor NULL para hWnd junto con un nIDEvent de un temporizador existente, ese temporizador se reemplazará de la misma manera que será un temporizador hWnd distinto de NULL existente.

[in] nIDEvent

Tipo: UINT_PTR

Un identificador de temporizador. Si el parámetro hWnd es NULL y nIDEvent no coincide con un temporizador existente, se omite nIDEvent y se genera un nuevo identificador de temporizador. Si el parámetro hWnd no es NULL y la ventana especificada por hWnd ya tiene un temporizador con el valor nIDEvent, el temporizador existente se reemplaza por el nuevo temporizador. Cuando SetCoalescableTimer reemplaza un temporizador, se restablece el temporizador. Por lo tanto, se enviará un mensaje una vez transcurrido el valor de tiempo de espera actual, pero se omite el valor de tiempo de espera establecido anteriormente. Si la llamada no está pensada para reemplazar un temporizador existente, nIDEvent debe ser 0 si hWnd es NULL.

[in] uElapse

Tipo: UINT

El valor del tiempo de espera, en milisegundos.

Si uElapse es menor que USER_TIMER_MINIMUM (0x0000000A), el tiempo de espera se establece en USER_TIMER_MINIMUM. Si uElapse es mayor que USER_TIMER_MAXIMUM (0x7FFFFFFF), el tiempo de espera se establece en USER_TIMER_MAXIMUM.

Si la suma de uElapse y uToleranceDelay supera USER_TIMER_MAXIMUM, se produce una excepción de ERROR_INVALID_PARAMETER.

[in, optional] lpTimerFunc

Tipo: TIMERPROC

Puntero a la función que se va a notificar cuando transcurre el valor de tiempo de espera. Para obtener más información sobre la función, vea TimerProc. Si lpTimerFunc es NULL, el sistema envía un mensaje WM_TIMER a la cola de la aplicación. El miembro hwnd de la estructura MSG del mensaje contiene el valor del parámetro hWnd .

[in] uToleranceDelay

Tipo: ULONG

Puede ser uno de los siguientes valores:

Valor	Significado
TIMERV_DEFAULT_COALESCING 0x00000000	Usa la fusión del temporizador predeterminado del sistema.
TIMERV_NO_COALESCING 0xffffffff	No utiliza ninguna fusión del temporizador. Cuando se usa este valor, el temporizador creado no se combina, independientemente de cuál sea el uso combinado del temporizador predeterminado del sistema o las marcas de compatibilidad de la aplicación. Nota No use este valor a menos que esté seguro de que el temporizador no requiere fusión.
0x1: 0x7FFFFFF5	Especifica el retraso de tolerancia de fusión, en milisegundos. Las aplicaciones deben establecer este valor en el valor predeterminado del sistema (TIMERV_DEFAULT_COALESCING) o en el valor más grande posible. Si la suma de uElapse y uToleranceDelay supera USER_TIMER_MAXIMUM (0x7FFFFFFF), se produce una excepción de ERROR_INVALID_PARAMETER. Consulta Fusión del temporizador de Windows para obtener más detalles y procedimientos recomendados.
Cualquier otro valor	Valor no válido. Si uToleranceDelay se establece en un valor no válido, se produce un error en la función y devuelve cero.

Valor devuelto

Tipo: UINT_PTR

Si la función se ejecuta correctamente y el parámetro hWnd es NULL, el valor devuelto es un entero que identifica el nuevo temporizador. Una aplicación puede pasar este valor a la función KillTimer para destruir el temporizador.

Si la función se ejecuta correctamente y el parámetro hWnd no es NULL, el valor devuelto es un entero distinto de cero. Una aplicación puede pasar el valor del parámetro nIDEvent a la función KillTimer para destruir el temporizador.

Si la función no puede crear un temporizador, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Una aplicación puede procesar WM_TIMER mensajes incluyendo una instrucción case de WM_TIMER en el procedimiento de ventana o especificando una función de devolución de llamada TimerProc al crear el temporizador. Cuando se especifica una función de devolución de llamada TimerProc , el procedimiento de ventana predeterminado llama a la función de devolución de llamada cuando procesa WM_TIMER. Por lo tanto, debe enviar mensajes en el subproceso de llamada, incluso cuando se usa TimerProc en lugar de procesar WM_TIMER.

El parámetro wParam del mensaje de WM_TIMER contiene el valor del parámetro nIDEvent .

El identificador del temporizador, nIDEvent, es específico de la ventana asociada. Otra ventana puede tener su propio temporizador que tiene el mismo identificador que un temporizador propiedad de otra ventana. Los temporizadores son distintos.

SetTimer puede reutilizar los identificadores de temporizador en el caso de que hWnd sea NULL.

Cuando uToleranceDelay se establece en 0, se usa el temporizador predeterminado del sistema y SetCoalescableTimer se comporta igual que SetTimer.

Antes de usar SetCoalescableTimer u otras funciones relacionadas con el temporizador, se recomienda establecer la marca de UOI_TIMERPROC_EXCEPTION_SUPPRESSION en false a través de la función SetUserObjectInformationW ; de lo contrario, la aplicación podría comportarse de forma impredecible y podría ser vulnerable a las vulnerabilidades de seguridad. Para obtener más información, consulta SetUserObjectInformationW.

Requisitos


Cliente mínimo compatible	Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluir Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-window-l1-1-2 (introducido en Windows 10, versión 10.0.10240)