SetUserEventTimer

This method of the IUserEventTimer interface arranges for notification that a given amount of time has passed in which there was recurring user activity.

Declaration

HRESULT
SetUserEventTimer (
    HWND hWnd,
    UINT uCallbackMsg,
    UINT uTimerElapse,
    IUserEventTimerCallback *pUserEventTimerCallback,
    ULONG *puUserEventTimerID);

Parameters

The hWnd argument provides a handle to a window to which timeout notifications are to be posted, else is NULL to direct that timeouts be notified through a callback interface.

The uMsg argument provides the message number for timeout notifications that are posted to the window. This argument is ignored if hWnd is NULL.

The uTimerElapse argument provides the number of milliseconds of user-active time that is to pass between notifications.

The pUserEventTimerCallback argument provides a pointer to an IUserEventTimerCallback interface for an alternative method of timeout notification. This argument is ignored unless hWnd is NULL.

The puUserEventTimerID argument provides the address of a variable that supplies and/or receives a non-zero ID that represents the timer, both for use with other methods of this interface and in notifications of timeout expiry. If hWnd is NULL, then this argument is ignored on input, but an auto-generated ID is returned in the variable. If a window is given, this ID variable may

• be supplied as zero, to set a new user event timer for which an auto-generated ID is returned in the variable;
• supply an ID that is not already in use for the window, to set a new user event timer with the given ID;
• supply the ID of an existing user event timer for the window, to reset that timer.

Return Value

The function returns zero for success, else an error code.

Behaviour

If the internal timer is not yet initialised (which should not ordinarily be possible by the time this interface method can be called), the function fails, returning E_FAIL or E_OUTOFMEMORY.

If hWnd and pUserEventTimerCallback are both NULL, there can be notification of timeout expiry, and the function fails. If puUserEventTimerID is NULL, there is no means to learn of or return an ID for the timer, and the function fails. If uTimerElapse is zero, then there is no time to measure, and the function fails. In all these cases, the returned error code is E_INVALIDARG.

Window Notification

It is not an error to set both the hWnd and pUserEventTimerCallback arguments as non-NULL, but hWnd has precedence and pUserEventTimerCallback is ignored.

At each expiry of the timeout, a message is posted to the window whose handle was given in hWnd. The message number is whatever was given in uCallbackMsg. The message has wParam containing the timeout (i.e., uTimerElapse) and lParam containing the timer ID.

Note that a window-based timer is identified completely by the combination of hWnd and the non-zero ID that is returned (including if unchanged) in the variable at puUserEventTimerID. A window may set multiple timers, each with a different ID. Multiple timers, each set by a different window, may have the same ID.

Callback Notification

The callback interface is used only if hWnd is NULL. When notification by callback is selected, the uCallbackMsg argument is irrelevant and is ignored.

At each expiry of the timeout, the UserEventTimerProc method of the given IUserEventTimerCallback interface is called. As with notification by window message, the callback method is passed the timeout and the timer ID.

A callback-based timer is identified completely by the combination of hWnd, being NULL, and the non-zero ID that is returned in the variable at puUserEventTimerID. The ID is generated by the implementation so that it is necessarily different for different timers.