SetCoalescableTimer, fonction (winuser.h)

Article
08/28/2023

Crée un minuteur avec la valeur de délai d’attente et le délai de tolérance de fusion spécifiés.

Syntaxe

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

Paramètres

[in, optional] hWnd

Type : HWND

Handle de la fenêtre à associer au minuteur. Cette fenêtre doit appartenir au thread appelant. Si une valeur NULL pour hWnd est transmise avec un nIDEvent d’un minuteur existant, ce minuteur est remplacé de la même façon qu’un minuteur hWnd non NULL existant.

[in] nIDEvent

Type : UINT_PTR

Identificateur du minuteur. Si le paramètre hWnd est NULL et que nIDEvent ne correspond pas à un minuteur existant, nIDEvent est ignoré et un nouvel ID de minuteur est généré. Si le paramètre hWnd n’est pas NULL et que la fenêtre spécifiée par hWnd a déjà un minuteur avec la valeur nIDEvent, le minuteur existant est remplacé par le nouveau minuteur. Lorsque SetCoalescableTimer remplace un minuteur, le minuteur est réinitialisé. Par conséquent, un message est envoyé après l’expiration de la valeur de délai d’attente actuelle, mais la valeur de délai d’attente précédemment définie est ignorée. Si l’appel n’est pas destiné à remplacer un minuteur existant, nIDEvent doit avoir la valeur 0 si hWnd a la valeur NULL.

[in] uElapse

Type : UINT

Valeur du délai d'attente exprimée en millisecondes.

Si uElapse est inférieur à USER_TIMER_MINIMUM (0x0000000A), le délai d’expiration est défini sur USER_TIMER_MINIMUM. Si uElapse est supérieur à USER_TIMER_MAXIMUM (0x7FFFFFFF), le délai d’expiration est défini sur USER_TIMER_MAXIMUM.

Si la somme de uElapse et uToleranceDelay dépasse USER_TIMER_MAXIMUM, une exception ERROR_INVALID_PARAMETER se produit.

[in, optional] lpTimerFunc

Type : TIMERPROC

Pointeur vers la fonction à notifier lorsque la valeur du délai d’attente s’écoule. Pour plus d’informations sur la fonction, consultez TimerProc. Si lpTimerFunc a la valeur NULL, le système publie un message WM_TIMER dans la file d’attente de l’application. Le membre hwnd de la structure MSG du message contient la valeur du paramètre hWnd .

[in] uToleranceDelay

Type : ULONG

Ce peut être l’une des valeurs suivantes :

Valeur	Signification
TIMERV_DEFAULT_COALESCING 0x00000000	Utilise la fusion du minuteur par défaut du système.
TIMERV_NO_COALESCING 0xFFFFFFFF	N’utilise pas de fusion du minuteur. Lorsque cette valeur est utilisée, le minuteur créé n’est pas coalescé, quels que soient la fusion du minuteur système par défaut ou les indicateurs de compatibilité d’application. Note N’utilisez pas cette valeur, sauf si vous êtes certain que le minuteur ne nécessite pas de fusion.
0x1 - 0x7FFFFFF5	Spécifie le délai de tolérance de fusion, en millisecondes. Les applications doivent définir cette valeur sur la valeur par défaut du système (TIMERV_DEFAULT_COALESCING) ou sur la valeur la plus élevée possible. Si la somme de uElapse et uToleranceDelay dépasse USER_TIMER_MAXIMUM (0x7FFFFFFF), une exception de ERROR_INVALID_PARAMETER se produit. Pour plus d’informations et les meilleures pratiques, consultez Coalescing du minuteur Windows .
Toute autre valeur	Valeur non valide. Si uToleranceDelay est défini sur une valeur non valide, la fonction échoue et retourne zéro.

Valeur retournée

Type : UINT_PTR

Si la fonction réussit et que le paramètre hWnd a la valeur NULL, la valeur de retour est un entier identifiant le nouveau minuteur. Une application peut passer cette valeur à la fonction KillTimer pour détruire le minuteur.

Si la fonction réussit et que le paramètre hWnd n’est pas NULL, la valeur de retour est un entier différent de zéro. Une application peut passer la valeur du paramètre nIDEvent à la fonction KillTimer pour détruire le minuteur.

Si la fonction ne parvient pas à créer un minuteur, la valeur de retour est zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Une application peut traiter WM_TIMER messages en incluant une instruction case WM_TIMER dans la procédure de fenêtre ou en spécifiant une fonction de rappel TimerProc lors de la création du minuteur. Lorsque vous spécifiez une fonction de rappel TimerProc , la procédure de fenêtre par défaut appelle la fonction de rappel lorsqu’elle traite WM_TIMER. Par conséquent, vous devez distribuer des messages dans le thread appelant, même lorsque vous utilisez TimerProc au lieu de traiter WM_TIMER.

Le paramètre wParam du message WM_TIMER contient la valeur du paramètre nIDEvent .

L’identificateur du minuteur, nIDEvent, est spécifique à la fenêtre associée. Une autre fenêtre peut avoir son propre minuteur qui a le même identificateur qu’un minuteur appartenant à une autre fenêtre. Les minuteurs sont distincts.

SetTimer peut réutiliser les ID du minuteur dans le cas où hWnd a la valeur NULL.

Lorsque uToleranceDelay est défini sur 0, la fusion du minuteur système par défaut est utilisée et SetCoalescableTimer se comporte de la même façon que SetTimer.

Avant d’utiliser SetCoalescableTimer ou d’autres fonctions liées au minuteur, il est recommandé de définir l’indicateur de UOI_TIMERPROC_EXCEPTION_SUPPRESSION sur false via la fonction SetUserObjectInformationW . Sinon, l’application pourrait se comporter de manière imprévisible et pourrait être vulnérable aux attaques de sécurité. Pour plus d’informations, consultez SetUserObjectInformationW.

Spécifications


Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winuser.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll
Ensemble d’API	ext-ms-win-ntuser-window-l1-1-2 (introduit dans Windows 10, version 10.0.10240)