Application Compatibility Guide

This guide is intended for application developers writing new applications for Microsoft® Windows® 2000 and Whistler operating systems. It can also help application developers who want to ensure that existing applications run well on these operating systems.

The Application Compatibility Guide consists of these parts:

Application Compatibility Overview

Common Application Compatibility Issues

Best Practices When Designing For Application Compatibility

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Application Compatibility Overview

The best way to enable your applications to take full advantage of the new Microsoft® Windows® 2000 and Whistler operating systems is to use the application programming interface described in the Microsoft® Platform Software Development Kit (SDK). This is also the best way to ensure that your applications run on future versions of the Windows operating system. For more information about the new technologies and features available in Whistler and Windows 2000, see What's New for Whistler Beta 2.

Applications that adhere to The Application Specification for Windows 2000 are compatible with Windows 2000 and use the new technologies this operating system provides. You can download the specification from the Microsoft Developer Network (MSDN) Web site.

Many application compatibility problems encountered by developers are due to a few new features and changes that have been made to the operating system. For a list of these, see Common Application Compatibility Issues. Your application can avoid problems with these issues by adhering to the points described in Best Practices When Designing for Application Compatibility. Adherence to these best practices when developing your application can prevent the majority of application compatibility problems.

In most cases, applications you have developed for earlier versions of Windows should perform well on Windows 2000 and Whistler. However, because Windows 2000 and Whistler are fundamentally new technologies, you still need to test your existing applications on the new operating system. Even if you currently use Microsoft Windows NT®, you should not assume that all your applications will work in the same way. You should also test to determine whether your existing applications still provide the best possible experience to your users. Many compatibility issues with existing application can be resolved by making full use of the new operating system enhancements.

Even if you are testing an application that you did not develop yourself, the Windows 2000 Application Specification and Best Practices When Designing for Application Compatibility can provide useful insight into how to test these applications.


Common Application Compatibility Issues

Before researching a problem as a operating system compatibility issue, be sure that the problem does not occur on your current platform. If your application does not run well on Microsoft® Windows® 2000 or Whistler, and you believe it is a compatibility problem, it may be due to one or more of the following new features or changes to the operating system. Your application can avoid problems in these areas by adhering to the points described in Best Practices When Designing for Application Compatibility.

Windows File Protection. Earlier versions of Windows allowed applications to replace shared system files during installation. Windows File Protection (WFP) verifies that protected system files are the correct Microsoft version. If a file is replaced with an incorrect version, WFP restores the correct version. For more information, see Do Not Overwrite System Files Covered by Window File Protection.

Robust Heap Checking. Performance enhancements have been introduced into the heap manager. Applications that did not use heap management correctly before might now have memory management problems exposed. Common problems include using memory after it has been freed and assuming that the memory location does not move when it is reallocated to a smaller size. For more information, see Do Not Read or Write From Freed Memory Blocks.

Enumeration of Hardware Devices. Changes in the list of supported hardware devices might cause problems for applications that use devices that are no longer supported.

Enumeration of Fonts. The list of fonts has changed. Because registry keys have been added to support internationalization, some applications might see multiple displays of fonts.

Changed Registry Keys. Some registry keys have been moved or deleted. Applications that use the Win32® application-programming interface (API) to make registry changes should not experience problems, but they can have problems if they write directly to the registry. For more information, see Use the Application Programming Interface to Get Registry Information.

Version Checking. The application is basically compatible but the installation program checks versions incorrectly. You should check for the minimum operating system version your application requires and install on that or any later version, unless your application is dependent on a specific operating system or version. This is the most common application compatibility problem. For more information, see Make Version Checking Compatible with Future Operating Systems.

Windows Messaging Service. Applications that expect Windows Messaging Service (WMS) to be provided by the operating system will not find it. You must obtain this service from the Windows Update Web site.

File Input/Output Security. Security for file input and output has been tightened. Applications that use file filters, such as antivirus programs, might lose significant functionality.


Best Practices When Designing for Application Compatibility

Many application compatibility problems encountered by developers are attributable to a few new features and changes that have been made to Whistler and Microsoft® Windows® 2000. For more information, see Common Application Compatibility Issues. The following is a list of some programming practices that help avoid these compatibility issues. Adherence to these best practices solves the majority of application compatibility problems.

  • Setup and Installation, Configuration, Version Checking
  • User Interface
  • Hardware, Input, Output, Threading
  • Networking and Security
  • General Programming Techniques


Setup and Installation, Configuration, Version Checking

