DOCUMENT:Q94925  12-JUN-1999  [win16sdk]
TITLE   :DOC: SetTimer() Unclearly Documented in Programmer's Ref
PRODUCT :Microsoft Windows Software Development Kit
PROD/VER:WINDOWS:3.1
OPER/SYS:
KEYWORDS:kbdocfix kb16bitonly kbSDKPlatform kbGrpDSUser kbWndwMsg

======================================================================
3.10
WINDOWS
kbprg kbdocerr

-------------------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Windows Software Development Kit (SDK) 3.1 
-------------------------------------------------------------------------------

SUMMARY
=======

The explanation of the SetTimer() function in the Windows 3.1 Software
Development Kit (SDK) "Programmer's Reference, Volume 2: Functions" is unclear
about the use of the idTimer parameter and the function's return value. For
example,

 - It should be more clearly explained that the idTimer parameter is used only
   if the value of hwnd is not NULL. If the hwnd parameter is NULL, SetTimer's
   return value is used for the timer ID.

 - The return value of SetTimer should be more clearly explained. That is, if
   the call to SetTimer successfully installs a timer, it returns a nonzero
   value; if the call fails to install a timer, it returns zero.

MORE INFORMATION
================

Below are excerpts from the Windows 3.1 SDK "Programmer's Reference, Volume 2:
Functions," followed by paragraphs that provide more details.

Page 874 states the following:

   idTimer

      Specifies a nonzero timer identifier. If the hwnd parameter is NULL,
      this parameter is ignored.

This could be replaced with the following:

   idTimer

      This value is used to specify a nonzero timer identifier if the hwnd
      parameter is not NULL. If hwnd is NULL, this parameter is ignored and
      cannot be used as a timer identifier.

The "Return Value" section on page 875 states the following:

The return value is the identifier of the new timer if hwnd is NULL and the
function is successful. An application passes this value to the KillTimer
function to kill the timer. The return value is nonzero if hwnd is a valid
window handle and the function is successful. Otherwise, the return value is
zero. Another way to explain the SetTimer() return value is as follows:

SetTimer returns a nonzero value if the timer was installed. If a timer could not
be installed, SetTimer returns zero.

If the hwnd parameter is NULL and SetTimer returns a nonzero value, the return
value specifies the timer ID to be used in a call to KillTimer.

If the hwnd parameter is not NULL and SetTimer returns a nonzero value, the
idTimer parameter specifies the timer ID to be used in a call to KillTimer. In
this case, the return value only signifies that SetTimer succeeded.

Charles Petzold's "Programming Windows" (Microsoft Press) contains an entire
chapter on using timers in Windows applications.

Additional query words: 3.10

======================================================================
Keywords          : kbdocfix kb16bitonly kbSDKPlatform kbGrpDSUser kbWndwMsg 
Technology        : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK310
Version           : WINDOWS:3.1

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 1999.