Chapter 1: Windows Fundamentals

 

Passing these requirements will help your application run in a stable and reliable manner on Windows operating systems.

Customer Benefits

Customers can be confident that a compliant product will not adversely affect the reliability of the operating system.

Requirements

1.1  Perform primary functionality and maintain stability

1.2  Provide 32-bit components and document any 16-bit code

1.3  Support Long File Names and UNC paths

1.4  Support printers with long names and UNC paths

1.5  Do not read from or write to Win.ini, System.ini, Autoexec.bat or Config.sys on any Windows operating system based on NT technology

1.6  Ensure non-hidden files outside of your application directory have associated file-types with icons, descriptions, and actions

1.7  Perform Windows version checking correctly

1.8  Support AutoPlay of compact discs

1.9  Any kernel mode drivers your application installs must pass verification testing on Windows 2000

1.10 Any hardware drivers included with your application must pass WHQL testing

References

How to Comply with Windows Fundamental Requirements

1.1  Perform primary functionality and maintain stability

Your application must perform its primary functions without compromising the stability of the operating system or your application. If your application is available on other Windows operating systems, your application must perform its primary functionality at least as well on Windows 2000 as it does on down-level versions of Windows.

For example:

  • If your application creates, edits and saves multi-page documents, it must not crash or hang, and it must not lose user's data when they create, edit, save, or open documents up to the maximum size you specify
  • If your application displays information about the folders on the user’s hard drive, it must not crash or destroy data if the user performs any of the menu functions in the application, such as creating new folders, moving them, or renaming them

Users must be able to use system features supported by Windows 2000 with your application. For example:

  • Windows 2000 supports mice with more than three buttons; your application should not crash, hang or lose data when the user presses any button on a supported mouse
  • Your application should not expect Windows 2000 system files or temporary folders to be on any particular drive letter or have any maximum or minimum size; Windows 2000 may be installed on drives larger than 9GB with drive letters other than C or D. The C: or boot drive can be quite small, under 100MB

For more information on primary functions and stability, see the "General Functionality and Stability Test Procedure for the Certified for Microsoft Windows Logo" located at: http://msdn.microsoft.com/certification/download.asp.

1.2  Provide 32-bit components and document any 16-bit code

An application must be a 32-bit executable file of the Portable Executable (PE) format. This means that all executable files, including dynamic-link libraries (DLLs) and executable (EXE) program files, must be 32-bit files. You can test for the correct executable format by using the VeriTest-Rational Install Analyzer tool available for free download from: www.veritest.com/mslogos/windows2000/Installation_analyzer.htm

If your application is not represented in PE format, for example, interpreted code, then the "run-time engine" must be a Win32-based executable file in PE format. For example, if you develop an application in Microsoft Access, your application is an .mdb file, not an .exe file. However, msaccess.exe is a Win32-based executable file in the PE format.

If you require 16-bit executable files or DLLs for backward compatibility and links to 16-bit products, you must provide a mechanism to ensure that the application continues to function properly if the user upgrades the operating system to Windows 2000. For more information, see: "Chapter 7: Application Migration".

Note   Whenever possible, you should avoid using any 16-bit code even for backward compatibility, because 64-bit versions of Windows will not support 16-bit code.
Note   Each 16-bit file must be tested as part of the Certification process to ensure that system stability is not compromised. This may require additional testing time and consequent additional charges by the testing agency. The time and charges will be determined on a case-by-case basis by the testing agency.
Important   When you submit your product for compliance testing, you must list the filename and fully explain the use of any 16-bit file your application could install. This must be done in the electronic Vendor Questionnaire you submit with your application.

1.3  Support Long File Names and UNC paths

If your application exposes filenames to users and/or allows users to enter file names, then your application must support all valid Win32 file names, including Long File Names (LFNs) and Universal Naming Convention (UNC) names. LFNs and UNC names may be longer than the names allowed by 16-bit Windows and legacy DOS applications, and they may contain characters that were not allowed in 16-bit Windows or DOS.