The following sections describe setup and installation application compatibility guidelines:

  • Make Version Checking Compatible with Future Operating Systems
  • Install Start and Desktop Shortcuts into the Common Folders for All Users
  • Handle Reboot Requests Separately for Different Operating Systems
  • Do Not Overwrite System Files Covered by Window File Protection
  • Locate Directories Using the Application Programming Interface Not Hard-Coded Paths
  • Applications under Terminal Services Must Use GetSystemWindowsDirectory to Locate the System Folder
  • Check for Correct User Privileges
  • Use GetFileAttributes and Masking to Check File Attributes
  • Use the Application Programming Interface to Get Registry Information
  • Use the Application Programming Interface to Locate Special Folders
  • Use Isolated Applications and Side-by-Side Component Sharing to Reduce DLL Conflicts


Make Version Checking Compatible with Future Operating Systems

Your application should handle future version numbers of Windows correctly and always use a method of version checking that does the following:

  • Version checking should never prevent your application from running on a computer that has a system version equal to or greater than the most current Windows system version.
  • If your application should run on Windows 2000 and later versions, always use VerifyVersionInfo instead of GetVersionEx to check the system version. Applications must use this technique to meet the Certified for Windows 2000 application specification.

Faulty version checking is one of the most common reasons an existing application becomes incompatible. In most cases, program code that runs on Windows NT (major version 4) also works on Windows 2000 and Whistler (major version 5), and program code that runs on Windows 95, Windows 98, or Windows Me (major version 4) also works on Whistler (major version 5 and minor version 1).

The method used by your application to perform version checking should therefore never prevent your application from running on a computer that has a system version equal to or greater than the most current Windows system version. For example, if your method of version checking prevents the application from running whenever GetVersionEx returns a major version value less than 4, this prevents your application from running on Windows 2000 or Whistler. Microsoft can develop a utility for a specific application that changes the return value from GetVersionEx and enables such programs to be run by users.

For applications designed for Windows 2000 and later, use VerifyVersionInfo instead of GetVersionEx to check the system version. VerifyVersionInfo is available with Windows 2000 and later versions. Applications must use VerifyVersionInfo for version checking to meet the Certified for Windows 2000 application specification. VerifyVersionInfo compares a set of operating system version requirements to the corresponding values for the current operating system. VerifyVersionInfo does not prevent your application from running on future versions of the Windows operating system.

For examples, see Getting the System Version and Verifying the System Version.

When you use the Windows Installer to manage the setup of your application, the installation gets information about the operating system or installed software by calling the Windows Installer. For more information, see Operating System Properties in Windows Installer.


Install Start and Desktop Shortcuts into the Common Folders for All Users

To be compatible with Windows 2000 and Whistler, all of your application's shortcuts should be removed from the user's computer when the application is removed. For this reason, your application should always be installed to the common start menu or desktop folders available to all users.

Microsoft Windows NT enables users to install applications to a customized Start menu or desktop folder on a per-user basis or to the common folders used by all users. If an application is installed to a per-user folder, SHGetFolderPath may return a different CSIDL on installation and on removal. This may leave shortcuts behind on the user's computer when the application is removed.

When you use the Windows Installer to manage the setup for your application, during installation the installer retrieves the properties of many special folders. Provided you use the folder properties, the Windows Installer correctly evaluates the properties based upon the installation context. If you do a per-user installation, the value of those properties is the per-user location, and upon repair or removal of the application the value is the correct location. The also applies for a per-machine install because the installer uses the specific CSIDL. For more information, see Windows Installer and System Folder Properties.


Handle Reboot Requests Separately for Different Operating Systems

Your application should handle reboot requests separately for different operating systems and reboot the system no more than required for the appropriate system. Windows 2000 and Whistler do not require a reboot as often as earlier versions of Windows.

For example, when installing a DirectX application, do not assume that a reboot is always required to check for the DirectXSetup return value. If a reboot is necessary on Windows 2000 you must first acquire the appropriate security privileges before calling ExitWindowsEx.


Do Not Overwrite System Files Covered by Window File Protection

Your application should never attempt to overwrite a system DLL unless the application's DLL is a newer version than the system DLL. Windows File Protection (WFP) prevents the replacement of essential system files.

Replacement of protected system files is supported only through the following mechanisms. Attempting to replace protected files by other than these methods results in the original files being restored by WFP.

  • Windows 2000 Service Pack installation using Update.exe
  • Hotfixes installed using Hotfix.exe
  • Operating system upgrades using Winnt32.exe
  • Windows Update

Note that the Windows Installer adheres to Windows File protection and never attempts to install or replace a protected file. For more information, see Windows File Protection on Windows 2000 and Windows File Protection on Windows Millennium Edition.


Locate Directories Using the Application Programming Interface Not Hard-Coded Paths

Your application should use the functions SHGetFolderPath, GetWindowsDirectory, GetSystemDirectory, and GetTempPath to find directories used by Windows. Applications that use hard-coded paths to specific locations, may not work on other versions of Windows because the location of folders and directories can change with different versions of Windows.

