DOCUMENT:Q95783 12-NOV-1999 [win16sdk] TITLE :Compatibility Issues for Microsoft Windows Versions 3.x PRODUCT :Microsoft Windows Software Development Kit PROD/VER:WINDOWS:3.0,3.1 OPER/SYS: KEYWORDS:kb16bitonly ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Windows Software Development Kit (SDK) versions 3.0, 3.1 ------------------------------------------------------------------------------- SUMMARY ======= This article provides guidelines for writing applications for the Microsoft Windows versions 3.x operating system in a manner that will produce the fewest compatibility problems when the application is run on future versions of Windows. The discussion focuses on compatibility issues involving Windows-based applications, Windows display drivers, and MS-DOS-based applications. MORE INFORMATION ================ Guidelines for Windows-Based Application Developers --------------------------------------------------- Keep these general rules in mind when developing applications for Microsoft Windows: - The golden rule of application compatibility is to adhere to the Microsoft Windows Software Development Kit (SDK) documentation. That is, do not use an application programming interface (API) that is not documented, and use only the features of an API that are documented. - Do not depend on the format of internal data structures to remain the same in the future. For example, the format of the internal structures used for windows (HWND), menus (HMENU), device contexts (HDC), regions (HRGN), bitmaps (HBITMAP), and tasks (HTASK) are guaranteed to change in a future version of Windows. Other internal structures may also change. - Do not assume objects are allocated in User's or GDI's data segment. In an attempt to remove system resource limitations, objects that are currently allocated in these data segments may be allocated elsewhere in the future. For example, assuming a window handle is an offset in User's data segment will probably be incorrect in future versions of Windows. - Do not replace system dynamic-link libraries (DLLs) such as TOOLHELP.DLL, SHELL.DLL, and COMMDLG.DLL unless you use the version APIs (VER.DLL). These DLLs will change in the future. The system will malfunction if applications replace these DLLs with the earlier 3.0 or 3.1 version. If your application installs these DLLs, double-check the code for correctness; many applications that attempt this do not do it correctly. - Test the Windows version number properly. The following code, for example, does not work correctly if it is run on a version of Windows that is numbered 4.0 because the first test of the minor version will fail. Surprisingly, this is a very common mistake. winVer = LOWORD(GetVersion()); if (HIGHBYTE(winVer) >= 10 && LOWBYTE(winVer) >= 3) // run else // exit Use the following code instead: winVer = LOWORD(GetVersion()); winVer = (((WORD)(LOBYTE(winVer))) << 8)|(WORD)HIBYTE(winVer); if (winVer >= 0x030A) // NOTE: Always use a HEX value here!!! // run else // exit - Applications written for Windows versions 2.x will not be supported under future versions of Windows. Make sure your applications have been tested and built using any of the Windows versions 3.x SDKs so that they are marked as applications written for Windows version 3.0 or later and can run in protected mode. - Do not copy Program Manager group files onto a user's disk. Use the Program Manager's DDE interface to add groups and group items for your application. - Do not assume minimized application windows have icon title windows. If your application walks the window list and assumes that a window with a class name of "0x8004" or "#32772" is an icon title, the application will not function properly in future versions of Windows. If your application needs to perform this operation when running on Windows version 3.1, write your code so that the application will continue to work even if it does not find the icon title windows. - Do not hard-code the pixel dimensions of menus, scroll bars, sizes of captions, and so on. Instead, use GetSystemMetrics to get these sizes. The sizes will change depending on the active display driver, and may be user-adjustable in the future. Also, your code should watch for the WM_WININICHANGED message and reinitialize the values accordingly. - Do not hard-code button colors to be the standard three shades of gray. Use the GetSystemColors function to obtain these colors. Again, watch for the WM_WININICHANGED message, and reinitialize these colors accordingly. - Those writing debuggers must use the services provided by TOOLHELP.DLL, rather than the services provided by the earlier WINDEBUG.DLL. WINDEBUG.DLL will not work in future versions of Windows. - Do not assume that GlobalWire allocates MS-DOS addressable memory. Your application must use GlobalDOSAlloc to obtain this type of memory. - Do not assume that GlobalAlloc with the GMEM_FIXED option allocates MS-DOS addressable memory. Your application must use GlobalDOSAlloc to obtain this type of memory. - Printer soft font information is currently stored in WIN.INI and is associated with a particular port (LPT1, for example). In the future, this information will be associated with a printer in order to be independent of the port to which the printer is connected. - Your application must not assume the contents of any WINOLDAP (MS-DOS-based application manager) data structures allocated in WINOLDAP's data segment. These structures may change in the future. - Do not over tune your application's STACKSIZE or HEAPSIZE settings in the application's .DEF file. Some developers have tuned these settings (STACKSIZE, in particular) in their applications to supply exactly enough space to run on Windows version 3.0 or 3.1. These applications sometimes have problems because different Windows display drivers have different stack depth characteristics. Future versions of Windows will compound this problem because the stack depth will change for most of the core components (GDI, Kernel, User, and so forth). It is recommended that at least an additional 2K be added to the minimum STACKSIZE and HEAPSIZE settings. Guidelines for Display Driver Developers ---------------------------------------- Keep these points in mind when developing display drivers for Windows: - The meaning of the WindHand field in EXTPAINTSTRUC may be changed for enhanced-mode grabbers. WindHand is the HWND of the grabber child window inside the WINOLDAP window. All grabber painting should be restricted to this window. Grabbers were not supposed to use WindHand for anything beyond calling GetClientRect, GetDC, and so on. - Grabbers should not use the EPStatusFlags bits other than fFocus, fVValid, fSelect, and fGrbProb. Some bits that are private to WINOLDAPP were accidentally included in the DDK header files although not used in any Microsoft-distributed grabber sample source. Guidelines for MS-DOS-based Application Developers -------------------------------------------------- If you develop applications for MS-DOS, keep these rules in mind: - Make sure your application works properly in a Windows version 3.1 MS-DOS box. Especially, make sure your Setup program functions in a Windows MS-DOS box. For example, writing over Program Manager group files or altering WIN.INI or SYSTEM.INI while Windows is running would be improper things to do. Even though the application is MS-DOS-based, consider writing a Windows-based Setup program, especially if your setup process needs to perform operations such as altering WIN.INI or SYSTEM.INI. - Do not assume the location of the system file table (SFT) or MS-DOS buffers. These may be moved into high memory to provide extra conventional memory. In general, all internal MS-DOS data structures may be moved into high memory in the future. - Do not assume sizes of internal MS-DOS data structures. For example, do not assume that a drive parameter block (DPB) is 21h bytes long as some applications have. The format of data structures, such as these that are easy to find and traverse, may change in future versions of MS-DOS. Use documented Interrupt 21h calls to obtain information such as this. For example, DPBs can be obtained using Interrupt 21h functions, 1Fh, and 32h. Additional query words: no32bit 3.10 ====================================================================== Keywords : kb16bitonly Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK300 kbWinSDK310 Version : WINDOWS:3.0,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.