For example, your application must properly recognize and display the following paths:

C:\documents and settings\joe user\my documents\my letter.txt

C:\documents and settings\Joe [joeuser]\my documents\Ca$h;flow\
my letter to André.txt

D:\Our folder\project 10\project 11\project 12\project 13\
project 14\project 15\ project 16\project 17\project 18\project 19\
project 20\project 21\ project 22\project 23\project 24\project 25\
project 26\project 27\ project 28\project 29\project 30\filename.ext

\\server\sharename\joe user\my letter.txt  

All Win32 functions that create, open, locate and save files and folders use the constant MAX_PATH as the maximum buffer size for path information. Your application must allow users to create files with a total path length up to MAX_PATH, and your application must open any supported files the user creates, with your application and any other application, on paths up to MAX_PATH long. The MAX_PATH constant is defined in the platform SDK support file windef.h. In the current platform SDK, the value of MAX_PATH is "260." You should use the MAX_PATH constant name instead of coding the value in your application. Using the constant instead of the value will help you quickly adapt your application to future versions of Windows, which may support longer paths, but use the same constant name.

Note   Double Byte Character Set (DBCS) applications: DBCS-enabled ANSI applications are required to properly support LFNs with DBCS characters in the language they support (e.g., a Japanese application must handle all Japanese LFNs correctly). Applications that are submitted for any double byte language will be tested for compliance with this requirement using LFNs based on those character sets.
Exception   Applications may be exempted from supporting file names and paths that contain certain characters, provided: 1) the application reserves those characters for special use. For example, some applications allow users to open multiple files at once and use a semi-colon to separate file names; 2) the application can support those characters if the filename or path is enclosed in quotes; 3)This is documented in the vendor questionnaire.

1.4  Support printers with long names and UNC paths

Windows allows names for Printers up to 220 characters long. Your application must start and function without errors, even if the Windows default printer has a long name. If your application supports printing, your application must accept and display printer names up to 220 characters long (if any printers are displayed by name in the print dialogs), and print to devices with long names. Examples of long printer names are:

\\PrintServer44.domain.com\Duplex printer: number 0047 (accounting group)
Color laser - Research & Design Dept IP 123.456.78.9 see Fred or Wilma

Note   Commas and exclamation points are illegal printer name characters.
Note   Double Byte Character Set (DBCS) applications: DBCS-enabled ANSI applications are required to properly support printer names with DBCS characters in the language they support (e.g., a Japanese application must handle all Japanese long printer names correctly). Applications that are submitted for any double byte language will be tested for compliance with this requirement using long printer names based on those character sets.

1.5  Do not read from or write to Win.ini, System.ini, Autoexec.bat or Config.sys on any Windows operating system based on NT technology

Your application must not read from or write to Win.ini, System.ini, Autoexec.bat, or Config.sys on any Windows operating system based on NT technology. These files are not used by NT-based Windows operating systems and some users remove them.

Exception   You may write to these four files during installation only if your application needs to support legacy 16-bit code. The 16-bit code may read those files when the application runs. Windows 2000 security prevents Users from writing to any files in the %systemroot% folder and the 16-bit code will not be able to make changes to win.ini or system.ini when members of the Users group run your application. Running the application as a User is required for Certification for Windows 2000. All writes to and reads from win.ini, system.ini, autoexec.bat and config.sys must be documented in the Vendor Questionnaire

1.6  Ensure non-hidden files outside of your application directory have associated file-types with icons, descriptions, and actions

Every file that does not have the hidden bit set that your application creates outside its directory in "Program Files" (see: Requirement 2.4) must have an associated registered file-type. This includes:

  • Files created during installation
  • Implementation and data files
  • User created files that are native to your application

If the file-type is already registered, no action is required, though you may take over the file-type if you wish.

If the file-type is not already registered, you must do the following for each new file type:

  • Provide an icon so that none of the files that your application creates is identified by the default Windows icon
  • Provide a friendly type description, for example, "Outlook Offline Mail File"
  • Ensure that each file-type has an associated action when double-clicked (e.g. launch your application and load the file), or is designated as "NoOpen"

