DOCERR: SetTimer() Unclearly Documented in Programmer's Ref

 Last reviewed: July 23, 1997
Article ID: Q94925
3.10 WINDOWS kbprg kbdocerr

The information in this article applies to:

  • Microsoft Windows Software Development Kit (SDK) for Windows version 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 reference words: 3.10
KBCategory: kbprg kbdocerr
KBSubcategory: UsrTim
Keywords : kb16bitonly

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.

Last reviewed: July 23, 1997
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.