For example, on Windows 95 and Windows 98, the My Documents folder is located at the root of the C or D drive. Windows NT 4.0 enabled users to create personal folders on a per-user basis, which were located in the Windows system directory: %windir%\profiles\user\personal. A default installation of Windows 2000 Professional puts the My Documents folder on the system drive at: \Documents and Settings\user\My Documents. In many enterprise situations, the user's My Documents folder may be moved off the local machine to a network share to makes it available to the user from anywhere by using roaming profiles.

To find shell folders such as My Documents, use SHGetFolderPath to get the path. You can use it on Windows 95, Windows 98, or any Windows platform. The following code snippet shows how to use SHGetFolderPath.

            // SHGetFolderPath can work everywhere SHFOLDER is installed.
            HMODULE hModSHFolder = LoadLibrary("shfolder.dll");
            if ( hModSHFolder != NULL )
               {
               (*(FARPROC*)&g_pfnSHGetFolderPath = GetProcAddress(hModSHFolder, "SHGetFolderPathA"));
               }
            else
               g_pfnSHGetFolderPath = NULL;
            }

   if (g_pfnSHGetFolderPath != NULL )
      g_pfnSHGetFolderPath(NULL, CSIDL_SYSTEM, NULL, NULL, szSystem32);
   else
      szSystem32[0] = '\0';
   OpenFileName.lpstrInitialDir   = szSystem32;

When you use Windows Installer to manage the setup of your application, the installer can search for a particular file or directory during an installation. For more information, see Searching for Existing Applications, Files, Registry Entries or .ini File Entries. in Windows Installer.


Applications under Terminal Services Must Use GetSystemWindowsDirectory to Locate the System Folder

To find the path to the Windows directory while running on Terminal Server, your application should call GetSystemWindowsDirectory. Calling the function GetWindowsDirectory while running on Terminal Server may instead return a path to a per-user Windows system directory set up for a particular user.

If the application is running in a Terminal Services environment, each user has a unique Windows directory. If an application that is not Terminal-Services-aware calls GetWindowsDirectory, it retrieves the path of the Windows directory on the client, not the Windows directory on the server.


Check for Correct User Privileges

A part of the operating system security of Windows 2000 and Whistler is the default access permissions granted to Administrators, Power Users, and Users. To be compatible with Windows 2000 and Whistler, Administrators and Power Users should be able to install your application system-wide for all of the user groups and Users should be able to install your application for their own use. You can manage your application's installation using Windows Installer.

Administrators can perform any and all functions. Any right that an administrator does not have by default, they can grant to themselves. The default Windows 2000 security settings do not restrict administrative access to any registry or file system object. Administrative access to the system should only be required to do the following tasks.

  • Install the operating system and components such as hardware drivers and system services.
  • Upgrade or repair the operating system and install Windows updates, Service Packs, or hotfixes.
  • Configure critical computer-wide system parameters such as kernel mode driver configuration, password policy, access control, and audit functions.
  • Install legacy Windows-based applications. Administrative access should be required to install such applications because they may replace operating system files during setup.

Power Users can perform any task except for the exclusive administrative tasks previously described. The default Windows 2000 security settings for Power Users are backward-compatible with the default security settings for Users in the Windows NT 4.0 operating system. Power Users cannot access other users' data stored on an NTFS partition. Power Users should be able to do the following tasks. Users cannot do these tasks.

  • Install and remove applications per computer that do not install system services.
  • Customize system-wide resources such as System Time, Display Settings, Shares, Power Configuration, and Printers.
  • Run legacy Windows-based applications installed by an Administrator.

Users should be able to perform any task except for the administrative and power user tasks described above. Users cannot modify computer-wide registry settings, operating system files, or program files. Users cannot install applications that can be run by other Users. Users cannot run applications installed by other Users. Users cannot access other users' private data.

  • Users should be able to run any application that has been previously installed by an Administrator or Power User.
  • A User should be able to install an application only for his or her own use.
  • Users should be able to run any application that complies with the Windows 2000 Application Specification a normal Users context.

Note that members of the Users group should not be able to run most legacy applications because most legacy applications were not designed with operating system security in mind.

If your application is a server application or installs a service, your application should check that it is logged into an account having sufficient permissions to install a service. Note that if your application currently uses an account that is not a member of a local administrator group, it may not have sufficient privileges to run the service on Windows 2000 or Whistler. Members of the Users group on Windows 2000 and Whistler have fewer permissions than unprivileged users on Windows NT 4.0. For example, unprivileged users cannot write into the Windows system directory. The default Windows 2000 security settings for Power Users are backward-compatible with the default security settings for Users in the Windows NT 4.0 operating system.

During setup your application should check to see whether the application is being installed by a user account having the privileges to write to HKEY_LOCAL_MACHINE. If your setup is not run by a user with write permissions to HKEY_LOCAL_MACHINE, the application should notify the user with a message such as, "You are not allowed to install this application for all users on this machine; do you want to install this application for personal use?" All users should be able to install an application for their own use.


Use GetFileAttributes and Masking to Check File Attributes

On Windows 2000 and later, your application should check for a file bit flag attribute by calling GetFileAttributes and using a mask rather than only checking for equality. For example, the following shows the correct way to check for the FILE_ATTRIBUTE_DIRECTORY attribute.

if( GetFileAttributes( "H:\Install" ) & FILE_ATTRIBUTE_DIRECTORY )
{
    // This is a directory!!
}


Use the Application Programming Interface to Get Registry Information

Because specific registry key information is not guaranteed to be present on all versions, your application should only get information about the operating system or installed software by calling the application programming interface. Applications should not retrieve information from the registry by other methods.

When you use the Windows Installer to manage the setup of your application, the installation can get information about the operating system or installed software by calling Windows Installer. For more information, see Searching for Existing Applications, Files, Registry Entries or .ini File Entries in Windows Installer.


Use the Application Programming Interface to Locate Special Folders

Whistler has new specialized folders to help users organize and retrieve documents and multimedia files. Your application should use the application programming interface in ShFolder.dll to locate special shell folders to ensure compatibility with earlier system versions. For more information, see Standard Shell Interfaces.

When you use Windows Installer to manage the setup for your application, during installation, the installer retrieves the properties of many special folders. For more information, see System Folder Properties in Windows Installer.


Use Isolated Applications and Side-by-Side Component Sharing to Reduce DLL Conflicts

If your application must consistently get the version of a component you have tested, it is possible to isolate the application with a copy of the tested component. This prevents your application from ever getting an untested component update that could cause a problem in the future. For more information, see Isolated Applications and Side-by-side Assembly Sharing.

Windows 2000 and Whistler enable you to create isolated applications (both IIS and Windows-client applications) and shared components. Developing isolated applications and shared components improves your application's reliability, stability, and resistance to DLL version conflicts by accomplishing the following:

  • The application always uses the versions of shared files with which it was deployed.
  • Installing the application does not overwrite other versions of the shared files by other applications.
  • Subsequent installations of other applications using different versions of the shared files cannot overwrite the files used by this application.

When you use Windows Installer to install your application, you can specify that the installer copy the critical files (commonly shared DLLs) into the application's folder rather than to a shared location. This private set of files (DLLs) are then used only by the application. For more information, see Isolated Components.


User Interface

The following sections describe user interface application compatibility guidelines:

  • Do Not Force a Window to the Foreground
  • Use DIALOGEX to Have the System Font
  • Check Custom Controls with the New Visual Styles
  • Test Your Application with Fast User Switching
  • Handle Multiple Monitors
  • Provide a User Interface Having the Best User Experience
  • Unset the File Attribute to Display Hidden System Files
  • Use Common File Dialog Boxes to Enable the Web Storage System and My Web Documents
  • Use Message Balloons Not Modal Dialogs for User Notification


Do Not Force a Window to the Foreground

Starting with Windows 98, your application can no longer simply rely on calling SetForegroundWindow to get the foreground window. The system restricts which processes can set the foreground window. For more information, see Foreground and Background Windows.


Use DIALOGEX to Have the System Font

Windows 2000 uses a different system font than Windows NT 4.0 and Windows 95/98. To have your application use the system font no matter which system it is running on, use DS_SHELLFONT with the typeface MS Shell Dlg, and use the DIALOGEX resource instead of the DIALOG resource. The system maps this typeface such that your dialog box uses the Tahoma font on Windows 2000 and the MS Sans Serif font on earlier systems. DS_SHELLFONT has no effect if the typeface is not MS Shell Dlg.

Starting with Windows 2000, if you specify the Dialog Box Template Style to DS_SHELLFONT you can change the font size but you can no longer change the font face. For more information, see Dialog Box Templates.


Check Custom Controls with the New Visual Styles

If your application uses custom controls, you should be sure to test your application with the new Common Controls version 6 that is included in Whistler. This control set has a new functionality, referred to as themes. The look and feel of theme-aware controls can change based on selected system themes. Some of your application's custom controls may need to be modified to use the new theme application programming interface. For more information, see Themes Overview.


Test Your Application with Fast User Switching

In Whistler, you do not have to log off to allow another user to log on. It is possible for multiple users to log on and switch quickly between open accounts. Switching to another account does not change the state of applications currently running. When a user switches back to their account, their applications will still be running and their network connections will have been preserved. For more information, see Fast User Switching.

If your application complies with the Application Specification for Windows 2000, it will work with fast user switching on Whistler. However, it is important to keep fast user switching in mind when developing an application so that it behaves as users would expect.

Use the following guidelines when writing your applications so that they work well with Fast User Switching:

Implement true profile separation. The system provides an underlying infrastructure that supports separation of user data, user settings, and computer settings. The best way to implement this is by using Windows Installer to manage the installation and setup of your application. For example, the installer sets the AppDataFolder property to the full path to the Application Data folder for the current user and sets the LocalAppDataFolder property to the full path to the directory for data that should not be available to the user on other computers, such as temporary files. You can also use the SHGetSpecialFolderLocation or SHGetSpecialFolderPath function with CSIDL_APPDATA or CSIDL_LOCAL_APPDATA to locate these folders.

Register for notification of a user switch. Typically, an application does not need to be notified when the switch occurs. However, if your application must be notified of a session change, it can be registered to receive a WM_WTSSESSION_CHANGE message. This message is sent only to applications that have registered to receive this message by calling WTSRegisterSessionNotification.

Shut down all instances of your application. Some applications need to shut down all instances of themselves. For example, an application that is run by two or more users simultaneously might need to download an update of itself off the Internet. To shut down all instances, create a unique named event and perform a wait operation. (To allow all users to use the object, create an ACL that grants access to the everyone SID.) When the wait has been satisfied, call the ExitProcess function.


Handle Multiple Monitors

For your applications to work best on Windows 98 and later, it should work on multiple display monitors. Your application must be able to handle negative screen coordinates and very large screen coordinates. If your application controls the position of windows, be sure to test your application on multiple monitors. For more information, see Multiple Display Monitors.


Provide a User Interface Having the Best User Experience

Test your applications with large fonts and icons to ensure that it provides the best user experience with high-resolution monitors. Starting with Whistler, the maximum dots per inch (dpi) setting for monitors is 480 dpi, which allows text that is not only more legible, but also of much higher quality than an equivalent 96 dpi monitor. Items that utilize this font feature are, for example, dialog boxes, buttons, title bars, and input by stylus, and speech.

Whistler supports 24-bit icons with 8-bit masks up to 128x128 pixels in size. These new icons are displayed in the shell when icon, thumbnail, or the new Tiles view is selected. Developers are encouraged to author 16x16, 32x32, and 48x48 icons for your applications and devices in this new color depth using the new icon tools and guidelines.

GDI+ C++ provides the industry's most feature-rich, best performing, and simplest to use 2D vector graphics, imaging, and typography solution for Windows and Web developers.


Unset the File Attribute to Display Hidden System Files

Starting with Windows 2000, it is possible to set both the system and hidden attributes on a file. For more information, see File Attributes. Files with both the system and the hidden attributes set are still in the operating system but are not displayed in Windows Explorer. This has no effect on the compatibility of 32-bit applications. Applications can still display and open these files in the Open File dialog box. The command line still works with these files.

If your 16-bit application calls INT21 on MS-DOS, a search for some hidden files only finds the hidden service file. Some of the files that remain hidden from a search are MS-DOS system files, such as io.dos, and Office Fast Find files.


Use Common File Dialog Boxes to Enable the Web Storage System and My Web Documents

Starting with Whistler, your application should be compatible with the Web Storage System and expose the new My Web Documents folder. The best way to do this is to use the common file dialogs. For more information, see Common Dialog Box Library. Note that your application may need to provide better progress indicators and more robust error handling for file transfers.

The Web Storage System is a database technology that you can use to store, share, and manage heterogeneous data, such as e-mail messages, Web pages, multimedia files, and Microsoft® Office 2000 documents. The My Web Documents is a folder that maps to a users personal presence site as determined by their passport. For more information, see Web Storage System Software Development Kit.


Use Message Balloons Not Modal Dialogs for User Notification

If your application sends messages to the user when it is not absolutely necessary to interrupt the user, your application should use a message balloon in the task bar notification area rather than a modal dialog box. On Whistler it is much easier to create a message balloon in the task bar notification area.

For more information, see the subheading titled "Adding, Modifying, and Deleting Icons in the Status Area" in The Taskbar.


Hardware, Input, Output, Threading

The following sections describe hardware, input, output, and threading application compatibility guidelines:

  • Use GetDiskFreeSpaceEx to Handle Large Hard Drives
  • Use DeviceIoControl and Control Codes to Retrieve the Physical Drive Number
  • Call ExpandEnvironmentStrings Before Reading REG_EXPAND_SZ
  • Handle Long File Names
  • Use CreateFile for Non-Buffered File I/O
  • Include the INF Files that Support Plug and Play of Network Devices
  • Use Removable Storage Manager to Access Tape Drives
  • Do Not Use Privileged Intel x86 Instructions for I/O or Performance Profiling
  • Use the Display Driver Management Level (DDML) to Enable Multiple Display Drivers
  • Use IMAPI to Create a CD-R/W
  • Use Autoplay Handlers to Simplify User Experience
  • Use WIA for Image Acquisition
  • Pass Keyboard Messages to TranslateMessage With No Alterations
  • Use Generic Thunking


Use GetDiskFreeSpaceEx to Handle Large Hard Drives

To be compatible with Windows 2000 and Whistler your application should work with large capacity hard drives. The size of hard drives has greatly increase over the years, and some older applications cannot handle large amounts of free disk space.

For example, the function GetDiskFreeSpace cannot report volume sizes that are greater than 2 gigabytes (GB). Your application should instead call GetDiskFreeSpaceEx to get the free space on large hard drives.


Use DeviceIoControl and Control Codes to Retrieve the Physical Drive Number

To be compatible with Windows 2000 and Whistler, your application may need to find the physical drive number using one of the following codes. The physical drive number is commonly needed only by applications that require low-level access to hard-drives and volumes, such as virus scanners.

On Windows NT 4.0, Windows 2000, or later, your application should call DeviceIoControl function with the following input and output control codes. For more information, see Calling DeviceIoControl on Windows NT/2000 or Device Input and Output Control Codes.

IOCTL_STORAGE_GET_DEVICE_NUMBER works for a single drive number. Use this code if the drive is a C drive or if you have multiple partitions on a single drive.

IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS works for multiple volume sets.


Call ExpandEnvironmentStrings Before Reading REG_EXPAND_SZ

Your application should call ExpandEnvironmentStrings before attempting to read the value of a REG_EXPAND_SZ registry data type. The REG_EXPAND_SZ is a null-terminated string that contains references to environment variables, such as "%PATH%". The REG_EXPAND_SZ data type was first introduced in Windows NT. Many older applications do not handle this data type. For more information, see Registry Data Types.

In the following, the string "%SystemRoot%" is replaced by the actual location of the directory containing the Windows NT system files:

File : REG_EXPAND_SZ : %SystemRoot%\file.exe


Handle Long File Names

To be compatible with Windows 2000 and Whistler, your application must work correctly with long file names and long printer names. Long file names and printer names were introduced with Windows NT and Windows 95.

For example, an application may use a smaller buffer than specified. Because the average lengths of paths have increased over time, this error may go undetected if the application has only been run on an older system. Your application should also handle spaces in directory names.

For more information, see Long File Names under File Name Conventions.


Use CreateFile for Non-Buffered File I/O

If your application performs file input or output without using the intermediate buffering or caching provided by the system, the application must call CreateFile with the FILE_FLAG_NO_BUFFERING flag set when opening the file. In this case, your application must pass a buffer to ReadFile or WriteFile that is correctly aligned for the device. Note that the alignments changed for some devices with Window 2000. For more information, see the FILE_FLAG_NO_BUFFERING description in the CreateFile section and the VirtualAlloc section.

One way to align buffers on integer multiples of the volume sector size is to use VirtualAlloc to allocate the buffers. This function allocates memory that is aligned on addresses that are integer multiples of the operating system's memory page size. Because both memory page and volume sector sizes are powers of 2, this memory is also aligned on addresses that are integer multiples of a volume's sector size. Your application must make sure that it reads and writes in multiples of the actual sector size of the input or output device. An application can determine a volume's sector size by calling the GetDiskFreeSpace function.

For more information, see Use GetDiskFreeSpaceEx to Handle Large Hard Drives.


Include the .inf Files that Support Plug and Play of Network Devices

Your application may require new .inf files to support Plug and Play of network devices on Windows 2000 and Whistler. These new files are also required to support Plug and Play of some network devices on Windows 98. Devices that require these new files include network drivers, transport drivers, and network file print providers.

For more information, see Universal Plug and Play and Plug and Play Device Management.


Use Removable Storage Manager to Access Tape Drives

If your application uses a tape drive, you'll need to change your application to access that tape using Removable Storage Manager. Removable Storage Manager (RSM) is a service in Windows 2000 that can manage removable media within a single-server system enable multiple applications to share local media libraries, tape drives, or disk drives. For more information, see Removable Storage Manager.


Do Not Use Privileged Intel x86 Instructions for I/O or Performance Profiling

Your application should not use Intel x86 instructions, including cli, sti, in, out, and any instructions that access the cr registers. These instructions cause the NT kernel to terminate the process.


Use the Display Driver Management Level (DDML) to Enable Multiple Display Drivers

Applications such as remote control applications that try to intercept calls to a display device should use the new Display Driver Management Level (DDML) to mirror the output to a remote device. This enables multiple display drivers, which is what these remote control applications are doing anyway. For more information about DDML, see the Microsoft Windows Driver Development Kits.


Use IMAPI to Create a CD-R/W

If your users would benefit from the capability to make a CD-R/W, your application can easily provide CD-R/W burning simply by handing files off to the Windows shell. On Whistler, the Image Mastering API (IMAPI) enables an application to write a simple audio or data image to a restricted set of CD-R or CD-R/W devices.


Use Autoplay Handlers to Simplify User Experience

AutoPlay is a new feature in Whistler that detects content such as pictures, music, or video files on removable media and removable devices. If your application handles these media types, your application should register Autoplay handlers so that common actions your application offers are listed when media with files of that type are inserted into a device.

AutoPlay automatically launches applications to play or display that content. This simplifies the user experience for users dealing with specialized peripheral devices such as MP3 players and digital photo readers as well as for users unfamiliar with the software necessary to access various content types.

For more information, see Using AutoPlay.


Use WIA for Image Acquisition

If your application collects still digital images, you can use the Windows Image Acquisition application programming interface to acquire and manage the images.

Windows Image Acquisition can be used in all applications based on Whistler and Windows Me operating systems.


Pass Keyboard Messages to TranslateMessage With No Alterations

Starting with Windows 2000, a new method is used to pass information from WM_KEYUP and WM_KEYDOWN messages. For users to obtain the full benefit of these changes, your application should always pass the wParam message parameter from WM_KEYUP and WM_KEYDOWN messages to TranslateMessage without altering it at all.


Use Generic Thunking

If your application makes use of 16-bit code, it should use the appropriate thunking model. Windows NT and Windows 2000 do not support flat thunks. If your application uses flat thunks, it cannot run on Windows NT or Windows 2000 unless you isolate your thunking code into platform-specific DLLs.

Windows 95/98 implements a thunking model called flat thunks. Flat thunks allow 32-bit code to call functions implemented in 16-bit code. They also allow 16-bit code to call functions implemented in 32-bit code. For more information, see Thunk Compiler.

Windows NT/Windows 2000 implements a thunking model called generic thunks, which allow 16-bit code to call functions implemented in 32-bit code. Although Windows 95/98 supports generic thunks, they do not support the underlying process model used by Windows NT/Windows 2000. This means that generic thunking code might not work identically under Windows 95/98 and Windows NT/Windows 2000. For more information, see Generic Thunks.


Networking and Security

The following sections describe networking and security application compatibility guidelines:

  • Specify NetBIOS or Use Other Interfaces
  • Enable QoS on Multimedia and Mission-Critical Networked Applications
  • Use Whistler Messaging Services for Chat
  • Integrate Your Application With Home Networking
  • Integrate Your Application with Online Services


Specify NetBIOS or Use Other Interfaces

Starting with Windows 2000, NetBIOS is no longer the default configuration. NetBIOS was a default configuration on Windows NT. If your application calls functions that use NetBIOS on a system without NetBIOS, the functions will return errors. Your application should handle this by instead using functions that do not depend on NetBIOS or by asking the user to enable NetBIOS.

The NetBIOS interface is provided primarily for existing legacy applications that use IBM NetBIOS 3.0 and that need to be ported to the Win32 API. New applications and applications not requiring compatibility with NetBIOS should use other interfaces, such as mailslots, named pipes, RPC, sockets, or distributed COM to accomplish tasks similar to those supported by NetBIOS. These interfaces are more flexible and portable than NetBIOS. For more information, see The NetBIOS Interface.

For more information, see Network Protocol Support in Windows.


Enable QoS on Multimedia and Mission-Critical Networked Applications

The goal of Quality of Service is to provide preferential treatment to certain subsets of data, enabling that data to traverse the traditionally best-effort Internet or intranet with higher quality transmission service. Quality of Service (QoS) in Windows 2000 is applicable to enhance multimedia applications, such as telephony and streaming media, and mission critical applications, such as database programs, transaction oriented applications, and mail programs.

Quality of Service in Windows 2000 is a collection of components that enable differentiation and management of higher quality data transmissions across the network. For more information, see Quality of Service.


Use Whistler Messaging Services for Chat

Whistler includes integrated messaging services based on MSN Messenger and a new SIP audio/video real-time communications (RTC) services.

For more information, see Windows Messenger.


Integrate Your Application With Home Networking

If your users will benefit from accessing multiple computers or peripheral devices, you should test that your application uses the protocols that work with Home Networking.

The Home Networking Wizard in Windows Millennium Edition (Me) and Whistler provides your customers with what they need to set up a computer on a home or small business network. Whistler enables users to configure capabilities such as Internet Connection Sharing and Personal Firewall on their home network.

For more information, see ICS Start Page.


Integrate Your Application with Online Services

If your application stores, prints, or otherwise processes files online, you can provide your users with an easy access point to all types of .NET services. On Whistler, third-party services can be hosted within Microsoft Web Publishing, Windows Image Acquisition, and Internet Photo Printing common dialogs.

For more information, see Microsoft Web Publishing SDK and Windows Image Acquisition.


General Programming Techniques

The following sections describe general programming techniques regarding application compatibility guidelines:

  • Check for Bit Flags by Masking
  • Do Not Rely on the Order in Which Messages are Received
  • Allocate a Sufficient Memory Stack Size
  • Do Not Read or Write From Freed Memory Blocks
  • Call CreateFile to Initialize the OPENFILENAME Structure
  • DirectX Applications Should Support Task Switching
  • Use RegOpenCurrentUse to Get a User that is not the Current User
  • Do Not Call the Win9x SMAP_LS Functions
  • Use Control Panel Applications


Check for Bit Flags by Masking

Your application should always check for the presence of bit flags by using a mask. Do not use an equality to check for the presence of a bit flag because new bit flags will be added in future operating system versions. The following snippet shows how to check whether the bit flag ODS_FOCUS is included in fItemState.

if (fItemState & ODS_FOCUS)


Do Not Rely on the Order in Which Messages are Received

Your application should not rely on the order in which it receives messages. If your application needs to rely on the order of messages, especially across threads, it must provide its own method for synchronization.

For example, when multiple threads are shut down, each posts a shut down message. Because of changes in the thread scheduler, applications should not assume that the order in which the messages are posted is the same as the order in which the thread actually shut down.


Allocate a Sufficient Memory Stack Size

If your application is compiling and linking to use small memory stacks, you may run out of stack memory space. Windows 2000 and Whistler requires more stack space than Windows NT 4.0. You may need to increase the stack space to run your application under Windows 2000 or Whistler.

Check this by inspecting the /STACK-linker option in your link line or the STACKSIZE .def file. Your linker may also support a command-line option for setting the stack size. For further details, see the documentation included with your linker. For more information, see Thread Stack Size.


Do Not Read or Write From Freed Memory Blocks

Changes in heap management can expose previously undetected bugs in the memory management of existing applications. Beginning with Windows NT 4.0 Service Pack 4, the heap manager was improved to be more efficient and faster on multiprocessor machines. Windows 2000 introduced additional changes. These enhancements did not change the application programming interface, but can expose previously undetected bugs in some applications.

Your application should not attempt to read or write data from a freed memory block. Previously, when you freed a block, that block would go the bottom of the unused block list and eventually it would be reused. Now, the last blocks that you used are cached and effectively go to the top of the unused block list, speeding up the entire system. This enhancement can expose bugs in applications that try to access memory after it's been freed. The application allocates memory, uses the block, frees the block, and then tries to read or write to it again. Because the memory is sitting in a block or a page that you already own, it's not going to cause an access violation. When the application allocates more memory the block gets reused and corrupts the old data.

Your application should not assume that reallocating formerly allocated memory to a smaller block does not move the block. In order to make better use of the space on a page, Windows 2000 and Windows NT 4.0 with Service Pack 4 might move an allocation if you've reallocated for a smaller block.


Call CreateFile to Initialize the OPENFILENAME Structure

The OPENFILENAME structure contains information that the operating system uses to initialize an Open or Save As dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure. For information, see OPENFILENAME and Open and Save As Dialog Boxes. For an example, see Opening a File.

Starting with Windows 2000, there was a change in the default directory initialized by the system and OPENFILENAME that may affect 16-bit applications. Starting with Windows 2000, the function OpenFile defaults to the My Documents folder as a shortcut if it does not find any files of the type specified. The OpenFile function is provided only for compatibility with 16-bit versions of Windows. New applications should use the CreateFile function to create, open, reopen, or delete a file.


DirectX Applications Should Support Task Switching

New DirectX applications should support task switching. Task switching enables a user to switch between multiple applications running on the computer. When an application is not the currently running as the foreground task, it can be swapped out of memory and onto disk by the operating system. The DirectX documentation contains information on how to properly design applications that safely support task switching.

On Windows 95 and Windows 98, some DirectX applications avoided supporting task switching by intercepting system key-press messages. On Window 2000, this can be done by using LowLevelKeyboardProc and SetWindowsHookEx to install a hook procedure that monitors low-level keyboard input events.


Use RegOpenCurrentUse to Get a User that is not the Current User

Applications should always use RegOpenCurrentUser to get information from a HKEY_CURRENT_USER key that is other than the current user. Other methods can return information for the wrong user.

For more information, see Use the Application Programming Interface to Get Registry Information.


Do Not Call the Win9x SMAP_LS Functions

The Win9x version of KERNEL32 facilitated porting of old DOS programs to Windows by allowing execution of 16-bit code in a 32-bit application through the SMAP_LS APIs. For more information, see MS-DOS – Based Applications. These functions are not supported on the Windows NT/2000 platform. On Windows NT, 16-bit applications execute in the virtual DOS machine (Ntvdm.exe), which runs the DOS or Win3.1 kernel in a sandbox to retain the operating system's stability. Because they are completely segregated from the NT kernel, it is not possible for the same process to run 16- and 32-bit code at the same time.


Use Control Panel Applications

Control Panel applications are special-purpose dynamic-link libraries (DLLs) that let users configure the environment of Windows. If you're writing a Control Panel Application, select the most appropriate category from Whistler's list of IDs and register it as an extended property.

For more information, see Control Panel Applications.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.