The NoOpen designation may be used for files that you don’t want users to open. When the user double-clicks a file marked as NoOpen, the operating system will automatically provide a message informing the user that the file should not be opened. If an action is later associated with a NoOpen file type, the NoOpen designation will be ignored.

Exception   If your application allows the user to save or export file types that aren’t native to your application, the user may choose to save a file as a type that has no association on the user’s computer. Your application may save the file as requested by the user, even though the file will have a default Windows icon.

Implementation details

To check if a file extension is already registered:

  • Under HKCR, look for the key that is named with the 3 (or more) character file extension, such as ".txt"; if the key with that file extension doesn't exist, you must register it (see below)

To register new file-types:

  • Create a file-type under HKCR

    The file-type is the unique identifier for all files with a given file extension. For example, "txtfile" is the file-type for files with the .txt extension. Note that multiple extensions can point to the same file-type. For example, ".txt" and ".log" both point to the same file-type, "txtfile." The default value for the file-type key is the "friendly name" that is displayed in Windows Explorer. For example, extensions that point to the "txtfile" key have the friendly name, "Text Document."

  • Under HKCR, create a three-character or longer extension for your file-type

    We recommend 4 or 5 characters since this will help avoid file-type collisions and will make the file-type easier to identify. Then set the default value for the file extension to point to the file-type you've just created. For example the default value for ".txt" is the file-type "txtfile".

To register an icon for a file type:

  • Under the file-type key, create the 'DefaultIcon' key as a REG_SZ or REG_EXPAND_SZ and point it to an icon you provide; for example, for "txtfile" the value is "%SystemRoot%\system32\shell32.dll,-152" meaning "use the 152nd icon in shell32.dll"

To identify a file as "No Open":

  • Under the file-type key, add the "NoOpen" Reg_SZ value. Custom text can then be added to the value if you would like to customize the message (see the "ocxfile" key in HKCR for an example)

Example: Registry structure to associate ".txt" file extension with "Txtfile" file type:

HKEY_CLASSES_ROOT\.txt
      (default) = "txtfile"

HKEY_CLASSES_ROOT\txtfile
         \DefaultIcon
            (default) = %SystemRoot%\system32\shell32.dll,-152
         \shell\open\command
            (default) = %SystemRoot%\system32\NOTEPAD.EXE %1

1.7  Perform Windows version checking correctly

Your application must verify that the operating system meets the minimum version requirements for your application. The application must also install and run on all later versions of that operating system.

For example, if the application requires Windows NT 4.0 with Service Pack 3 (SP3), your version checking should allow installation on Windows NT, Major Version 4, Minor Version 0, SP3, and it must also install on all operating system version numbers that are greater than this number (such as Windows NT 4.0 Service Pack 4 [SP4], Windows 2000, Windows 2000 with any subsequent Service Packs, and so on).

Exception   In certain cases it is acceptable to block install on later versions of the OS. If you choose to do this, you must: 1) Document this in the Vendor Questionnaire and explain the rationale, AND 2) Display a message to the user when blocking installation or execution that your application is not designed for the later OS version. Examples where this is appropriate would be for low-level disk utilities. In this case, running such an application on an OS for which the product was not tested for could potentially result in lost user data, if for example there were changes in the file system that the application was not aware of.

In general, you should use the GetVersionEx() API to determine the OS version. If you need to verify the version of an NT4 Service Pack prior to Service Pack 4, you should also query the following registry key to determine the SP level.

HKLM\system\CurrentControlSet\control\windows\CSDVersion

The values of CSDVersion will be 0x100 for Service Pack 1, 0x200 for Service Pack 2, etc. See below for code sample to determine the Service Pack level.

Code Sample to Verify the Windows Version Requirements

This code runs on all 32-bit Windows platforms:

