SetCoalescableTimer, fonction (winuser.h)

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 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

Voir aussi

Exemple de minuteurs de fusion

Conceptuel

KeSetCoalescableTimer

KeSetTimer

KillTimer

MSG

Référence

Exemple

SetTimer

TimerProc

Minuteurs

Utilisation de minuteurs

WM_TIMER