BOOL bIsWindowsVersionOK(DWORD dwMajor, DWORD dwMinor, DWORD dwSPMajor )
{
OSVERSIONINFO osvi;
 
// Initialize the OSVERSIONINFO structure.
//
ZeroMemory(&osvi, sizeof(OSVERSIONINFO));
osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
GetVersionEx((OSVERSIONINFO*)&osvi);
 
// First the major version
if ( osvi.dwMajorVersion > dwMajor )
   return TRUE;
else if ( osvi.dwMajorVersion == dwMajor )
   {
   // Then the minor
   if (osvi.dwMinorVersion > dwMinor )
      return TRUE;
   else if (osvi.dwMinorVersion == dwMinor )
      {
      // OK, better check the Service Pack
      if ( dwSPMajor && 
          osvi.dwPlatformId == VER_PLATFORM_WIN32_NT )
         {
         HKEY   hKey;
         DWORD dwCSDVersion;
          DWORD dwSize;
         BOOL   fMeetsSPRequirement = FALSE;
 
         if (RegOpenKeyEx(HKEY_LOCAL_MACHINE,
            System\\CurrentControlSet\\Control\\Windows",
0, KEY_QUERY_VALUE, &hKey) == ERROR_SUCCESS)
            {
            dwSize = sizeof(dwCSDVersion);
            if (RegQueryValueEx(hKey, "CSDVersion",
               NULL, NULL,
(unsigned char*)&dwCSDVersion, 
&dwSize) == ERROR_SUCCESS)
               {
               fMeetsSPRequirement = 
(LOWORD(dwCSDVersion) >= dwSPMajor);
               }
             RegCloseKey(hKey);
             }
         return fMeetsSPRequirement;
         }
      return TRUE;
      }
   }
return FALSE;
}

1.8  Support AutoPlay of compact discs

For products distributed on CD-ROM or DVD-ROM, the first time the disc is inserted, your application must use AutoPlay to either prompt the user to install or to run the application. It is up to you whether AutoPlay is enabled on subsequent insertions of the CD-ROM/ DVD-ROM. In the case of products distributed on multiple discs, subsequent discs must either use the AutoPlay feature or behave during installation like a subsequent floppy disk; they must continue installation without prompting the user for action.

It is not acceptable to require the user to use Start/Run to launch the installation from the CD-ROM or DVD-ROM.

1.9  Any kernel mode drivers your application installs must pass verification testing on Windows 2000

Poorly written kernel mode drivers have the potential to crash the system. Therefore, it is critical that any application that includes kernel mode drivers, such as anti-virus products, be thoroughly tested to minimize this risk.

If your application includes any kernel mode drivers, each of these drivers must pass validation triggered by the Windows 2000 Driver Verifier Manager tool (Verifier.exe). Driver Verifier is located in the \system32 directory on Windows 2000 systems. For more information on using the Driver Verifier Tool and diagnosing driver problems see: www.microsoft.com/hwdev/driver/driververify.htm.

1.10 Any hardware drivers included with your application must pass WHQL testing

If your product includes drivers for hardware devices, these drivers must pass testing by Windows Hardware Quality Labs (WHQL). Please note that turn-around times at WHQL can be up to 30 days. For more information, see: www.microsoft.com/hwdev/winlogo.

How to Pretest Applications for Windows Fundamental Requirements

How to Pretest that Your Application is 32-bit

Use the VeriTest-Rational Install Analyzer for Windows 2000, available from: www.veritest.com/mslogos/windows2000/ OR you can use the Link utility in the Microsoft Platform SDK.

If you use the Link utility, at the command line, type: "link –dump –headers exename.exe | more". If your application is in the proper PE format, the output of this command will be:

Microsoft (R) COFF Binary File Dumper Version 5.12.8181
Copyright (C) Microsoft Corp 1992-1998. All rights reserved.

Dump of file exename.exe

PE signature found

File Type: EXECUTABLE IMAGE
.
.
.

You should not get the following output, which would be produced if the application were 16-bit:

Microsoft (R) COFF Binary File Dumper Version 5.12.8181
Copyright (C) Microsoft Corp 1992-1998. All rights reserved.

Dump of file exename.exe
LINK : warning LNK4095: " exename.exe" is an NE format executable; use EXEHDR to dump it
.
.
.

To Pretest for Entries in Win.ini, System.ini, Autoexec.bat, and Config.sys Files

  1. Create and save copies of these files before installing the application on a computer where Windows has been freshly installed.
  2. Install the application.
  3. Launch the application, exercise basic functionality, then close the application.
  4. Compare the installed version of the files to the saved version of the files, verifying that no changes have been made. The Install Analyzer will verify this for you.

To Test Whether Your Product Properly Handles Long File Names

LFNs must do the following:

  • Allow plus signs, periods, commas, semicolons, equal signs, and square brackets anywhere
  • Not save leading or trailing spaces

    You can test for this by typing " test " or similar text in the "Save As" dialog box. The program should strip the spaces and add an extension, returning the file name "test.ext".

    Note   The ANSI 0160 character, used as a non-breaking space character in many fonts, should always be retained, even if used as the leading or trailing character in folder and file names.
  • Support MAX_PATH characters (including the path and extension)
  • Test the following list of file names (not including the quotes), which should save to the hard disk as indicated (In the chart below, the number sign (#) indicates a spacebar space. ANSI 032):
If you type… It should be saved as
"test" "test.ext"
" test" "test.ext"
"test " "test.ext"
"test#;#+#,#=#[#]" "test#;#+#,#=#[#].ext"
"     test     " (non-breaking space characters ANSI 0160) "     test     .ext"
"…..test….." "…..test……ext"
"\\server\share one\folder three\file" "\\server\share one\folder three\file.ext"
NOTE   If you are typing a UNC or LFN name that contains spaces from a command line, you may need to enclose the name in quotes.

To Run Verification Tests on Kernel Mode Drivers

  1. Connect a kernel mode debugger to your test machine. Several suitable debuggers are available, including character mode and GUI debuggers, on the Windows 2000 SDK and DDK CDs, and on the Windows 2000 Symbols and Support CD.
  2. Install your application with its kernel mode drivers.
  3. Start Verifier.exe and select the Settings tab. Look for each driver’s name in the Driver list. Select each of your application’s drivers on the list and click Verify. If you don’t find one or more of the drivers’ names in the Driver list, enter the names in the "Verify these additional drivers after next reboot" edit box. Separate multiple driver names in the edit box with spaces and use only the name of the driver and its extension. Do not include path information.
  4. Check only these options in "Verification type":
    • Special pool
    • Force IRQL checking
    • Pool tracking
    • I/O verification
  5. Click Apply, Exit and reboot.
  6. After reboot, start your application and run a series of typical user tests. If the kernel detects any errors in your driver during boot or during the user tests, it will halt Windows 2000 and display the appropriate information on the character mode screen (blue screen) and on the kernel debugger. If pool corruption is indicated in the debugger, uncheck "Pool tracking" in "Verification type" and restart. When you’ve eliminated the errors, re-enable "Pool tracking" and retest.
  7. If you find no errors, restart Verifier.exe. Select each driver name again and click Verify, or enter the drivers’ names (filename.extension, without path) again in the "Verify these additional drivers after next reboot" edit box, separated by spaces.
  8. Uncheck all options in "Verification type", then check "Low resources simulation."
  9. Click Apply, then exit and reboot. Start your application and run a series of typical user tests.
  10. The low resources simulation option causes the Kernel to return invalid data and error codes to your driver periodically. As you run user tests, your driver should handle the invalid codes gracefully, perhaps by declining user requests or posting error dialogs. If your driver tries to use the invalid data or ignores error codes, your application will become unstable and fail. The exact symptoms vary with the application and purpose of the driver. The goal here is to ensure that your driver does not crash or hang the system. It is acceptable for applications using your driver to experience intermittent failures, but the system must NOT crash.
Show: