Application Specification for Microsoft® Windows® 2000

          for desktop applications


 

Design Guide for Building

Business Applications

 

 

 

 

 

VERSION 1.0a

January 21, 2000

 

 

 

Microsoft Corporation


This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user.

The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in a written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Active Accessibility, Active Desktop, Active Directory, IntelliMirror, Microsoft, Microsoft Press, MSDN, Outlook, Windows, the Windows logo, Win32, Win64, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.

 

© 1998-2000 Microsoft Corporation. All rights reserved.

 


Acknowledgments

Microsoft wishes to thank the following organizations for their technical review, feedback, and consideration in the drafting of this specification. Their feedback was invaluable to help guide the content of this specification to better meet the needs of enterprise customers.

 

American International Group, Inc.

Carnegie Mellon University

Charles Schwab & Co., Inc.

CIGNA

Credit Suisse First Boston

Ford Motor Company

Nortel Networks

Pfizer, Inc.

The University of Texas at Austin – The Graduate School of Business

Warburg Dillon Read

 

 


Welcome

The Application Specification for Windows 2000 was developed by Microsoft in cooperation with customers and 3rd party developers to identify the technical definition of the model business application for Windows 2000. This specification will help software developers take advantage of the new technologies in Windows 2000 so that your application is more manageable, more reliable, and reduces cost of ownership for your customers. It is intended for developers of all kinds, including independent software vendors and corporate application developers.

The specification has two versions. This document details the requirements for desktop applications. There is a similar specification for building server applications, available at http://msdn.microsoft.com/certification.

 

Top reasons your customers will benefit

An application that meets this specification…

·         Provides a robust, self-repairing installation that helps minimize conflicts among shared components (i.e. “DLL Hell”) to enable better co-existence of applications.

·         Facilitates easier software deployment and management for organizations.

·         Correctly maintains user preferences and computer settings to help provide a good “roaming user” experience, support for multiple users per machine, and regeneration of application settings in machine replacement scenarios.

·         Runs in a tightly controlled network environment, to enable network administrators to secure and control corporate desktops.

·         Supports OnNow power management for a better mobile computing experience.

·         Supports accessibility standards to reduce support and training costs.

·         Provides a smooth transition of the application for users that upgrade from a previous version of Windows to Windows 2000 Professional (if certified on down-level operating systems).

Your customers will get the greatest benefits when running your application on Windows 2000 Professional. The same application can also run on down-level operating systems (e.g. Windows NT Workstation 4.0, Windows 98, and Windows 95). Many of these benefits will also accrue to customers running your application on down-level operating systems.


 

Certified for Windows

The Application Specification for Windows 2000 defines the technical requirements for applications to earn the “Certified for Microsoft Windows” logo. Applications may carry the “Certified for Microsoft Windows” logo once they have passed compliance testing and have executed a logo license agreement with Microsoft. This logo lets your customers know that your application offers a high quality computing experience on Windows. 

Applications that comply with this Desktop Specification may be Certified for any of the following operating systems:

·         Windows 2000 Professional

·         Windows NT Workstation version 4.0

·         Windows 98

·         Windows 95

You may choose from the combinations of platforms as shown in the logos below. Note that Windows 2000 Professional is always included.

        

The logo you receive will indicate the version(s) of Windows for which your product is certified. The checklist on the next page shows which parts of the specification are required for Certification on each platform.

Compliance testing for the Certified for Windows program is performed by VeriTest, an independent testing lab, using the latest released versions of the operating systems, including any service packs. Currently these are:

·         Windows 2000 operating systems

·         Windows NT Workstation 4, with Service Pack 6a and Internet Explorer 5

·         Windows 98 Second Edition

·         Windows 95 OSR2 with Internet Explorer 5

For additional information on how to test for the “Certified for Windows” logo, see http://www.veritest.com/mslogos/windows2000/

 

References

Resource

Address

“Certified for Windows” Logo Program

http://msdn.microsoft.com/certification

Server Application Specification for Windows 2000

http://msdn.microsoft.com/certification

Certified for Windows information e-mail

Winlogo@microsoft.com

VeriTest Logo site

http://www.veritest.com/mslogos/windows2000

VeriTest Logo Lab email

LogoLab@veritest.com

Windows 2000 Developer Information

http://msdn.microsoft.com/windows2000

Knowledge Base

http://www.microsoft.com/support/

Microsoft Platform SDK (Software Developer Kit)

     Documents the Win32® and Win64™      application programming interfaces (APIs).

Provided with Microsoft Developer Network (MSDN)      Professional Subscription. To subscribe, visit
     http://msdn.microsoft.com/subscriptions.


Checklist for Windows Certification

Win95

Win98

NTW 4

Win2000

 

 

 

 

 

Windows Fundamentals

X

X

X

X

1.1   Perform primary functionality and maintain stability

X

X

X

X

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

X

X

X

X

1.3   Support Long File Names and UNC paths

X

X

X

X

1.4   Support printers with long names and UNC paths

 

 

X

X

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

X

X

X

X

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

X

X

X

X

1.7   Perform Windows version checking correctly

X

X

X

X

1.8   Support AutoPlay of compact discs

 

 

 

X

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

 

X

X

X

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

 

 

 

 

 

 

 

 

 

Windows Installer Service

X

X

X

X

2.1   Install using a Windows Installer-based package that passes validation testing

X

X

X

X

2.2   Observe rules in componentization

X

X

X

X

2.3   Identify shared components

X

X

X

X

2.4   Install to Program Files by default

X

X

X

X

2.5   Support Add/Remove Programs properly

X

X

X

X

2.6   Ensure that your application supports advertising

X

X

X

X

2.7   Ensure correct uninstall support

 

 

 

 

 

 

 

 

 

Component Sharing

 

 

 

X

3.1   Do not attempt to replace files that are protected by Windows File Protection

 

X

 

X

3.2   Component producers: Build side-by-side components

 

X

 

X

3.3   Application developers: Consume and install side-by-side components

X

X

X

X

3.4   Install any non side-by-side shared files to the correct locations

 

 

 

 

 

 

 

 

 

Data and Settings Management

X

X

X

X

4.1   Default to My Documents for storage of user-created data

X

X

X

X

4.2   Classify and store application data correctly

 

 

X

X

4.3   Degrade gracefully on access denied

 

 

X

X

4.4   Run in a secure Windows environment

 

 

 

X

4.5   Adhere to system-level Group Policy settings

 

 

 

X

4.6   Applications that create ADM files must properly store their ADM file settings in the registry

 

 

 

 

 

 

 

 

 

User Interface Fundamentals

X

X

X

X

5.1   Support standard system size, color, font, & input settings

X

X

X

X

5.2   Ensure compatibility with the High Contrast option

X

X

X

X

5.3   Provide documented keyboard access to all features

X

X

X

X

5.4   Expose the location of the keyboard focus

X

X

X

X

5.5   Do not rely exclusively on sound

X

X

X

X

5.6   Do not place shortcuts to documents, help, or uninstall in the Start Menu

 

X

 

X

5.7   Support multiple monitors

 

 

 

 

 

 

 

 

 

OnNow/ACPI Support

 

X

 

X

6.1   For applications allowed to prevent sleep when busy, indicate busy application status properly

 

X

 

X

6.2   In the non-connected state, your application must allow sleep and resume normally

 

X

 

X

6.3   In the connected state, handle sleep notifications properly

 

X

 

X

6.4   Handle wake from normal sleep without losing data

 

X

 

X

6.5   Handle wake from critical sleep properly

 

 

 

 

 

 

 

 

 

Application Migration

X

X

X

 

7.1   Application must continue to function after upgrade to Windows 2000 Professional without reinstall


Contents

 

 

Acknowledgments____________________________________________________ iii

 

Welcome      _________________________________________________________ iv

 

Checklist for Windows Certification_______________________________________ vi

 

Chapter 1      Windows Fundamentals______________________________________ 1

Describes the requirements for consistent, stable functionality.

 

Chapter 2      Windows Installer Service___________________________________ 11

Describes the requirements for implementing the Windows Installer service, ensuring that the application can be easily deployed in a corporate environment.

 

Chapter 3      Component Sharing________________________________________ 18

Describes the requirements for handling shared components so that applications better coexist with one another.

 

Chapter 4      Data and Settings Management_______________________________ 24

Describes the requirements to ensure that applications support roaming users, multiple users per machine, and simplified machine replacement. Applications that meet these requirements can also operate properly in a secure Windows environment.

 

Chapter5      User Interface Fundamentals_________________________________ 33

Describes the requirements to provide an accessible user interface.

 

Chapter 6      OnNow/ACPI Support_______________________________________ 43

Describes the requirements for ensuring that the application can participate in system-wide power management.

 

Chapter 7      Application Migration_______________________________________ 50

Describes requirements for ensuring that an application continues to function correctly after the user upgrades to the Windows 2000 operating system.

 

Appendix A   Best Practices____________________________________________ 53

Best practices are not required for compliance with the Application Specification for Windows 2000, but are strongly encouraged to provide a better user experience.

 

Appendix B   Product Distribution Issues__________________________________ 63

 

Appendix C   Development Tools_________________________________________ 65

 

Appendix D   International and Localized Versions___________________________ 66

 

Appendix E   Revisions History__________________________________________ 67

 

Glossary       ________________________________________________________ 69

 


 

Chapter 1

Windows Fundamentals

Summary of Windows Fundamental Requirements

Describes the requirements for consistent, stable functionality.

Rationale

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

General Functionality and Stability Test Procedure for the Certified for Microsoft Windows Logo

http://msdn.microsoft.com/certification/download.asp.

VeriTest-Rational Install Analyzer for Windows 2000

 http://www.veritest.com/mslogos/windows2000

AutoPlay information and description

http://msdn.microsoft.com/library/techart/msdn_autoplay.htm

Supporting Long File Names

http://msdn.microsoft.com/isapi/msdnlib.idc?theURL=/library/psdk/winbase/filesio_7qwj.htm

Using Driver Verifier tool: http://www.microsoft.com/hwdev/driver/driververify.htm

 

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 http://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.

For more details on supporting valid Win32 long file names, see the Platform SDK and http://msdn.microsoft.com/isapi/msdnlib.idc?theURL=/library/psdk/winbase/filesio_7qwj.htm

 

Note on 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:

·          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.

·          The application can support those characters if the filename or path is enclosed in quotes.

·          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 that commas and exclamation points are illegal printer name characters.

 

Note on 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.  Note that 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. Note that 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 “NoOpenReg_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:

·          Document this in the Vendor Questionnaire and explain the rationale, AND

·          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 )

        {

        HKEYhKey;

        DWORD dwCSDVersion;

        DWORD dwSize;

        BOOLfMeetsSPRequirement = 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.

For more information on using AutoPlay, please see http://msdn.microsoft.com/library/techart/msdn_autoplay.htm

 

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. See http://www.microsoft.com/hwdev/driver/driververify.htm for more information on using the Driver Verifier Tool and diagnosing driver problems.

 

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 http://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 http://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.

 

·         You can also pre-test your application with the set of LFNs that VeriTest uses for testing compliance with Requirement 1.3. See the Windows 2000 Desktop Applications Test Plan, or the appropriate down-level Windows Test Plan,available at http://msdn.microsoft.com/certification/download.asp for details on using the LFN files.

 

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”:

a.   Special pool

b.   Force IRQL checking

c.   Pool tracking

d.   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.


Chapter 2

Describes the requirements for implementing the Windows Installer service, ensuring that the application can be easily deployed in a corporate environment.

Windows Installer Service

Summary of Windows Installer Service Requirements

Rationale

Install and uninstall issues are some of the most common sources of application interoperability problems. These requirements help to ensure that the user has successful installation and uninstallation experiences, and that the application co-exists in a friendly way with other applications.

The Windows Installer service is an operating system component that centrally manages application installation configuration, as well as application uninstall.  Using the Windows Installer service allows the operating system to manage application setup and configuration, which enables the following:

·         Management of reference counting and version checking of shared components, which helps ensure that applications better co-exist with one another.

·         Robust installations and self-repairing applications.

·         Reliable and complete uninstall, including correct handling of shared components.

·         Ability to perform installation on secure systems (for non-administrators and non-power users).

·         Enables applications to make full use of Windows 2000 IntelliMirror™ functionality for policy-based deployment, update, and uninstallation over a network.

 

The Windows Installer service enables all of this functionality using packages that describe application configurations. The Windows Installer ships in Windows 2000 and is also available for redistribution on Windows NT 4, Windows 98, and Windows 95.

Customer Benefits

End users gain these benefits when your application uses the Windows Installer service:

·         Fewer problems during application setup: installation and uninstallation of applications is less likely to affect the performance of another application because reference counting and version checking are properly implemented.

·         Self-repair of damaged applications at runtime: When the application is launched, the Windows Installer will check to ensure that the application is properly installed, and if it is not, will automatically repair the application on-the-fly.

·         Transacted install: In the event that the installation is not completed (for example, if there is a network failure), the Windows Installer can roll back to the earlier installed version of the application without error.

·         On-demand install of your application.

 

System administrators in corporate environments also gain these benefits when your application uses the Windows Installer service:

·         Ability to perform installation on secure systems (for non-administrators and non-power users) without having to visit the PC.

·         A Windows Installer-based package (.msi file) allows the administrator to easily determine what files, and what versions of those files, are being installed. This is especially beneficial for corporations that maintain a list of “known good versions” of shared DLLs and allow installation of applications that require a shared DLL only on the basis of this list.

·         The Windows Installer service management APIs can be used with management tools that allow files and application integrity to be remotely checked.

·         Application installation more readily supports roaming users via install on demand and indirection of file paths through the installer API's (reduced dependence on hard paths that may change across machines).

·         Application installation more readily supports mass deployment in organizations using Win2000 software management, and as a result of standard support for customization and unattended install.

 

Requirements

2.1     Install using a Windows Installer-based package that passes validation testing

2.2     Observe rules in componentization

2.3     Identify shared components

2.4     Install to Program Files by Default

2.5     Support Add/Remove Program Files properly

2.6     Ensure that your application supports advertising

2.7     Ensure correct uninstall support

 

References

Microsoft Platform SDK: Windows Installer Programmer’s Reference

Windows Installer SDK (includes msival2.exe and logo.cub file):

http://www.microsoft.com/msdownload/platformsdk/WinInst.htm 

 

 

How to Comply with Windows Installer Requirements

2.1    Install using a Windows Installer-based package that passes validation testing

Your application must install itself using the Windows Installer service. To do this, your install must be in the form of a Windows Installer-based package. You must validate that the package is properly constructed by running an Internal Consistency Evaluation tool (such as msival2.exe, available in the Windows Installer SDK) in conjunction with the suite of ICEs contained in the file named logo.cub. These are available from the Windows Installer SDK at http://www.microsoft.com/msdownload/platformsdk/WinInst.htm. You can also use the logo.cub file in conjunction with ICE tools provided by leading install tool vendors.

Leading vendors of install tools have new versions of their tools to enable easy authoring of Windows Installer-based packages. Contact your tools vendor for more details. You can also create your own Windows Installer-based package. The Microsoft Platform SDK provides a detailed example for implementing a Windows Installer-based package.

2.2    Observe rules in componentization

The Windows Installer service always installs and removes an application as monolithic pieces of information referred to as components. A component can consist of a collection of files, registry keys, shortcuts, or any other information that must be written to the user's computer during the installation. The installer identifies a component by its unique component code GUID. The installer locates the component using a keypath file that belongs to the component. Because components are commonly shared by more than one application or product, developers must correctly organize their applications into a set of components to ensure their application can be managed by the installer.  For more details, see “Organizing Applications into Components” in the Windows Installer documentation in the Platform SDK.

To ensure that the removal of one program does not harm any other programs on the system and that the Windows Installer service correctly removes all resources connected with that program, your application must adhere to the following rules:

·         A single resource must not be shipped as a member of multiple components across multiple products, unless it is isolated as its own component and is flagged as shared in the component table.

·         All files in a given component must be installed to the same directory. This means files in different directories must be in different components.

·         All files that are the targets of advertisable shortcuts must be the KeyPath of a component. This means there can only be one advertised file per component, although many different shortcuts can point to that single file.

·         COM servers must be the KeyPath of a component. This means there can only be one COM server per component. A single file, which can only be in one component, may serve multiple CLSIDs. However, two files serving different CLSIDs must be in separate components.

·         Extension servers must be the KeyPath of the component. This means there can only be one Extension server per component.

 

2.3    Identify shared components

·         If the Windows Installer service determines that a component is shared, it will automatically handle the incrementing and decrementing of reference counting, and if appropriate, removal of components when no other application depends on them.

·         The Windows Installer service will automatically determine if components are shared with other applications that also use the Windows Installer service.

·         For components that are to be shared with applications that don’t use Windows Installer service, you must flag these components in the component table, so the Windows Installer service knows to also reference count them in a manner that is compatible with legacy install methods. This helps ensure that your application interoperates properly with other applications that do not use the Windows Installer service.

·         Components that are shared with applications that don’t use Windows Installer service need to properly implement the DLLRegisterServer and DLLUnregisterServer entry points if they need to do any registration at install time.  (DLLs which use the Windows Installer should use the registration services provided by the Windows Installer.)

Note: Applications are not allowed to update files that are protected by Windows File Protection on Windows 2000. See Chapter 3, “Component Sharing” for more details.

2.4    Install to Program Files by default

By default, your application must install into an appropriate subdirectory where the current user’s program files are stored. This folder is represented by the ProgramFilesFolder property in the Windows Installer-based package. (The ProgramFilesFolder property is a variable that exposes the path to the Program Files folder, and the Windows Installer sets that variable appropriately on all Windows platforms.)  On English systems, this folder is often “C:\Program Files”. However, do NOT hardcode that path, as it is not universal.

 

Exception: If you are upgrading a previously installed version of your application, it is acceptable to default to the directory where that version exists.

Considerations for shared components

In some cases shared component must be placed in locations other than the application directory. See chapter 3, “Component Sharing” for full details.

2.5    Support Add/Remove Programs properly

Your application must supply all the information in the following table so that Add/Remove Programs in the Control Panel can obtain information about the application as needed. You can set these values using properties in the Windows Installer-based package. Setting these properties will automatically write the corresponding values in the registry under

HKEY_LOCAL_MACHINE

  \Software

    \Microsoft

      \Windows

        \CurrentVersion

          \Uninstall

            \{ProductCode}

 

Property

Corresponding registry value

Contains

ProductName

DisplayName

Display name of application.

ARPINSTALLLOCATION

InstallLocation

Full path where application is located (folder or .exe).

Manufacturer

Publisher

Publisher/Developer of application.

ProductVersion

VersionMajor

Major version number of application.

ProductVersion

VersionMinor

Minor version of application.

Note: Property names are case-sensitive.

 

You can also provide additional properties to present in Add/Remove Programs if you like, such as product ID, online support information, etc. See the platform SDK for full details.

2.6    Ensure that your application supports advertising

“Advertisement” is the notion of application availability in the absence of the application’s files being installed. Advertising allows the application to be deployed using software management tools.

All Windows Installer-based packages of your core application must be advertisable in a manner that operating system entry points, such as shortcut activation and file activation, can trigger install on demand. In order to support advertisement at the operating system level, the following tables in the Windows Installer-based package must be populated with advertising data: shortcut, extension, icon, and Verb. It is recommended that you also populate class, MIME, ProgID, and TypeLib.

Note: This does not mean your application must support feature-level advertising, (e.g. enabling the spell-checker to install on demand). The intent of this requirement is to ensure that your overall application can be installed on demand using the IntelliMirror features of Windows 2000.

 

2.7    Ensure correct uninstall support

Your application’s Windows Installer-based package must correctly and fully uninstall the application. In a package that follows component rules and uses only native Windows Installer actions to modify the computer, this capability is provided automatically.

However, if your Windows Installer-based package includes custom actions, you will need to proactively ensure that your application properly uninstalls. Except as noted below, your application must remove the following:

·         All non-shared application files and folders

·         Shared application files whose refcount reaches zero

·         Registry entries, except for keys that might be shared by other programs

·         All shortcuts from the Start menu that the application created at install-time

·         The uninstaller itself

 

The following should remain on the hard disk:

·         User data files.

·         Shared application files that have a non-zero refcount.

·         “Core” files. These files must be left behind to ensure compatibility with legacy applications. See http://www.veritest.com/ftp/core.htm for the most up-to-date, complete list. The core component list exists for historical reasons and is maintained to ensure compatibility with legacy applications that did not properly implement refcounting. Microsoft expects to add no new files to this list. On Windows 2000 and later, applications should rely on Windows File Protection for information on what system files to update or uninstall. See Chapter 3, “Component Sharing.”

·         Other resources that other programs use, sharable fonts, and sharable registry entries. If you are not sure whether removing a DLL might harm other applications, it is better to leave it behind.

You must explain in the Vendor Questionnaire everything you leave behind.

 

Tip: If your application creates temporary files that should be removed during uninstallation, create a zero-length (0) file with the same name at installation time. Examples of such files would be .gid files created by Help.

 

 

How to Pretest Applications for Windows Installer Service Requirements

To pretest a Windows Installer-based package:

·         Use an Internal Consistency Evaluation tool with the logo.cub file to check the validity of your application’s Windows Installer-based package. The logo.cub file is available in the Windows Installer SDK.

·         Use Windows 2000 software management tools to deploy the application to both users and to machines. Verify all the activation paths work correctly when the application is advertised.

 

To pretest correct setup actions:

·         Use the Windows 2000 application deployment tools to publish the application. Verify the application can be installed from Add/Remove Programs, Add from the corporate network.

·         Use the Windows 2000 application deployment tools to assign the application to a user. Log on as that user to a machine that did not previously have the application installed. Verify after the user logs on that the application is correctly advertised, i.e., it looks like it is fully installed on the machine and all activation paths (shortcuts and file extensions, for example) trigger an installation.

·         Use the Windows 2000 application deployment tools to assign the application to a machine that does not currently have the application installed. Verify after the machine is booted the application is fully installed.

·         Undeploy the application in the tests above. Verify Windows 2000 software management can silently uninstall the app from the user/machine.

·         Install the application for more than one user on a given machine. Verify each user can have their own settings and also uninstalling the application for one user does not affect the others.

·         Test the install and uninstall of your package under each of these Windows Installer UI modes:

·         Full

·         Basic (Simple progress and error handling)

·         None (completely silent installation, no UI)

You can activate different UI modes by launching your package with the /q switch. (Default is mode full. Specify b=basic, n=none)

 

To pretest uninstallation:

1.       Take a snapshot of a computer’s directory tree, install the application, uninstall the application, and take another snapshot.

2.       Verify that the snapshots before the install and after the uninstall are the same, except for the following which should be left on the machine: user created files, core files, and shared components that are still required by other programs.

To pretest interop with other apps that share components:

To ensure that your application interoperates well with other applications (that do not use the Windows Installer) that share some of the same components that your application uses, you should test and verify each of the following scenarios:

 

 

Scenario 1

Scenario 2

Scenario 3

Scenario 4

Step 1

Install your app

Install your app

Install “other” app

Install “other” app

Step 2

Install “other” app

Install “other” app

Install your app

Install your app

Step 3

Uninstall your app

Uninstall “other” app

Uninstall “other” app

Uninstall your app

Step 4

Verify “other” app still works

Verify your app still works

Verify your app still works

Verify “other” app still works

 


 

 

Chapter 3

Component Sharing

Describes the requirements for handling shared components so that applications better coexist with one another.

Summary of Component Sharing Requirements

Rationale

Windows-based applications can share code, as well as application and component state in the registry, application specific data in the file system, and Windows APIs which expose global namespaces.  Sharing allows for the efficient leverage of limited hardware resources and reduces the exposed front that Quality Assurance groups must test. 

However, there are costs to sharing. Sharing causes applications to become interdependent upon one other, which introduces an element of fragility. In the extreme, applications that once worked will mysteriously start functioning oddly, or even fail. Typically, an application is dependent on a particular version or implementation of a shared component. If that shared component is upgraded (or downgraded) as a result of installing another application, the former application may break. This condition is often referred to as “DLL Hell.”

Successful global sharing requires that any shared component behave exactly like previous versions of that component to avoid this problem. In practice, however, 100% backward compatibility is difficult, if not impossible, to achieve because:

·         It is usually not feasible to test all configurations in which the shared component may be used.

·         Component “functionality” is not easily defined. Applications may become dependent on unintended side effects that are not considered part of the core “functionality” of the component.  For example, a component author may choose to fix a “bug” in the component, which another application has unknowingly (or knowingly) become dependent on. 

·         The sheer volume of applications that use the component exacerbates the problem.

 

Windows 2000 and Windows 98 Second Edition enable a new form of sharing called side-by-side sharing which minimizes this application fragility. Side-by-side sharing enables multiple versions of the same COM or Win32 component to run at the same time in memory. This means applications can use the specific components that they were designed for and tested with, even if another application requires a different version of the same component. This allows developers to build more reliable applications because developers can choose the version of the component they will use for their application, independent of the other applications on the system.

Side-by-side sharing requires the use of side-by-side components, which are ordinary COM or Win32 components, except that they:

·         Are installed into the application directory rather than the system directory.

·         Must be registered properly with the system (as described later in this chapter) so they won’t conflict with other versions of the component that may exist.

Side-by-side components are isolated to a specific application and are not globally shared across all applications:

·         A side-by-side component can run safely “side-by-side” with a different version of the same component that is installed elsewhere on the system. If another application on the system requires a different version, your application will be unaffected and both applications will run with their respective versions of the component.

·         In the event another application installs a new version of a component on the system, your version of that component will remain untouched since you installed it into your application directory. Your application will continue to use the same version of the component that you shipped with your application, while the other application will use its version. Both versions can exist in memory at the same time.

The following chart compares the traditional “global sharing” method with side-by-side sharing.

 

Global Sharing

Side-by-Side Sharing

Requires consistency of interface and behavior over time. Backward compatibility needs to be tested.

Interface and behavior can change over time.

All versions can/must share the same state (registry, etc).

Requires isolation of state by component version and optionally, by application using the component.

Applications all use the “latest version” of a component.

Applications choose which version of a component they use.

Installs into a globally shared location, for example the system directory.

Installs into the application’s directory.

System supports activation by absolute name (file name in system directory or GUID to an absolute file name).

Activation is by relative name based on the application being run.

Upgrading / bug fixing the component simply requires replacing the single globally shared component.

Upgrading and bug fixing a component is the responsibility of the application developer.

 

 Customer Benefits

·         Application writers can safely use your components without fear of some other application overwriting them. The main cause of “DLL Hell” is eliminated.

·         Customers can safely install and reliably run multiple applications that require different versions of the same shared component.

·         Customers can update applications independently of each other, without fear of impacting existing applications.

·         Customers will be able to install your component without requiring a reboot, even if another application is using a different version of your component. 

 

Requirements

3.1     On Windows 2000 do not attempt to replace files that are protected by Windows File Protection.

3.2     Component producers: Build side-by-side components.

3.3     Application developers: Consume and install side-by-side components

3.4     Install any non side-by-side shared files to the correct locations

 

References

 “Implementing Side-by-Side Component Sharing in Applications”

http://msdn.microsoft.com/library/techart/sidebyside.htm

 

How to Comply with Component Sharing Requirements

3.1    On Windows 2000 do not attempt to replace files that are protected by Windows File Protection

Your application must not attempt to replace any Windows 2000 files that are protected by Windows File Protection (WFP). To ensure that you do not invoke WFP, call SfcIsFileProtected when installing any file you did not create. The Windows Installer service version 1.1 automatically does this for you.

Protected files include the following files that ship on the Windows 2000 CD:

·         Most .SYS, .DLL, .EXE and .OCX files.

·         The following fonts: micross.ttf, tahoma.ttf, tahomabd.ttf; fixedsys.fon, dosapp.fon, modern.fon, script.fon and vgaoem.fon

Note, some redistributable files, such as specific versions of Microsoft Foundation Classes (MFC) DLLs, are installed by Windows 2000 and are protected by WFP.

Protected files form the core of the operating system and it is essential for system stability that the proper versions be maintained. These files can only be updated via Service Packs, operating system upgrades, QFE hotfixes, and Windows Update. Applications cannot replace them, and attempting to replace these files by means other than those listed above will result in the files being restored by the Windows File Protection feature (see below).

If your application requires newer versions of these components, your application must update these components using an approved Microsoft Service Pack that installs the required versions.

About Windows File Protection:

Windows File Protection is a feature of Windows 2000 which prevents the replacement of essential system files.  WFP runs as a background process on Windows 2000 and monitors the files listed in the preceding section. When WFP detects that a protected file has been changed, it restores the original.

The following code shows how to check if a file (in this case “ntdll.dll”) is protected by WFP. Note that SfcIsFileProtected is Unicode-only and requires a fully qualified path.

SHGetFolderPath(NULL,CSIDL_SYSTEM, NULL, 0, szSystemDir);

PathAppend(szSystemDir,"ntdll.dll");

MultiByteToWideChar(CP_ACP, 0, szSystemDir, -1, wzFileName, 265);

 

if ( SfcIsFileProtected(wzFileName) )

  MessageBox(hWnd,szProtected,szSystemDir,MB_OK);

else

  MessageBox(hWnd,szNotProtected,szSystemDir,MB_OK);

 

3.2    Component producers: Build side-by-side components

Authors writing new redistributable components must use side-by-side sharing techniques so their components can be installed into the application directory. 

“Side-by-side” means version 1 of the component runs in one process while version 2 runs in another process. This requires each version to isolate its state so that it doesn’t conflict with other versions. The rules below will help ensure your components can run in a side-by-side scenario. Most ordinary components will need only minor modifications to meet these requirements.

To build a side-side component:

·         Do not register full path names for COM registrations. The operating system will find any dependent components in the application directory.

·         If COM meta data (such as threading model) changes between versions, expose a new GUID in the new version.

·         Typelibs must be contained within your DLL instead of as a separate file. Use LoadTypeLib and not LoadRegTypeLib to load typelibs.

·         You must reference count GUIDs: Uninstall of a side-by-side component should not remove its GUIDs from the registry because another app on the system using this component could be dependent on it. 

·         Registry settings must be per version.  For example, store your registry state in keys with the following naming convention

HKCU\MyCompany\MyComponent\VersionXXXX\

 

·         Other global stores must be per version if the data changes across versions:

·         Use of shared data structures like memory mapped files, mutexes, and named pipes needs to be designed to be different for each version of the component so that different versions can run at the same time.

·         Use of memory mapped files and shared files must either be separated per component version or have version keys within the file so that different versions of the component can access them at the same time.

 

Note: Side-by-side sharing is supported in Windows 2000 and Windows 98 Second Edition. For previous Windows operating systems, side-by-side activation is not supported. However, a side-by-side DLL can be written so that it installs on down-level platforms into the system directory, and functions in a global-sharing (backward compatible) fashion.  Side-by-side DLLs must be installed to the system directory on these platforms, and in the application directory on Windows 2000 and Windows 98 Second Edition. Applications must dynamically check the operating system version to determine which sharing technique to use. The following code checks if side-by-side sharing is supported:

BOOL bPlatformSupportsSideBySide(void)

{

    OSVERSIONINFOEX osviex ;

 

    osviex.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);

 

    // If platform does not support OSVERSIONINFOEX structure, it does not

    // have side-by-side support

    //

    if (!GetVersionEx((OSVERSIONINFO *)&osviex))

    {

        return FALSE ; // no DLL re-direction

    }

 

    // However, for NT, then NT4 SP4 had support for OSVERSIONINFOEX

    // support but it did not support DLL re-direction.

    // If DLL re-direction appears in a future NT4 SP,  this code will have

    // to be updated.

    //

    if ( (osviex.dwPlatformId == VER_PLATFORM_WIN32_NT) && (osviex.dwMajorVersion < 5) )

    {

        return FALSE ;

    }

 

    // For the other platform Ids, assume has side by side support

    return TRUE ;

}

 

3.3    Application developers: Consume and install side-by-side components

For Windows 2000 and Windows 98 Second Edition, any side-by-side DLLs that your application depends on must be installed into your application directory:

%ProgramFiles%\<company name>\<App Name>

Be sure to follow the install and uninstall instructions provided by the component developer.

On down-level operating systems, install side-by-side components into the system directory. Installers must dynamically check the operating system version to determine which sharing technique to use.

3.4    Install any non side-by-side shared files to the correct locations

The proper location for shared components depends on whether these components are shared across companies or by a single company.

·         Shared components that are private to a single software vendor must be installed in one of two places. Do not store these files in the system directory.

common files directory\<company name>

%ProgramFiles%\<company name>\Shared Files

 

The common files directory can be accessed by passing  CSIDL_PROGRAM_FILES_COMMON to the SHGetFolderPath API, or by using the Windows Installer CommonFilesFolder property.  For more information on using Windows Installer Properties, see the Windows Installer Programmer’s Reference in the Platform SDK.

 

·         Non side-by-side OCXs and DLLs that are shared by multiple software vendors can be placed in the system directory to ensure backward compatibility with those applications. 

 

You must document in your Vendor Questionnaire any cases where your software application writes to the system directory.

 

·         New control panel applets (CPLs) must be installed in the application directory on Windows 2000. Register the path by adding a value under either of the following registry keys:

HKLM\software\microsoft\windows\CurrentVersion\control panel\cpls

HKCU\software\microsoft\windows\CurrentVersion\control panel\cpls

Example of a name / value pair under this key:

MyCpl = “%ProgramFiles%\MyCorp\MyApp\MyCpl.cpl

 

·         Services and device drivers must be placed in the system directory.

Note: The system directory is not locked down when the user is a power user or administrator, so legacy components or globally shared components can still be placed there.  However, Windows File Protection prevents the replacement of protected operating system files. See Requirement 3.1.

How to Pretest Applications for Component Sharing Requirements

 

To pretest installation:

After installing your component, make sure there are no instances of fully qualified names to your component stored in the registry.

To pretest uninstall:

Test uninstall with one instance of your component installed (only one application uses your component). Make sure all GUIDs and other information to your component have been removed.

Test uninstall with two instances of your component installed (i.e., two apps uses your component). Make sure the other application still runs after uninstalling the first application which uses your component.

To pretest co-existence:

Install your component in two different applications. Run both applications at the same time and make sure your component continues to function properly. Ideally, you will test using two different versions of your component.

 

 

 


Chapter 4

Describes the requirements to ensure that applications support roaming users, multiple users per machine, and simplified machine replacement. Applications that meet these requirements can also operate properly in a secure Windows environment.

Data and Settings Management

Summary of Data and Settings Management Requirements

Rationale

Windows 2000 provides an underlying infrastructure that supports state separation of user data, user settings, and computer settings. Applications that properly use this infrastructure offer the following benefits:

·         Support for roaming users

·         Support for multiple users on a single machine, each with their own settings

·         Simplified machine replacement

·         Operation in a secure Windows environment

·         Helps ensure proper functioning on Terminal Services.

IntelliMirror uses these features along with software installation and maintenance technologies described in Chapter 2, to provide the “follow me” feature that allows users’ data, settings, and software to follow them to any Windows 2000-based desktop.

Customer Benefits

·         Users can easily back up their individual documents and settings without having to backup application and operating system files.

·         Applications can be installed and run in a secure Windows environment.

·         Multiple users can share a single computer, each with their own preferences and settings.

·         A single user can roam to multiple computers, maintaining their own documents and settings from one computer to another.

·         Administrators can easily manage corporate desktops.

 

Requirements

4.1     Default to My Documents for storage of user-created data

4.2     Classify and store application data correctly

4.3     Degrade gracefully on access denied

4.4     Run in a secure Windows environment

4.5     Adhere to system-level Group Policy settings

4.6     Applications that create ADM files must properly store their ADM file settings in the registry

 

References

Windows 2000 Default Access Control Settings

http://www.microsoft.com/windows/server/Technical/security/

Whitepapers on Windows 2000 Management Services

http://www.microsoft.com/windows/server/Technical/management

Information on registry settings for system-level Group Policy:

System.adm file, installed on Windows 2000 systems

How to Comply with Data and Settings Management Requirements

4.1    Default to My Documents for storage of user-created data

If your application allows for local file I/O, then the first time an application is run per user, the application’s Common File Open and Save dialogs must default to the My Documents folder or descendant folder the first time these dialogs are called. On subsequent calls to these dialogs, it is recommended to default to the previously used path.

Calling the Common File Open/Save with no parameters will default to the My Documents folder or you can target the My Documents folder directly by passing CSIDL_PERSONAL to SHGetFolderPath().

Note:

·         The My Documents folder is for user-created data, but not for temporary storage or application state data. Non-user data must be stored using the proper AppData path, as described in the Requirement 4.2.

·         For imaging applications, it is recommended to use My Pictures, a descendant of My Documents, in place of My Documents.

Benefits for using the My Documents folder as the default for data storage are:

·         Users have one familiar place to organize and store all their data.

·         Data sharing is facilitated between applications because all applications using Common File Open can easily access the My Documents folder.

·         My Documents is an abstracted location and can be redirected to the network transparently by an administrator.

·         My Documents is available on the Desktop.

·         The My Documents folder is part of a user’s profile information, so by default, other users can’t read its contents.

 

Retrieving the path to My Documents: The preferred way to do this is by using passing CSIDL_PERSONAL to the SHGetFolderPath API.

TCHAR szMyDocs[MAX_PATH];

...

hr = SHGetFolderPath(NULL, CSIDL_PERSONAL, NULL, 0, szMyDocs)

 

SHGetFolderPath behaves consistently across Windows 95, Windows 98, Windows NT 4, and Windows 2000 and is exported from SHFOLDER.DLL.  SHFOLDER.DLL ships in Windows 2000 as well as Windows NT 4 Service Pack 4 (and later), Internet Explorer 5, and Windows 98 Second Edition. SHFOLDER.DLL is a redistributable component that contains support for CSIDL_PERSONAL as well as many other special folders. (See Appendix A, “Best Practices.”)  SHFOLDER.DLL is installed by the Windows Installer redistributable. Software vendors are encouraged to redistribute this component as much as possible to enable this support on Windows operating systems prior to Windows 2000. Windows 2000 includes this DLL as a protected system file and as such, this DLL cannot be replaced on Windows 2000 or greater.

To help ensure your application can run on Windows 9x, Windows NT 4 as well as Windows 2000, always link to the SHGetFolderPath implementation in SHFOLDER.DLL. Windows 2000 natively implements SHGetFolderPath in SHELL32.DLL, but other versions of Windows do not include SHGetFolderPath in SHELL32.DLL.

 

4.2    Classify and store application data correctly

Application data, such as user preferences, application state, temp files, and so on, must be stored in application data folders or the registry according to the following classifications:

·         Per user, roaming

·         Per user, non-roaming

·         Per machine (non-user specific and non-roaming)

Guidelines on classifying application data among these three choices are provided below, though the final decision is left to the software developer. Classifying application data according to these three types ensures a consistent and abstracted location for user data, enables roaming, enforces per-user separation of application data, and allows the operating system and its applications to be secured.  In a roaming scenario, data that is designated as roaming will be copied to and from the server during logon/logoff processing. It is important to prioritize carefully what should be roamed vs. not roamed so as to minimize the amount of information that is transferred across the network.

In general, use application data folders rather than the registry for storing application data in excess of 64KB. The registry is acceptable for small amounts of data. At install time your application must not store more than a total of 128KB across HKCU and HKLM (note that HK Classes Root is excluded).

Using Application Data Folders:

The CSIDL values described here provide a consistent, unified way to access the physical paths to the desired folder locations, independent of the operating system. The preferred API is SHGetFolderPath, because it behaves consistently across all versions of Windows. To access the path for application data, applications should call SHGetFolderPath with the appropriate CSIDL and then append [company name]\[product name]\[version] to the returned path. Specifically:

To retrieve the CSIDL _APPDATA path:

TCHAR szAppData[MAX_PATH];

hr = SHGetFolderPath(NULL, CSIDL_APPDATA, NULL, 0, szAppData);

 

When storing application data in the user profile, applications should use the same hierarchy under Application Data and Templates as is used in the registry:

   [User Profile]\

     Application Data\

        [company name]\

          [product name]\

             [version]\

               [file or folder]

 

Data Type

Folder CSIDL

Folder Location

Per user, roaming

CSIDL_APPDATA

[user profile]\Application data

Per user, non-roaming

CSIDL_LOCAL_APPDATA

[user profile]\Local Settings\Application data

Per machine (non-user specific  & non- roaming)

CSIDL_COMMON_APPDATA

All Users\Application data

 

·         CSIDL_APPDATA

As part of the User profile, this folder will roam.  Use this folder to store all user-specific application preferences. For example, if a user can specify a custom dictionary to be used in your application, you should store it here. That way if the user roams from computer to computer, their dictionary will roam with them. This also allows other users to have their own individual custom dictionaries.

·         CSIDL_LOCAL_APPDATA

This folder is for application data that does not roam. It is still part of the User profile, so this is still per-user information. Application data that is machine-dependent, such as user specified monitor resolution, should be stored here. This data must not roam because different machines have different monitors. In addition, large blocks of data which can easily be re-created should be placed here to minimize download time that is incurred when roaming. For example, Internet Explorer keeps its cache of downloaded html/gif pages here so that they don't roam with the user.  But the smaller cookie and history lists are stored in CSIDL_APPDATA so that they roam.

·         CSIDL_COMMON_APPDATA.

This folder should be used for application data that is not user specific. For example, an application may store a spell check dictionary, a database of clip-art or a log file in the CSIDL_COMMON_APPDATA folder. This information will not roam and is available to anyone using the computer. By default, this location is read-only for normal (non-admin, non-power) Users.  If an application requires normal Users to have write access to an application specific subdirectory of CSIDL_COMMON_APPDATA, then the application must explicitly modify the security on that sub-directory during application setup.  The modified security must be documented in the Vendor Questionnaire.

Using the Registry:

Applications may also use the registry for storing read/write application data and configuration files.

·         The HKCU registry is appropriate for storing small amounts of data (<64KB) and for policy settings that are per user.

·         Avoid writing to HKLM during runtime, because normal Users have Read Only access to the entire HKLM tree by default. In addition, HKLM does not support roaming.

·         Larger, file-based data should be placed in the Application Data folder. For example, Internet Explorer’s Temporary Internet Cache is stored within the user profile and not in the registry.

·         At install time your application must not store more than a total of 128KB across HKCU and HKLM. Note that HK Classes Root is excluded.

Additional Considerations:

·         Files may be shared in UserProfile\Application Data. Multiple computers may use them simultaneously in different versions of the application. The data may also be used by multiple applications, for example, applications in a productivity suite. Applications should only get a write exclusive on the file when necessary. For example, applications using CreateFile should only specify GENERIC_WRITE when a write is required, but they should always set FILE_SHARE_READ.

·         Paths returned by SHGetFolderPath are valid Win32 file system names that may contain spaces and may be in the UNC format.

·         PathAppend() and PathCombine() APIs can be used to concatenate the relative path information onto the paths returned by SHGetFolderPath. Example:

PathAppend(szAppData, "Company\Product\File.txt")

 

·         Any user can write into the All Users\Documents location.  However, by default, only the creator of the document (and administrators) will be able to subsequently modify the document.  All other (non-admin) Users will have read-only access to the document by default.  If an application requires that all normal Users to have write access to a given application specific subdirectory of CSIDL_COMMON_DOCUMENTS, then the application must explicitly modify the security on that sub-directory during application setup.  The modified security must be documented in the Vendor Questionnaire.

·         By default, normal Users have read only access to all locations other than those specified in Requirement 4.4. Thus normal Users cannot write to the Winnt directory, system32, or the Program Files directory.

 

4.3    Degrade gracefully on access denied

By default on Windows 2000, normal (non-admin, non-power) Users cannot write to per-machine locations such as HKLM and the Winnt directory.  Only applications that classify and store data correctly, as described above, will be able to avoid access denied errors and run successfully in this secure environment. There are, however, legitimate scenarios where access denied errors are encountered by applications which classify and store data correctly.  For example,

·         An unprivileged User may attempt to run an administrative application that is designed to modify system-wide settings.  In this case, the User is allowed to run the application, but cannot carry out any system-wide modifications.

·         An unprivileged User may run an application that allows users to modify objects based on permissions.  In this case, a User is allowed to modify objects which they own, but not objects owned by the administrator or other Users.

·         An unprivileged User may direct an application to save per-user data in a per-machine location, for example, by choosing the system directory as the destination for a File\Save operation.

In these cases, the application should degrade gracefully when the access denied error is encountered.  Degrading gracefully can be accomplished by:

1.       Disabling the operation in the first place.

This is the approach taken by System Settings in Control Panel.  A User cannot set system-wide environment variables, but they can set their own environment variables.  Thus, when a User launches this applet, the system-wide environment variable option is “grayed-out”.  When an administrator launches it, the system-wide environment variables can be modified.

2.       Display an appropriate error message.  For example,

·         “You must be an administrator to perform this operation”

·         “You only have permissions to view the properties of this object”

·         “You must have xyz privilege to perform this operation”

·         “You must have write access to abc.xyz to perform this operation”

 

4.4    Run in a secure Windows environment

Your application must function properly in a secure Windows environment. Complying with the previous requirements in this chapter will help ensure that your application meets this requirement. 

A secure Windows environment is defined as the environment exposed to a normal (non-admin\non-power) User by default on a clean-installed NTFS system.  In this environment, Users can only write to three* specific locations:

1.   Their own portion of the registry (HKEY_CURRENT_USER)**

2.   Their own user profile directory (CSIDL_PROFILE)

3.   A Shared Documents location  (CSIDL_COMMON_DOCUMENTS)***

Users can also write to subkeys and subdirectories of these locations.  For example, users can write to CSIDL_PERSONAL (My Documents) because it is a subdirectory of CSIDL_PROFILE. Users have Read-Only access to the rest of the system.

*Applications are free to modify the default security for an application-specific subdirectory of CSIDL_COMMON_APPDATA provided the modification is documented in the vendor questionnaire.  This may provide a fourth location for Users to write to for a given application.

**Users cannot write to the following subsections of HKCU:

\Software\Policies

\Software\Microsoft\Windows\CurrentVersion\Policies

 

***By default, Users cannot write to other Users’ shared documents, they can only read other Users’ shared documents.  Applications are free to modify this default security on an application-specific subdirectory of CSIDL_COMMON_DOCUMENTS provided the modification is documented in the Vendor Questionnaire.

 

Exception:

When the major features of the application can be successfully run as a non-privileged User, exceptions may be made for minor features that are not considered important for the operation of the program and which are not installed by any default mechanism (e.g. a minimal or typical install) other than a "complete" install.  Examples of such minor features include components necessary to support legacy file formats.  In some cases, entire applications may be exempted, provided that the primary purpose of the application is to perform some administrative function that is technically not possible for normal Users to perform.

For any feature that does not work as User, you must document in the Vendor Questionnaire what objects (file system\registry keys) need to be opened in order for that feature\function to work. Requests for exemptions are judged on a case-by-case basis.

 

4.5    Adhere to system-level Group Policy settings

Group Policy settings allow administrators to control and manage their users’ PC environments by mandating specific user and computer settings across the network. System-level Group Policy settings may be set by administrators to control specific capabilities of the system. For each policy listed below, your application must adhere to any policy settings that are enabled at the time your application is launched. Adherence to an enabled policy is defined by “Application Action” in the charts below. The “Registry Information” indicates where the policy setting information is stored.

For many applications, no action is required to adhere to these policies. However, if your application replaces or duplicates operating system functionality, specific steps may be required on the part of the application.

Policy Setting

Remove Run menu from Start Menu

Description

When this policy is enabled, Windows 2000 removes Run from the Start Menu and disables users from launching the Run dialog via pressing the Windows Key + R.

Application

Action

If your application has a “run” function that allows a user to start a program by typing in its name and path in a dialog, then your application must disable that functionality when this policy is enabled.

Registry Information

Key:  HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer

Value Name: NoRun

 

Policy Setting

Hide these specified drives in My Computer

Description

When enabled, this policy removes the icons representing the selected disk drives from My Computer, Windows Explorer, and My Network Places and from Common Dialogs.

Application

Action

Your application must hide any drives that are hidden by the system when this policy is enabled. This includes any buttons, menu options, icons, or any other visual representation of drives in your application. This does not preclude the user from accessing drives by manually entering drive letters in dialogs.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer

Value Name: NoDrives

 

Policy Setting

Run only allowed Windows Applications

Description

When this policy is enabled, users can only run applications that are listed under the following key: Software\Microsoft\Windows\CurrentVersion\Policies\Explorer\RestrictRun

Application

Action

Your application must not start any application that is not on this list. If you use ShellExecuteEx, Windows 2000 will handle this for you automatically.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer

Value Name: RestrictRun

 

Policy Setting

Remove "Map Network Drive" and "Disconnect Network Drive"

Description

When this policy is enabled, users are prevented from using Windows Explorer and My Network Places to connect to other computers or to close existing connections.

Application

Action

When this policy is enabled, applications must not provide buttons, menu options, icons, or any other visual representation that enables a user to map or disconnect network drives.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer

Value Name: NoNetConnectDisconnect

 

Policy Setting

No Entire Network in My Network Places

Description

When enabled, this policy removes all computers outside of the user's workgroup or local domain from lists of network resources in Windows Explorer and My Network Places.

Application

Action

When this policy is enabled, applications that allow users to browse network resources mustlimit browsing functionality to local workgroup or domain.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Network

Value Name: NoEntireNetwork

 

Policy Setting

Do not keep history of recently open documents

Description

When this policy is enabled, the system does not save shortcuts to most recently used (MRU) documents in the start menu.

Application

Action

When this policy is enabled, applications must not display any MRU lists (for example, in file menu and save/open dialogs).

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer

Value name: NoRecentDocsHistory

 

Policy Setting

Disable/Remove the Shut Down command

Description

This policy prevents the user from using the Windows user interface to shut down the system.

Application

Action

When this policy is enabled, applications that enable the user to shut down Windows must disable this capability.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer

Value Name: NoClose

 

Policy Setting

Hide Common Dialog Places Bar

Description

The places bar allows users to navigate via the common dialog directly to the following locations: History folder, Desktop, My Documents, My Computer, and My Network Places. When this policy is enabled, Windows 2000 removes the places bar from the Windows common dialog.

Application

Action

When this policy is set,applications that provide their own file/open dialogs must remove any functionality equivalent to the places bar. Applications that use the Windows common dialog API will automatically comply with this policy.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Comdlg32

Value Name: NoPlacesBar

 

Policy Setting

Hide Common Dialog Back button

Description

When this policy is enabled, Windows 2000 removes the back button from the common dialog, preventing the user from browsing to the previous folder accessed from the dialog.

Application

Action

When this policy is set,applications that provide their own file/open dialogs must remove or disable any back button functionality from these dialogs. Applications that use the Windows common dialog API will automatically comply with this policy.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Comdlg32

Value Name: NoBackButton

 

Policy Setting

Hide the dropdown list of recent files

Description

When this policy is enabled, Windows 2000 removes the MRU list from the common dialog.

Application

Action

When this policy is set,applications that provide their own file/open dialogs must not display an MRU list in these dialogs. Applications that use the Windows common dialog API will automatically comply with this policy.

Registry Information

Key: HKCU\ Software\Microsoft\Windows\CurrentVersion\Policies\Comdlg32

Value Name: NoFileMru

 

To comply with the Application Specification, your application must adhere to the policies listed above. Note, however, that additional system-level policies exist and it is recommended that your application honor these as well.  For example:

·         Don’t save settings at exit: when this policy is set, applications should not save settings such as Window size/location and toolbar locations.

·         Disable changes to Taskbar and Start Menu settings: When this policy is set, applications should not add or remove any items to the Start Menu.

Registry settings for system-level policies can be found in the system.adm file on Windows 2000 systems. We recommend that developers review the system.adm file to ensure their applications respect any additional policies that the administrator may set.

 

4.6    Applications that create ADM files must properly store their ADM file settings in the registry

Administrative Template (ADM) files allow administrators to implement Group Policy settings. If your application offers management capabilities via ADM files, it must store these settings under the following registry keys:

HKCU\Software\Policies for user specific policy settings

HKLM\Software\Policies for machine specific policy settings

 

How to Pretest Applications for Data and Settings Management Requirements

To pretest correct storage of user data and defaults:

1.       Clean-install Windows 2000 onto an NTFS partition.*

2.       Log in as Administrator.

3.       Remove all members of the Power Users group.

·           By default, Interactive users are Power Users.

4.       Install the application into the Program Files directory

5.       Log in as a normal (non-admin, non-power) User (e.g. “User1”).

·         This must be a different account than the one used to install the application.

6.       Verify that the application runs successfully as a normal User.

·         A normal user should be able to perform all advertised functionality

·         The application must degrade gracefully when a normal user attempts to perform any administrative functions exposed by the application (e.g. Changing System Time, System Environment Variables, System Security Settings etc...)

7.       Modify user preferences, create files, etc.

8.       Log in as a different (non-admin, non-power) User (e.g. “User2”).

9.       Verify that User1's custom preferences do not apply to User2.

10.   Roam to a different machine that also has the application installed. Log in as the same user as in step 6 (User1). (Make sure that this user has a roaming profile enabled on the network.)

11.   Launch the application and verify that User1's custom preferences are available on the new machine.

 

* When testing in an NT4 environment, Security Configuration Manager should be used to configure the NT4 systems in a secure manner that is consistent with the Windows 2000 defaults.  After installing Windows NT4 and the proper service pack, install the command line version of the Security Configuration Manager and configure the system using the w2kdefsec.inf security template. This template is included in the Support Files for the Windows NT4 Test Plan, available at http://msdn.microsoft.com/certification/download.asp.

 


Chapter 5

Describes the requirements to provide an accessible user interface.

User Interface Fundamentals

Summary of Requirements for UI Fundamentals

Rationale

·         Consistency and accessibility among Windows-based applications increases customer confidence in Windows applications and the Windows platform.

·         Meeting UI requirements enables the use of sophisticated automation tools, including testing tools, task automation tools such as intelligent agents, and new input methods such as voice input.

·         Organizations that use the Windows platforms require software to be usable by a wide range of users in order to comply with employment and equal rights legislation.

·         Meeting these requirements helps you ensure that software will be compatible with future enhancements that are planned for the Windows platform, including speech input, speech output, and intelligent task automation.

 

Customer Benefits

·         Providing a consistent user interface reduces training, support, and testing costs for customers.

·         Meeting UI requirements enables your business customers who are located in the United States to comply with the Americans with Disabilities Act, which requires that they provide reasonable accommodation for employees with disabilities. It also enables government agencies, schools, and organizations receiving federal funding to comply with section 508 of the Rehabilitation Act, which was strengthened in the reauthorization of 1998. Similar legislation exists in a number of states and countries, and is pending in many more.

·         Meeting UI requirements enables your customers to purchase software that meets standards for usability, such as HFES/ANSI 200 and ISO 9241. Such standards will continue to expand to incorporate high-level requirements for usability and accessibility.

·         Meeting UI requirements enables over 49 million people in the United States who have disabilities to use your products. The U.S. Access Board estimates that one in five people, and one in eight Internet users, have some form of functional limitation.

·         Meeting UI requirements enables organizations to benefit by keeping valuable employees, even when they receive a permanent or temporary disability, such as repetitive strain injury associated with typing or using a mouse, or experience functional limitations that are a natural part of aging.

 

Requirements

5.1     Support standard system size, color, font, and input settings

5.2     Ensure compatibility with the High Contrast option

5.3     Provide documented keyboard access to all features

5.4     Provide notification of the keyboard focus location

5.5     Do not rely exclusively on sound

5.6     Do not place shortcuts to documents, help, or uninstall in the Start Menu

5.7     Support multiple monitors

 

References

Guidelines for accessibile software design: See http://www.microsoft.com/enable

Microsoft Active Accessibility: See the Platform SDK 

Microsoft media player: http://www.microsoft.com/windows/mediaplayer

Microsoft Windows Guidelines for User Interface Design

Available from MSDN and MS Press.

How to Comply with Requirements for UI Fundamentals

5.1    Support standard system size, color, font, & input settings

Your application must read and use system-wide user interface settings when displaying customized controls or window content.  Standard controls provided by USER32.DLL and COMCTL32.DLL automatically support all of the required settings.  Applications can add support for these settings to their own windows by calling DefWindowProc in the window procedure. Applications should be careful to handle these settings when:

·         Creating custom controls

·         Creating owner-drawn controls

·         Superclassing or subclassing to alter the normal standard control behavior

·         Handling a message and not calling DefWindowProc (especially when drawing any non-client areas)

·         Handling low-level input that bypasses normal mouse and keyboard messages (such as double-click and shift-state detection)

 

These settings are queried using the GetSysColor, GetSystemMetrics, and SystemParametersInfo functions. For more information, see “System Information Functions” in the Microsoft Platform SDK at http://msdn.microsoft.com/library/psdk/sysmgmt/sysinfo_8stv.htm


 

All applications must support:

  SPI_GETHIGHCONTRAST

All GetSysColor settings are required for menus, dialog boxes, and other standard UI elements.  See Section 2, below.

  SPI_GETWORKAREA

Primary display monitor work area size

 

Customized combo boxes must support:

  SPI_GETCOMBOBOXANIMATION

Slide-open effect for combo boxes must be disabled when this setting is false

 

Customized keyboard handlers (low level input) must support:

  SPI_GETKEYBOARDDELAY

  SPI_GETKEYBOARDSPEED

Keyboard repeat-delay setting

Keyboard repeat-speed setting

  SPI_GETFILTERKEYS

Expanded range for above

 

Customized menus must support:

  SM_CYMENUCHECK, CXMENUCHECK

Default menu check-mark dimensions

  SM_CYMENU

Single-line menu bar height

  SPI_GETNONCLIENTMETRICS

      IfMenuHeight

      lfMenuFont

      lfMessageFont

 

Menu bar height

Menu bar font

Message box font

  SPI_GETSELECTIONFADE

Menu fade must be disabled when this setting is FALSE

  SPI_GETMENUANIMATION

Menu animation must be disabled when this setting is FALSE

  SPI_GETMENUFADE

Menu fade animation must be disabled when this setting is FALSE

 

Specialized mouse functions must support:

  SM_CYDOUBLECLK,

  SM_CXDOUBLECLK

Maximum vertical and horizontal distances the mouse can move between successive clicks and still be interpreted as a double-click

  SM_CYDRAG, SM_CXDRAG

Minimum vertical and horizontal distances the mouse must be moved with button down to start a drag operation

  SPI_GETMOUSEHOVERHEIGHT

  SPI_GETMOUSEHOVERWIDTH

Height and width of the rectangle within which the mouse pointer has to stay to activate hover effects

  SPI_GETMOUSEHOVERTIME

Mouse hover time

 

Customized scroll bars must support:

  SM_CYHSCROLL

  SM_CXVSCROLL

Height of horizontal scroll bar

Width of a vertical scroll bar

                                    

Application sounds must support:

  SPI_GETSHOWSOUNDS

When TRUE, the application must present all information visually rather than by sound alone

 

Customized tooltips must support:

  SPI_GETNONCLIENTMETRICS

      SPI_lfStatusFont

 

Font used in status bars and tooltips

  SPI_GETTOOLTIPANIMATION

ToolTip animation must be disabled when this setting is FALSE

 

Customized window frames must support:

  SM_CYSMCAPTION

Small caption height

  SPI_GETNONCLIENTMETRICS

      IfCaptionFont

 

Caption font information

  SM_CYBORDER, SM_CXBORDER

Minimum thickness of a line, in pixels. Applications should not draw lines thinner than this because on high-resolution monitors a 1-pixel line might be nearly invisible. (The display driver sets this number, and it is also increased when the user selects the Custom System Font Size in Control Panel.)

  SM_CXEDGE

  SM_CYEDGE

Thickness of a 3D edge, in pixels. Each 3D edge is comprised of two adjacent lines, so the thickness is 2 * SM_CxBORDER.

  SM_CXSIZEFRAME

  SM_CYSIZEFRAME

Thickness of the complete resizable window frame, in pixels.

  SM_CYFIXEDFRAME

  SM_CXFIXEDFRAME

Thickness of a non-resizable window frame, in pixels. This is made up of one 3D edge whose thickness is SM_CxEDGE plus one line of space whose thickness is SM_CxBORDER.

 

5.2    Ensure compatibility with the High Contrast option

Your application must be compatible with the High Contrast option, which indicates that the user requires a high degree of contrast to improve screen legibility.Standard controls provided by USER32.DLL and COMCTL32.DLL automatically support all of the required settings. Applications only need to support it explicitly when creating custom window classes or controls or altering the normal behavior of standard windows or controls.

Applications can determine the value of the High Contrast option using the SystemParametersInfo function with the SPI_GETHIGHCONTRAST constant. When this option is set, your application must:

·         Display all menus and dialog boxes using the color scheme returned by GetSysColor function. This also applies to any other UI elements that are required to adjust colors in the application’s UI.

·         Allow the user to adjust the colors used to display everything in the application’s windows.

·         This must be possible using display options that override the colors normally used by the application or specified in the document, and must not alter the content of the document or affect other users.

·         The preferred method is to use the corresponding colors returned by the GetSysColor function, but the application can provide its own display options.

·         Always draw foreground objects in colors designated as foreground colors and fill backgrounds with the corresponding background colors. This is required whether colors are selected using the GetSysColor function or through the application’s own options. For example, anything drawn using window text color (COLOR_WINDOWTEXT) must be drawn on the window background color (COLOR_WINDOW), and anything drawn using highlight text color (COLOR_HIGHLIGHTTEXT) must be drawn on highlight background (COLOR_HIGHLIGHT).

·         Make sure any information normally conveyed by color is available through other means, such as sound or a visual display, because the user may have chosen a monochrome appearance scheme.

·         Omit any images or patterns drawn behind text, and make sure any important information conveyed with such backgrounds is available through other means.

Note: Users can adjust the High Contrast option from the Accessibility Options section of Control Panel, by selecting the Display tab and then the Use High Contrast check box.

Users can adjust the values returned by GetSysColors using the Display section of Control Panel, by selecting the Appearance tab.

The High Contrast option can be used with any appearance scheme, and selecting a scheme through the Display section of Control Panel does not affect the High Contrast option setting.

 

Exception: Certain application features may be exempted from High Contrast requirements when the use of color is intrinsic and indispensable to the goal of the feature. Examples include:

·          Palettes or swatches where the user selects from a range of displayed colors. In this case, the application can display the color but must provide a text description such as a name (light blue) or numeric value (RGB 0, 255, 255).

·          Animation, video, and graphic images when the information content is available through other means.

·          Entire applications are exempted only when it can be shown that the application has no value without the use of color. For example, painting programs may be exempted, but drawing programs where the user manipulates shapes would not be exempted.

·          Reference and educational titles will not be exempted.

 

When the major features in the application support the High Contrast option, exceptions may also be made for minor features that are not required for the operation of the program.

Requests for exemptions are judged on a case-by-case basis. You must detail these exceptions in your Vendor Questionnaire.

5.3    Provide documented keyboard access to all features

Your application must provide keyboard access to all features, so that a mouse or other pointing device is not required for its use. Standard controls provided by USER32.DLL and COMCTL32.DLL automatically support all of the required settings. Applications must explicitly provide this support only when:

·         Creating custom window classes or controls

·         Altering the normal behavior of standard windows or controls

·         Assigning keyboard navigation in dialog boxes.

User interface elements that rely on standard Windows keyboard documentation should support all equivalent standard window class keyboard behavior. If a specific user interface element, such as a custom control, requires a mouse or other pointing device, its functionality must also be available through keyboard input.

All keyboard techniques required to operate the application must be documented, except for elements that follow Windows conventions, e.g.,  standard menus and controls. Applications must document non-intuitive complex procedures, customized window class usage, and controls that do not conform to normal conventions. The product’s standard documentation must either include this information or direct the user to the appropriate documents.

Example: Information can be delivered by online help, with text file on the product CD, or through the product’s Web site.

Note: Keyboard behavior of standard window classes is documented in The Microsoft Windows Keyboard Guide, which is available on http://www.microsoft.com/enable.

Exception: Exemptions may be made in the following cases:

·          Applications that rely on specialized input devices, such as graphing tablets.

·          Situations where the mouse targets are no larger than a pixel. For example, painting with the mouse. These features may rely on the MouseKeys feature built into the 32-bit Microsoft Windows operating systems to allow users to move the mouse pointer using the keyboard. However, this is not acceptable for drawing when the user can independently manipulate separate text and graphic objects. This exemption applies to individual features within a product, not to the entire application.

 

When the major features in the application have keyboard access, exceptions may be made for minor features that are not required for the operation of the program.

Requests for exemptions are judged on a case-by-case basis. You must detail these exceptions in your Vendor Questionnaire.

 

5.4    Expose the location of the keyboard focus

Your application must visually indicate the location of the keyboard focus, and notify other software of this location by using Microsoft Active Accessibility™ or by moving the system caret.

The application must display a visual focus indicator at all times when it is the active window so users can anticipate the effects of keystrokes they type. Exposing its location to other software enables the use of the panning software supported by many display adapters and accessibility aids such as the Magnifier accessory included with Windows 98 and Windows 2000.

When it is not feasible to use Microsoft Active Accessibility, the application may indicate the focus location by moving the system caret. The caret is normally the blinking vertical bar that the user sees when editing text, but it can be placed anywhere on the screen, made any shape or size, and even made invisible. If it is invisible, it can be moved to indicate the focus location to applications without disturbing what the user sees on the screen.

To create an invisible caret call the CreateCaret function to set the caret’s size and shape and the SetCaretPos function to move it to wherever you are drawing the visual focus indicator (the highlighted cell, icon, button, and so on). Note that it is present but remains invisible unless you explicitly make it visible.

Each time the focus moves to a new object with a different size, the application should call DestroyCaret and then use CreateCaret to specify the size of the new object. The system caret must cover the bounding rectangle of the screen element, so that screen magnification tools can allow the user to zoom-in on different portions of the region.

An application should only display focus and selection indicators when they are in the active window. When the window loses activation, the application should remove the visual indicator and call the DestroyCaret function.

Exception: Applications and features that are exempt from the keyboard access requirement as described earlier in this section are also exempt from the requirement to expose keyboard focus location. However, it is strongly recommended that applications expose the keyboard focus location for any feature that provides keyboard access.

5.5    Do not rely exclusively on sound

Applications should not convey important information exclusively by sound. If sound is the default method for conveying information, the application must provide other options to express this information.

Closed captioning or synchronized highlighting is recommended when conveying information by audio and video content longer than several seconds. Closed captioning is supported by the Windows Media Player since version 5.2.  See http://www.microsoft.com/enable and http://microsoft.com/windows/mediaplayer for more information.

The application must provide visual equivalents of all information normally provided by sounds alone when the ShowSounds option is selected. If the ShowSounds option is selected when the application starts, the application must either turn on these additional visuals or explicitly ask the user whether they would like them.

The user may select the ShowSounds option in the Control Panel to notify applications that all information should be conveyed visually rather than relying on audible means. This option is set through the Accessibility Options section of the Control Panel. Applications can determine the current value of the ShowSounds option with the SystemParametersInfo function to query SPI_GETSHOWSOUNDS.

Applications are not required to display visual equivalents of music or other sounds that convey no information. However, they are required to display a visual indication that such sounds are playing when the ShowSounds flag is set.  When a sound merely emphasizes a visible event, the application does not need to provide an additional visual indication that the sound is present. For example, when a message box appears, it is often accompanied by a warning sound.  When a user presses an invalid direction key, the selection fails to move and a warning beep is produced. In these cases the application does not need to display additional visual feedback. However, when user input or an external event can trigger results indicated or distinguished exclusively by sound, additional visual notification is required.

 

5.6    Do not place shortcuts to documents, help, or uninstall in the Start Menu

The Start Menu is designed to give users easy access to launch applications. Usability studies show that when the Start Menu becomes too cluttered, users can no longer do this.

·         Do not place shortcuts to documents, such as readme files, in the Start Menu. If you have important information that the user should see, consider displaying that information during the install process.

·         Do not put shortcuts to help files in the Start Menu. Users can access help once they launch the application.

·         Do not place shortcuts to uninstall in the Start Menu. The Add/Remove Program control panel applet provides this functionality.

The following behaviors, though not required, are recommended:

·         Place your icon to launch your application directly under Start -> Programs.  Avoid placing it in a folder under programs. In particular, do not create a folder in the Start Menu in which you only put one item. Often, applications will create a folder based on Company name and then put a single shortcut to launch the application inside that folder. Instead, consider renaming the shortcut to include the company name and dropping the use of the folder.

Programs à      My Company à     My App      (Avoid this)

Programs à      My Company My App              (Recommended)

 

·         Do not put anything in the top of the Start Menu, as users consider this their own personal space.

·         If you have support applications, tools, or utilities associated with your application, and you wish to publish these in the Start Menu, create a single folder in the Start Menu as a peer of the icon to launch your application and place them there.

5.7    Support multiple monitors

In a multiple monitor system, the top left pixel on the primary monitor always has coordinates 0,0. Valid screen coordinates can exist anywhere in relation to this location.  In particular:

·         Pixels in multiple monitor systems can have negative values for one or both coordinates, since users can place secondary monitors to the left and above the primary monitor.

·         Users may also place several monitors in a horizontal or vertical row. At high screen resolutions, coordinates for the monitor furthest from the primary may be much larger than would be possible on any single monitor system.

Your application must support users who have two or more monitors installed.  This support is automatically provided by the operating system, unless your application specifies screen coordinates in any of the windows it creates.  If your application does specify screen coordinates for any window, then:

·         It must handle negative coordinates, as well as large coordinates that are outside the traditional display space.

·         Dialogs must not open in a location that splits them across two monitors. Applications that specify dialog locations as the center of the desktop should use the center of a physical monitor instead.

·         If you cache the locations of your application’s windows so they appear at their previous screen locations when the user starts your application, you must accommodate any changes in the user’s monitor arrangement and change the display locations of your windows accordingly. When your application opens windows, it must verify that the locations where it intends to restore its windows correspond to locations on the current multiple monitor configuration.

·         Each monitor can have a different resolution and color depth. If your application allows images to span monitors, and your application cannot successfully combine the images from several monitors of different resolutions/color depths, it must degrade gracefully and give the user meaningful options, such as resizing the monitors, limiting the image to a single monitor, or accepting a lower definition image.

·         Some applications must be especially aware of multiple monitor issues, including the following:

·         Applications that capture all or part of the desktop as a graphic.

·         Applications that float toolbars.

·         Applications that switch among multiple simulated desktops.

·         Screen savers.

How to Pretest Applications for UI Fundamentals

 

To pretest system metrics support:

1.   Open Control Panel, and then open the Display applet.

2.   Choose the Appearance tab.

3.   Select a scheme with the “(extra large)” designation, such as Windows Standard (extra large) scheme. Click on Apply.

4.   Test the application’s main screens, dialog boxes, and controls to ensure that these changes have been instated and the application is still usable.

Screen elements should be displayed correctly and compatible with the appearance scheme, i.e., menu items, title bars, icons and icon titles, window borders and scroll bars are displayed with appropriate sizes and fonts. Text and controls should never overlap and text should not be truncated inappropriately. Examples of appropriate truncation are

·         Text strings too large to be displayed in a column in a list view control. The beginning of the text is displayed, followed by “…” to indicate the truncation.

·         Text that runs beyond the frame of a window, but can be viewed using the horizontal or vertical scroll bar.

 

To pretest high-contrast support:

1.   Open Control Panel, and then open the Accessibility Options.

2.   Choose the Display tab.

3.   Select the Use High Contrast option.

4.   Choose Settings.

5.   Choose Custom and verify that High Contrast Black is selected. Apply these settings.

6.   Go back into your product and test the major screens, dialog boxes, and controls to ensure that these changes have been properly reflected.

7.   Repeat, selecting the High Contrast White option in step 5.

The application should still be usable. Screen elements should be displayed correctly and be compatible with the appearance scheme. For example, make sure that text contrasts with its background, that graphics on toolbar buttons are distinguishable, that lines are still visible, and that no images or complex backgrounds appear behind text.

If anything within the window is not displayed using the selected color scheme, verify that the user can adjust the display colors without having to alter the document.

 

To pretest documented keyboard access:

1.   Open Control Panel, and then open the Accessibility Options.

2.   Choose the Keyboard tab.

3.   Select the Show Extra Keyboard Help. Apply these settings.

4.   Exercise the major functions within your application without using a mouse.

5.   Verify that a mouse is not required for any activity.

For example, if a command on a toolbar can only be used with a mouse, make sure that the equivalent command is also available through a menu or through a documented keyboard shortcut.

The product documentation and user interface must make clear how to carry out a task using the keyboard or it must be readily inferred using knowledge of standard Windows keyboard conventions. If the documentation is not clear, the product fails the requirement to use adequately documented keyboard UI.

6.   Verify that all menu items and controls have underlined access keys.

 

To pretest exposure of keyboard focus:

1.   Use the Magnifier accessory. From the Start menu, choose Programs -> Accessories -> Accessibility -> Magnifier.

Magnifier is included with Windows 98 and Windows 2000. For Windows 95, install the Microsoft Active Accessibility SDK to get Magnifier. Magnifier is not available for Windows NT 4.

2.   Navigate through your application using the keyboard, making sure that Magnifier accurately tracks and displays the area with the keyboard focus. In particular, verify that Magnifier:

·         Shows the correct focus location when you navigate or type within a document, text field, or table.

·         Shows the correct focus location when you navigate in menus, dialog boxes, toolbars, list boxes, or other controls.

·         Shows the correct focus location when you extend a selection in text or in a multiple-selection list box, list view, or tree view.

·         Shows the correct focus location when you return to your application from a dialog box, menu, or another application.

 

To pretest use of sounds:

1.   Open Control Panel, and then open the Accessibility Options.

2.   Choose the Sounds tab.

3.   Select the ShowSounds option. Apply these settings.

4.   Go back into your product and test the major functions. Notice any sounds that are played that do not have equivalent visual feedback. In particular, look for animations and audio or visual clips.

If any information is conveyed using sound and the same information is not available through textual means, the application does not meet requirements for supporting the ShowSounds option. 

 

To pretest your application for multiple monitor support:

·         Move each of your application’s windows to every monitor, including monitors located to the left and above the primary monitor. The windows should move to any monitor without error dialogs, hangs or crashes.

·         Resize each resizable window across all monitors.

·         Maximize all windows that can be maximized on each monitor. Windows should maximize to the current monitor, not across monitors to the entire desktop.

·         For windows that can be minimixed:

·         Resize and move each window so it spans all monitors. Minimize each window, then restore it. The window should restore to its original position, spanning several monitors.

·         Maximize each restored window. Each window should maximize to one physical monitor, not to multiple monitors or the virtual desktop.

·         Test selecting and dragging elements on windows that span several physical monitors.

·         Test floating toolbars that can move off your application’s parent window by maximizing the parent on one monitor and moving the toolbars to a separate monitor.

·         If your application supports dragging graphics objects, set multiple monitors for different screen resolutions and color depths. Then drag the graphics from one monitor to another. The graphics’ appearance should adapt to each monitor when dropped.

·         If your application acts directly on the desktop:

·         Test all functions with monitors to the left and above the primary monitor.

·         Set all monitors for the highest possible resolutions and greatest color depths to test your application’s ability to accommodate very large pixel coordinates

·         Set each monitor at a different color depth and screen resolution, then exercise your application. Your application must successfully accommodate the differences or provide a meaningful message to the user with suggestions on how to change the configuration so the program will work as intended


Chapter

Describes the requirements for ensuring that the application can participate in system-wide power management.

OnNow/ACPI Support

Summary of OnNow/ACPI Requirements

Rationale

The OnNow design initiative is a set of design specifications for system hardware and software applications which enable a PC to deliver the instantly available capabilities consumers expect from TVs, VCRs, stereos and other appliances.

Applications must participate in system-wide power management decision-making to establish error-free handling of power down and power up scenarios. This participation includes responding appropriately to events such as sleep requests and wake notifications so that user and application data is preserved.

Note: In this chapter, the term “sleep” means that the system is on standby or is in hibernation. To the application, standby and hibernation are the same. The difference occurs in how the operating system determines what gets powered-down. The application does not need to provide any additional feedback to make this determination.

Customer Benefits

·         OnNow reduces power consumption via the Advanced Configuration and Power Interface (ACPI).  The system is able to enter a lower power state (or sleep mode) that appears to be “off” but is still powered enough to enable the system to power up (or wake) to handle timed events or device related needs such as receiving a fax.

·         The PC is instantly available to the user because it can rapidly return from a low power state to a fully-functional state.

·         Customers can rely on their PCs to power down and up in a way that is easily understood and predictable.

 

Requirements

6.1     For applications allowed to prevent sleep when busy, indicate busy application status properly

6.2     In the non-connected state, your application must allow sleep and resume normally

6.3     In the connected case, handle sleep requests properly

6.4     Handle wake from normal sleep without losing data

6.5     Handle wake from critical sleep properly

 

References

OnNow and Power Management: see http://www.microsoft.com/hwdev/onnow.htm

OnNow Power Management Architecture for Applications:

http://msdn.microsoft.com/library/backgrnd/html/onnowapp.htm

SHIsFileAvailableOffline Function

http://msdn.microsoft.com/library/psdk/shellcc/shell/functions/SHIsFileAvailableOffline.htm

                  

How to Comply with OnNow/ACPI Requirements

About OnNow Power Management in Windows

The key issue for applications is that upon waking from a sleep state it is possible that previously available network connections and removable drives (such as disks in docking stations) may no longer be available. To help reduce the risk of data loss problems, applications are notified of power management events through the WM_POWERBROADCAST message. Applications must respond to these messages properly so the system can transparently enter and wake from sleep.

When the operating system initiates a sleep request, it sends the running applications a query to determine if it is safe to go to sleep. It does this by sending a WM_POWERBROADCAST message with a wParam value of PBT_APMQUERYSUSPEND.

Once all running applications have responded[1] to the suspend query, the OS will send out a new WM_POWERBROADCAST with one of two wParam values.  If all applications responded TRUE to the PBT_APMQUERYSUSPEND message, the operating system will send PBT_APMSUSPEND to notify applications that the system is about to go into sleep.  If any application returned BROADCAST_QUERY_DENY to the PBT_APMQUERYSUSPEND message, the OS will send a PBT_APMSUSPENDFAILED message.  In this case, the application should restore its state and resume normal operations.

Key Windows Messages:

PBT_APMQUERYSUSPEND: This message serves as a request to the application to determine if it can go to sleep and provides the primary opportunity for applications to take any necessary actions to prepare for sleep. Note that the system will wait approximately 20 seconds for an app to pull this message from the message queue.  If the system doesn’t see the message pulled then it will assume a true response.  (This is done to handle applications that are not processing system messages, perhaps because they are no longer functioning properly.)  However, once the message is pulled from the message queue, applications have as long as they need to determine if they can allow sleep, perform any required operations, and respond to the message. Of course, applications should use the minimal amount of time needed to prepare for sleep so as not to cause unreasonable delays.

PBT_APMSUSPEND: This message is merely a notification that the system is about to sleep. The operating system allows approximately 20 seconds for an application to handle this notification. After 20 seconds the OS will continue the sleep state processing. Thus, applications that are performing operations after their 20 second allotment could potentially have their operations interrupted. Therefore, applications should initiate the majority of their shut-down tasks when they receive the PBT_APMQUERYSUSPEND, as there may not be enough time if they wait till receiving PBT_APMSUSPEND. 

Note: In some circumstances, the sleep request may be canceled. If this occurs, the operating system follows the WM_POWERBROADCAST/PBT_APMQUERYSUSPEND message with WM_POWERBROADCAST/PBT_APM_QUERYSUSPENDFAILED message.  In this case, the application should restore all its data to a working state and continue all operations normally.

The zero bit of the lParam value, known as the UI bit, indicates whether user interaction is possible. If no user display device is available (e.g. the user has closed the laptop lid or the system believes there is no user present), the system will set the UI bit to 0. Otherwise the UI bit will be 1.

 

Considerations for Applications that install as services

By default, the system does not notify services of power management events. The system will initiate power state transitions without any action required on the part of the service. 

If your application installs services and those services must participate in power management decisions:

1.   You must follow these steps to receive notification of power management events:

·         The service must notify the system that the service will accept and process power events as follows:  When the service calls SetServiceStatus, it must set the SERVICE_ACCEPT_POWEREVENT bit in the dwControlsAccepted field in the SERVICE_STATUS structure.

·         The service’s control handler must be a “HandlerEx” function as described at http://msdn.microsoft.com/library/psdk/winbase/services_3smw.htm.  Services must use the RegisterServiceCtrlHandlerEx function to register a “HandlerEx” control handler function. “HandlerEx” control handler functions support the new power event control codes (whereas “Handler” control handler functions do not).

2.   Once you have enabled notification of power management events for your service, the service must respond and process the SERVICE_CONTROL_POWEREVENT control requests in the same manner as for WM_POWERBROADCAST messages enumerated earlier in this chapter to comply with the OnNow/ACPI requirements. A SERVICE_CONTROL_POWEREVENT is equivalent to an application receiving a WM_POWERBROADCAST message.

 

Comparison of Power Management notifications

 

Non-Service

Service

Power Event

WM_POWERBROADCAST

SERVICE_CONTROL_POWEREVENT

Event parameter

wParam

dwEventType

Event parameter

lParam

lpEventData

Accept Request

Return TRUE

Return NO_ERROR

Deny Request

Return BROADCAST_QUERY_DENY

Return any Error code

 

 

6.1    For applications allowed to prevent sleep when busy, indicate busy application status properly

If the system detects that it is idle for extended periods of time, it will attempt to go to sleep. The idle times that Windows uses for putting the system to sleep are set using the power management control applet.

Some applications perform functions that are readily visible to the user but may appear to the system as being idle (e.g. slide presentations, DVD movie viewing, CD audio playing).  In these cases, the expectation of the user is that the system will not sleep during these operations because he/she considers the system to be busy.  In these scenarios only, an application must signal to the system that it is not idle.  One way to achieve this is to call the SetThreadExecutionState() API function, which marks the computer as busy.

When marked as busy, the operating system will not send sleep requests as a result of the computer being idle. For example, the Windows 2000 redirector will mark a thread as busy if the thread has an open file on a network device, so in this case an application would not receive sleep requests from the operating system unless the user specifically requests the system to sleep.

Note, applications that use SetThreadExecutionState() will still receive sleep requests if the user specifically requests the system to sleep. These requests must be handled as specified in all the other requirements in this chapter.

Calling SetThreadExecutionState with the ES_SYSTEM_REQUIRED flag will keep the system from going to sleep if it thinks it is idle.  Calling it with the ES_DISPLAY_REQUIRED flag will keep the display from being turned off if the system thinks the display is idle.

Note that calling the SetThreadExecutionState function without the ES_CONTINUOUS flag will simply reset the idle timers and the system will go to sleep if the timers run out again.  To keep the system or the display awake it may be necessary to use the ES_CONTINUOUS flag along with either the ES_SYSTEM_REQUIRED or the ES_DISPLAY_REQUIRED flag.  This will freeze the respective timers.  If the ES_CONTINUOUS flag is used in conjunction with ES_DISPLAY_REQUIRED or ES_SYSTEM_REQUIRED, applications should then release the idle timers by resending just the ES_CONTINUOUS flag when there is no longer a need to prevent them from timing out.

 

6.2    In the non-connected state, your application must allow sleep and resume normally

The “non-connected” case is when the application does not have any network resources open.

If an application is in the non-connected state, it must respond TRUE when it receives a PBT_APMQUERYSUSPEND request from the operating system. Upon waking, it must resume to stable state (see Requirement 6.4).

Note about Client Side Caching:

If the user has enabled Client Side Caching (CSC), it is not readily apparent whether a file is on a network or not. The Client Side Caching feature in Windows 2000 allows a user to store an offline version of a network file locally. This is done transparently to the application.  Thus, even in the non-connected case, a file in the client side cache will appear as a network file.

If the file is in the cache, your application must still allow sleep. To determine whether the file or folder is in the cache, use the SHIsFileAvailableOffline API. It also determines whether the file would be opened from the network, from the local Offline Files cache, or from both locations. For details on this API, visit http://msdn.microsoft.com/library/psdk/shellcc/shell/functions/SHIsFileAvailableOffline.htm.

6.3    In the connected case, handle sleep requests properly.

The “connected” case is when the application has a network resource open. An example would be if your application has a file open on the network.

Your application must respond to PBT_APMQUERYSUSPEND in one of the following ways:

1.   If your application can avoid data loss, the application should prepare for sleep by ensuring that all outgoing operations are completed and then return a value of TRUE for this message.

2.   If data loss is possible (e.g. an application has unsaved data on a network location), the application should check the UI bit to see if interaction with the user is possible.

·         If the UI bit is 0 (e.g. user interaction is not possible), the application must either return BROADCAST_QUERY_DENY, or wait until the operation causing the busy status is finished, and then prepare to go to a sleep state and return TRUE.

·         If the UI bit is 1, the application should query the user to determine the user’s desired course of action. Some suggested courses of action are:

·         Offer to save the user’s work and proceed to sleep.

·         Offer to discard the user’s work and proceed to sleep.

·         Offer to cancel the sleep event.

·         Instruct the user on the actions required by the user to allow a sleep request.

·         If the risk of data of loss is eliminated while waiting for user input (for example your app was processing a transaction when the sleep request was sent, and the transaction completes before the user responds), your app should automatically allow sleep.

 

3.   Your application may deny sleep, provided it either gives the user the option to rectify the non-sleeping situation or gives direction on how the user can get to a state that allows sleep (though this is not preferred behavior).

 

6.4    Handle wake from normal sleep without losing data

When the system wakes from sleep mode the operating system will notify the applications with a WM_POWERBROADCAST/PBT_APMRESUMESUSPEND message.  The application must then restore itself to its pre-sleep state, preserving all data while maintaining app and system stability. If any data cannot be fully restored, the application must notify the user, and it may seek the user’s aid in restoring data to a state acceptable to the user.

Note that when the system wakes automatically (from a timer), the system broadcasts the PBT_APMRESUMEAUTOMATIC event to all applications. Because the user is not present, most applications should do nothing at this point. Event-handling applications, such as fax servers, should handle their events. If you wish to determine whether the system is in this state, call the IsSystemResumeAutomatic function.  (IMPORTANT: Whenever the system wakes from S4 - for whatever reason - the OS always treats this as an automatic event because it has no way of knowing why it woke from S4.  In this case, it will always send the PBT_APMRESUMEAUTOMATIC message.)

If the system detects user activity after broadcasting PBT_APMRESUMEAUTOMATIC, the system will broadcast the PBT_APMRESUMESUSPEND event and turn on the display.  At this point this message (PBT_APMRESUMESUSPEND) should be handled by all apps as described above.

 

6.5    Handle wake from critical sleep properly

In certain situations, the operating system may need to perform a critical sleep operation—for example, if battery capacity is critically low, or if the computer temperature is critically high and must be shut down to prevent hardware damage. A user may also initiate a critical sleep request in an urgent situation—for example, the user has to board a plane and must power down the computer instantly.  In cases of critical sleep, the applications will not be notified by the operating system of the impending sleep event. Your application will not get the opportunity to perform any actions defined in the previous requirements. When the computer is wakened, the operating system will indicate in its wake notification whether the shut down was critical by sending the PBT_APMRESUMECRITICAL notification.

Upon waking from critical sleep, applications must not crash and must wake to a stable state—no stalls, crashes, or corruption of files that were not opened by the application. Data may be lost, but the application should notify the user of the data loss that occurred. In general, the application should handle the at least as well as they recover when restarted after either a system or application crash.

 

How to Pretest Applications for OnNow/ACPI Support

Verify applications allow and resume from normal sleep in the non-connected case:

·         Open a file on a local hard disk, edit it—don't save—and put the computer to sleep, and then wake the computer. Verify that the application continues to run, the file can be saved, and so forth.

·         To test sleep when client-side caching is enabled:

·         Make a file that is on a network share available for offline line. (Right-click on the file and select “Make Available Offline”)

·         Disconnect from the network.

·         Open that file from within your application

·         Request the system to sleep and verify that the system goes to sleep correctly.

·         Then wake the computer and verify that the application continues to run and the file is loaded.

 

Verify applications respond properly in the connected case:

·         Open a file on the network.

·         Attempt to put the system to sleep.

·         Verify that the one of the following occurs:

·         The system goes to sleep correctly. Upon waking the computer, verify that the application continues to run and that the application attempts to reopen the file.

·         The application prompts the user to determine the appropriate course of action.

·         If the application denies sleep, it must provide the user information on how he or she can get to a state that allows sleep.

 

 

Pretest presentation applications for OnNow/ACPI compliance:

1.   In the Power control panel, set the system idle time as low as possible.

2.   Start the application and play a presentation.

3.   Wait for a time longer than the system idle time, and verify that the computer does not go to sleep and that the display does not go blank during that time.

 

Verify that applications respond properly to sleep requests when data loss could occur:

1.   Start the application and get it to a point where it starts operations that might corrupt data if interrupted.

2.   Press the power button to put the computer to sleep

3.   Verify that the application puts up a dialog box to prompt the user about possible loss of data. Test the following cases:

·         Respond “NO” to the dialog box and verify that the computer doesn’t go to sleep and that the application continues as normal without losing any data.

·         Respond “YES” to the dialog box and verify that the computer goes to sleep. Wake the computer and ensure that the computer doesn’t hang or cause the operating system to crash; also ensure that the application doesn’t hang or crash, but that it notifies the user of any possible data loss and attempts to recover all possible data.

 

Verify response to critical sleep requests:

1.   Under the start menu select “Shut Down”.  In the Shut Down dialog box, select the “standby” option while holding down the CTRL key. This will force a critical standby to occur.

2.   Wake the computer by pressing the power button. Verify that your application does not cause any destabilizing behavior such as hanging or crashing, and that it attempts to recover all possible data. If user data is lost, the application must inform the user.

 


Chapter 7

Describes requirements for ensuring that an application continues to function correctly after the user upgrades to the Windows 2000 operating system.

Application Migration

Summary of Migration Requirements

Rationale

Millions of users today are running Windows 95, Windows 98, or Windows NT Workstation 4. Looking ahead, Windows 2000 Professional will increasingly become the predominant operating system of choice. Many of those Windows 95/98 and Windows NT 4 machines will be upgraded to Windows 2000 Professional. The goal of this requirement is that when users upgrade their operating system, previously installed applications will continue to function as before, with all preferences and privileges working after the upgrade.

Customer Benefits

·         Applications work properly after customers upgrade to new operating systems, with no loss of functionality.

·         Customers experience reduced Total Cost of Ownership (TCO).

·         End-users’ experience with their applications and the operating system is the same or better after the upgrade.

 

Requirements

7.1     Application must continue to function after upgrade to Windows 2000 Professional without reinstall

 

References

Microsoft Platform SDK: Migration Extension Interface

       http://msdn.microsoft.com/library/psdk/win9xmig/migport_6l2d.htm

How to Comply with Migration Requirements

7.1    Application must continue to function after upgrade to Windows 2000 Professional without reinstall

To be certified on Windows 95, Windows 98, or Windows NT Workstation 4, applications must remain fully functional after an operating system upgrade to Windows 2000 Professional.

In the ideal case, applications will use a single set of binaries and not require different configurations on different operating systems. This is the best way to ensure a smooth upgrade of your application.

In the event that your application utilizes features specific to a particular operating system, Microsoft suggests the following alternatives for you to ensure smooth application migration. While the method you choose is up to you, it is a requirement that the application successfully migrate:

·         When installing your application on one 32-bit Microsoft Windows operating system, the installer should install all the additional binaries that would be required to make the program operate on the other operating systems.  Ideally, your application should isolate platform-specific behavior into dynamically loaded modules. The application should determine at runtime which components to use. For example, if the application requires a different DLL on Windows 2000 than on Windows 98, the application should install both and pick the one to actually load and use at application startup time.  Use GetVersionEx to determine the version at runtime. 

If the application has platform-specific behavior, it should be written to detect an operating system change (e.g. the user upgrades the operating system after the app is installed).  If the operating system changes, the application should be able to function properly on the new operating system.  For example, if the application uses a .VXD on Windows 98, and uses a service on Windows 2000, the application should automatically install the service after Windows 98 is upgraded to Windows 2000 Professional.  In addition, your uninstall process should dynamically check the OS version so that if the user has upgraded the OS since the initial install of the app, the correct uninstall routine will be called.

 

·         For Windows 9x applications that implement Windows 9x-specific behavior, you can write a migration DLL to ensure that your application will work correctly after an end user upgrades to Windows 2000 from Windows 95 or Windows 98. For example, if the application uses a .VXD on Windows 9x, a migration DLL could be used to implement the equivalent functionality on Windows 2000 as a service.  Windows 2000 Setup calls migration DLLs to perform any necessary migration of the application so it will continue to function for Win2000.

Note that migration DLLs can only be applied during the upgrade process from a Windows 9x system. Once the upgrade is complete, the DLL can no longer be applied. It is imperative that vendors make their migration DLLs broadly available for customers in a timely fashion. For more information about writing Migration DLLs, see the Migration Extension Interface in the Microsoft Platform SDK.

Place your Migrate.dll file, along with your company’s digital certificate and other associated files, on your distribution media, on the Web site from which the user installed the application, or on the user’s hard disk. If the files are installed on the hard disk, you must write the following to the Windows 95 or Windows 98 registry:

HKLM\Software\Microsoft\Windows\CurrentVersion\Setup\Migration DLLs

   Value name: <ProductID string >

   Value: <path to MIGRATE.DLL>

 

Note: The ProductID must match the string returned by the QueryVersion function described in the Platform SDK. Following this process makes the migration process “seamless” and silent for the user.

 

You might want to consider using the Migration DLL AppWizard. The Migration DLL AppWizard is a tool that creates a skeleton migration DLL with localization support. Full implementation details are available at:
http://msdn.microsoft.com/library/psdk/win9xmig/migport_6l2d.htm.

Please note that Microsoft does not provide technical support for the Migration DLL AppWizard.

How to Pretest Applications for Migration Requirements

The following procedures outline the minimal process you should undertake during your test. Note that you should repeat the tests for multiple user account scenarios, that is, default, roaming, workgroup, and domain users. The scenarios should also cover combinations of these user accounts.

To test the migration of your application:

1.   Install Windows 95, Windows 98, or Windows NT Workstation 4 on a computer.

2.   Install the target application on the computer.

3.   Exercise the functionality of the application so that user-specific settings, .INI files, registry entries, MRU lists, etc are populated as they would be on a normal user’s machine.

4.   Start Windows 2000 Setup and select the Upgrade option on the Welcome page.

5.       If you are using a migration DLL, insert the media containing the migration DLL when prompted. See the additional information below about using migration DLLs.

6.   Complete Windows 2000 Setup.

7.   Launch the migrated application on Windows 2000.

8.   Run test suites to determine if the application is fully functional.

9.   Repeat this process, starting out with other operating systems as appropriate.

 

Using Migration DLLs

Migrations DLLs must be tested for compliance as specified in the Microsoft Platform SDK. In particular, note:

·         Be sure to test your migration DLL in the scenario in which your application is NOT installed on the system.

·         No changes may be made on the Window 95/98 side of setup, except to the working directory and answer file.

·         All changes must be reported to setup using Migrate.inf.

·         It is recommended that no user interface (UI) be present.

·         No UI is allowed in unattended mode.

·         The Migration DLL must provide complete VENDORINFO structure, which gives company name, URL, support phone and support instructions.

·         The Migration DLL must understand localization issues and either run on all localized OSes, or provide a code page list of the code pages it supports.

·         Additional disk space usage in GUI mode setup is given to setup on Win9x via Migrate.inf.

·         If an incompatibility message is added to the upgrade report, the DLL must write the text in the proper language.

·         The Migration DLL must be restartable (the machine can crash during setup, and the Migration DLL still does its job).

 

For more information, see the Migration Extension Interface in the Platform SDK.


Appendix A

Best Practices

Important: The guidelines outlined in this appendix are not required to comply with the Application Specification for Windows 2000, but are strongly encouraged to provide a better user experience.

 

A-1   Installation of your application must not require a reboot on a freshly installed Windows 2000 system

Installation of your application should not require a reboot when you install it onto a freshly installed Windows 2000 system with no applications running unless you are deploying any of the following as part of your install.

·         Operating system update package, such as service pack

·         System-level drivers, such as 3rd party video drivers, disk drivers, and administrative level privileged services.

Generally, a reboot on Windows 2000 should not be necessary, even if applications are running. In the past a typical reason apps would reboot was because they were replacing a file that was in use at the time. However, on Windows 2000, these situations are greatly eliminated when this Specification is adhered to because:

·         The operating system will protect essential files as part of Windows File Protection, so applications must not attempt to replace them. These files will be updated as a group via an operating system update package, instead of in a piecemeal fashion by individuals applications.

·         Windows Installer service will automatically check to see if other applications or service processes are using files that it is attempting to update. In these cases Windows installer will prompt the user to shutdown those apps that are using those files. If the user does this, the application will install without a reboot. If the user does not shut down those applications, Windows Installer will prompt for a reboot.

·         Applications that deploy side-by-side components will not impact existing copies of these components, since side-by-side components are private copies.


A-2   Use SHGetFolderPath to determine special folder paths

Whenever you access any of the special folders in the following list, your application should use the Win32 APIs to dynamically obtain the proper language-specific folder names. The preferred way to do this is using the SHGetFolderPath API with the appropriate CSIDL constant. This function behaves consistently across Windows 95, Windows 98, Windows NT 4.0, and Windows 2000.

This API is redistributable via the SHFOLDER.DLL. SHFOLDER.DLL is installed by the Windows Installer redistributable. Software vendors are encouraged to redistribute this component as much as possible to enable this support on Windows operating systems prior to Windows 2000. Windows 2000 includes this DLL as a protected system file and, as such, this DLL cannot be replaced on Windows 2000 or greater.

To help ensure your application can run on Windows 9x, Windows NT 4 as well as Windows 2000, always link to the SHGetFolderPath implementation in SHFOLDER.DLL. Windows 2000 natively implements SHGetFolderPath in SHELL32.DLL, but other versions of Windows do not include SHGetFolderPath in SHELL32.DLL.

 

Standard folder

CSIDL constant name

Alternate Startup ([user], DBCS)

CSIDL_ALTSTARTUP

Alternate Startup folder (All Users profile, DBCS)

CSIDL_COMMON_ALTSTARTUP

Application Data ([user] profile)

CSIDL_APPDATA

Application Data (All Users Profile)

CSIDL_COMMON_APPDATA

Control Panel virtual folder

CSIDL_CONTROLS

Cookies folder

CSIDL_COOKIES

Desktop (namespace root)

CSIDL_DESKTOP

Desktop folder ([user] profile)

CSIDL_DESKTOPDIRECTORY

Desktop folder (All Users profile)

CSIDL_COMMON_DESKTOPDIRECTORY

Favorites folder ([user] profile)

CSIDL_FAVORITES

Favorites folder (All Users profile)

CSIDL_COMMON_FAVORITES

Fonts virtual folder

CSIDL_FONTS

History folder

CSIDL_HISTORY

Internet Cache folder

CSIDL_INTERNET_CACHE

Internet virtual folder

CSIDL_INTERNET

Local (non-roaming) data repository for apps

CSIDL_LOCAL_APPDATA

My Computer virtual folder

CSIDL_DRIVES

My Pictures folder

CSIDL_MYPICTURES

Network Neighborhood directory

CSIDL_NETHOOD

Network Neighborhood root

CSIDL_NETWORK

Personal folder ([user] profile)

CSIDL_PERSONAL

Printers virtual folder

CSIDL_PRINTERS

PrintHood folder ([user] profile)

CSIDL_PRINTHOOD

Program Files folder

CSIDL_PROGRAM_FILES

Program Files folder for x86 apps on Alpha systems

CSIDL_PROGRAM_FILESX86

Programs folder (under Start menu in [user] profile)

CSIDL_PROGRAMS

Programs folder (under Start menu in All Users profile)

CSIDL_COMMON_PROGRAMS

Recent folder ([user] profile)

CSIDL_RECENT

Recycle Bin folder

CSIDL_BITBUCKET

SendTo folder ([user] profile)

CSIDL_SENDTO

Start menu ([user] profile)

CSIDL_STARTMENU

Start menu (All Users profile)

CSIDL_COMMON_STARTMENU

Startup folder ([user] profile)

CSIDL_STARTUP

Startup folder (All Users profile)

CSIDL_COMMON_STARTUP

System folder

CSIDL_SYSTEM

System folder for x86 applications on Alpha systems

CSIDL_SYSTEMx86

Templates folder ([user] profile)

CSIDL_TEMPLATES

User’s profile folder

CSIDL_PROFILE

Windows directory or SYSROOT

CSIDL_WINDOWS


A-3   Test your application under Terminal Services

Many enterprise customers use Terminal Services to provide Windows 2000 applications to an array of desktop and mobile clients. Applications running under terminal services run only on the server. The terminal server client performs no local processing of applications. This means that in a terminal services environment, multiple instances of the same application may be running on the same machine at the same time, serving different users.

Considerations for developers

1.   Because multiple users are running your application at the same time, it’s critical to store application and user data properly, as outlined in Chapter 4, “Data and Settings Management.”

2.   In a Terminal Services environment, multiple instances of your application will be running on the same machine. Your application’s .EXE and .DLL files must be written so multiple users can run your application on the same machine at the same time.  Particular considerations include:

·         File locking:  Ensure that files are not locked during use, as this could prevent multiple instances of the application, or processes under the application such as wizards, from running.

·         File permissions:  Users may not have access to system files, and may not have the same permission levels as the administrator who installed the application.

·         File locations: Per user data and configuration files must be stored separately to avoid collisions and manage permissions. In particular, applications must store temporary information on a per user basis  to avoid conflicts among users’ information and preferences. You should do this by using the GetTempPath API rather than using a hard-coded path.

3.   Terminal Services manages objects on a per-client basis for you. You only need to think about object management, if you do not want the operating system to do this for you. If a specific object should be available to all instances of the application, register the .DLL  or .EXE that creates the object, with the command “register filename /system”, or by changing the application to append \\GLOBAL to the name of the object when it is created.

How to Pre-Test

1.   Set up a Windows 2000 Server computer as a Terminal Server Host and configure it to allow both administrator and non-administrator access.  

2.   Install the application on this machine logged on as an Administrator.

·         The application must be installed in Terminal Server’s Install mode.  Use the command line ”change user /install” or use Add/Remove Programs in the Control Panel.  This is required so that Terminal Server can appropriately manage the registry for each user.  An installation script may also be required to adjust file and registry settings for multiple users. See the whitepaper referenced below, “Using and Developing Applications Compatibility Scripts.”

3.   On a separate client machine, log on to the Terminal Server Host with normal (non-Power, non-Admin) User privileges. 

4.   Ensure that all shortcuts, files and folders are available to the user.

5.   Launch each program in the application

6.   Run a full set of functionality tests on your application.

7.   Create customized interface, file option and new default settings for the user. 

8.   Log on as a different user and make sure that the setting changes you made for the first user are not the new defaults for the new user.

9.   Run a full set of functionality tests on your application simultaneously from two client computers as two different users.

10.  Run a full set of functionality tests on your application simultaneously from two client computers with one (non-Power, non-Admin) User and one Administrator.

Diagnosing Common Problems

·         If the problem was encountered while logged on to a client as a user without administrative rights, try to reproduce the problem on the Terminal Services server console as the same user. If the problem goes away, this indicates that the application is using a system resource or configuration. The console session has all system processes, such as SMSS.exe, RPCSS.exe, SERVICES.exe, and LSASS.exe, and the Windows NT services associated with it.

·         If the problem is still present on the Terminal Services server console, log on to a client machine as an Administrator and repeat the test.  If the error does not occur, the problem is probably a file permission problem. 

·         If the problem is still present, log on to the Terminal Services server console as the Administrator and repeat the test.  If the error does not occur, the problem may be caused by incorrect permissions or the application is using a system resource or configuration.

References

Optimizing Applications for Windows 2000 Terminal Services and Windows NT Server 4.0, Terminal Server Edition:

http://www.microsoft.com/windows/server/Technical/terminal/TSAppDev.asp

Using and Understanding APIs for Terminal Server:

http://www.microsoft.com/ntserver/terminalserver/techdetails/prodarch/api.asp

Using and Developing Applications Compatibility Scripts:

http://www.microsoft.com/ntserver/terminalserver/techdetails/prodarch/AppCompSc.asp


A-4   Clients query Active Directory for Services

Any client that is locating a Windows 2000 service should query Active Directory to obtain binding information for the services that are of interest.

In Windows 2000, services publish their existence via objects in Active Directory. The objects contain binding information that applications use to connect to instances of the service.  To access a service, an application does not need to know about specific computers; the objects in Active Directory include this information. An application queries Active Directory for an object representing a service (called a connection point object) and uses the binding information from the object to connect to the service.

In a distributed system, the computers are engines; the interesting entities are the services that are available. From the user's perspective, the identity of the computer that provides a particular service is not important. What is important is accessing the service itself.

To take advantage of the service-centric view afforded by the Active Directory Service, client applications must:

·         Query Active Directory for accessible services.

·         Present these services to the end user or automatically select the appropriate service connection point object.

·         Connect to the service using the binding information contained in the selected connection point object.

For examples and more detailed information, see the section titled “Searching Active Directory” in the Active Directory Programmer’s Guide at http://msdn.microsoft.com/developer/windows2000/adsi/actdirguide.asp.


A-5   Globalization

Globalization is the practice of designing and implementing software that is not locale dependent, i.e., can accommodate any locale. In software design, a locale is defined as a set of user preferences associated with a user’s language. A locale in Windows 2000 includes formats for date, time, currency and numbers; rules and tables for sorting and comparison; and tables of character classifications.

Other user preferences that a globalized application should accommodate include user-interface language, default font selection, language rules for use in spell checking and grammar, and input methods such as keyboard layouts and input method editors. See www.microsoft.com/globaldev for more details.

Guidelines for developing a globalized application include the following:

1.       Use Unicode as your character encoding to represent text. If your application must also run on Windows 9x, consider a method for using Unicode on those platforms, as described in Microsoft Systems Journal articles in the November 1998 and April 1999 issues. These articles are available at:

www.microsoft.com/globaldev/articles/singleunicode.aspwww.microsoft.com/globaldev/articles/multilang.asp

If you cannot use Unicode, you will need to implement features such as DBCS enabling, BiDi enabling, codepage switching, and text tagging. Guidelines related to this functionality are available at www.microsoft.com/globaldev.

2.       Consider using a multilingual user interface: launch the application in the default user interface language, and offer the option to change to other languages.

3.       Use the Win32 API NLS functions to handle locale sensitive data.

4.       Watch for Windows messages that indicate changes in the input language, and use that information for spell checking, font selection, etc.

5.       Use the Script APIs (Uniscribe) to layout formatted text on a page. This will allow your application to display multilingual text and complex scripts such as Arabic, Hebrew, Hindi, Tamil, and Thai.

6.       Test your application on in the following scenarios:

·         Where the system locale, the user locale, the input locale and the UI language each have different values and are all different from the localization language of the application

·         Where the system locale is not English (United States) and not the same as the application localization.

·         Where the user locale is new in Windows 2000 (e.g. Hindi)

·         Where the UI language is one of the right-to-left languages such as Arabic.

·         For a client/server application, where the client and server each have different locales

·         By using Regional Settings to customize the user locale (the more unusual the better for testing)


A-6   Localizability

In contrast to globalization, localization is the process of modifying an application so that its user interface is in the language of the user. Well designed software can be localized to any of the languages supported by Windows 2000 without changes to the source code, i.e., without recompilation. In addition to the guidelines for globalization mentioned above, those for localizability include the following:

1.       Isolate all user interface elements from the program source code. Put them in resource files, message files, or a private database.

2.       Use the same resource identifiers throughout the life of the project. Changing identifiers makes it difficult to update localized resources from one build to another.

3.       Make multiple copies of the same string if it is used in multiple contexts. The same string may have different translations in different contexts.

4.       Do not place strings that should not be localized in resources. Leave them as string constants in the source code.

5.       Allocate text buffers dynamically, since text size may expand when translated. If you must use static buffers, make them extra large to accommodate localized strings (e.g., double the English string length).

6.       Keep in mind that dialog boxes may expand due to localization. Thus, a large dialog box that occupies the entire screen in low-resolution mode may have to be resized to an unusable size when localized.

7.       Avoid text in bitmaps and icons, as these are difficult to localize.

8.       Do not create a text message dynamically at runtime, either by concatenating multiple strings or by removing characters from static text. Word order varies by language, so dynamic composition of text in this manner requires code changes to localize to some languages.

9.       Similarly, avoid composing text using multiple insertion parameters in a format string (e.g., in sprintf or wsprintf), because the order of insertion of the arguments changes when translated to some languages.

10.   If localizing to a Middle Eastern language such as Arabic or Hebrew, use the right-to-left layout APIs to layout your application right to left. For details, see the article in the April 1999 issue of the Microsoft Systems Journal at http://www.microsoft.com/globaldev/articles/singleunicode.asp.

11.   Test localized applications on all language variants of Windows 2000. If your application uses Unicode, as recommended, it should run with no modifications. If it uses a Windows codepage you will need to set the system locale to the appropriate value for your localized application, and reboot, before testing.

 


A-7   Additional Accessibility Considerations

Accessibility means accommodating the widest possible range of user needs and preferences, especially those that might prevent use by individuals with temporary or permanent impairments, seniors, and those working in unusual circumstances. You accomplish this goal by providing a flexible user interface and maintaining compatibility with external software utilities that provide additional functionality.

In particular, applications should do the following:

1.       Allow other software to identify and manipulate all screen elements that the user interacts with. This should be accomplished by supporting Microsoft Active Accessibility. Standard controls provided by USER32.DLL and COMCTL32.DLL automatically support all of the required settings. Applications only need to add additional support when creating custom controls or when drawing content in their window client area. It is strongly recommended that vendors begin planning this support as soon as possible, and implement it in stages. You should test your application for proper behavior using the Narrator utility included with Windows 2000 and with the testing tools included in the Microsoft Active Accessibility SDK.

2.       Allow the user to customize all user interface timings that are not based on standard system settings.

3.       Be compatible with changes to the system font size and with changes to the number of pixels per logical inch.

4.       Avoid triggering unexpected side effects based on changes in pointer or keyboard focus locations.

5.       Avoid conveying important information by color alone. If color alone is the default method for conveying the information, the application should provide an option to convey this information by other means.

For additional information, guidelines, and tools, see http://microsoft.com/enable/.


A-8   Use 64-bit compatible data types

It is possible for developers to use a single source-code base for their Win32- and Win64™-based applications. Microsoft has added this support by introducing new data types in the Platform SDK for Windows 2000.

There are three classes of new data types: fixed-precision data types, pointer-precision types, and specific-precision pointers. These types were added to the Windows environment (specifically, to Basetsd.h) to allow developers to prepare for 64-bit Windows well before its introduction. These new types were derived from the basic C-language integer and long types, so they work in existing code. Therefore, use these data types in your code now, test your code as a Win32-based application, and recompile as a Win64-based application when 64-bit Windows is available

Fixed-precision

Fixed-precision data types are the same length in both Win32 and Win64 programming. To help you remember this, their precision is part of the name of the data type. The following are the fixed-precision data types.

Type

Definition

DWORD32

32-bit unsigned integer

DWORD64

64-bit unsigned integer

INT32

32-bit signed integer

INT64

64-bit signed integer

LONG32

32-bit signed integer

LONG64

64-bit signed integer

UINT32

Unsigned INT32

UINT64

Unsigned INT64

ULONG32

Unsigned LONG32

ULONG64

Unsigned LONG64

 

Pointer Precision

As the pointer precision changes (that is, as it becomes 32 bits with Win32 code and 64 bits with Win64 code), these data types reflect the precision accordingly. Therefore, it is safe to cast a pointer to one of these types when performing pointer arithmetic; if the pointer precision is 64 bits, the type is 64 bits. The count types also reflect the maximum size to which a pointer can refer. The following are the pointer-precision and count types.

Type

Definition

DWORD_PTR

Unsigned long type for pointer precision.

HALF_PTR

Half the size of a pointer. Use within a structure that contains a pointer and two small fields.

INT_PTR

Signed integral type for pointer precision.

LONG_PTR

Signed long type for pointer precision.

SIZE_T

The maximum number of bytes to which a pointer can refer. Use for a count that must span the full range of a pointer.

SSIZE_T

Signed SIZE_T.

UHALF_PTR

Unsigned HALF_PTR.

UINT_PTR

Unsigned INT_PTR.

ULONG_PTR

Unsigned LONG_PTR.

 

Specific Pointer-Precision Types

There are also new pointer types that explicitly size the pointer. Be cautious when using pointers in 64-bit code: If you declare the pointer using a 32-bit type, the system creates the pointer by truncating a 64-bit pointer. (All pointers are 64 bits on a 64-bit platform.)

Type

Definition

POINTER_32

A 32-bit pointer. On a 32-bit system, this is a native pointer. On a 64-bit system, this is a truncated 64-bit pointer.

POINTER_64

A 64-bit pointer. On a 64-bit system, this is a native pointer. On a 32-bit system, this is a sign-extended 32-bit pointer.

Note that it is not safe to assume the state of the high pointer bit.

 

For more details, please see the Microsoft Platform SDK or visit: http://msdn.microsoft.com/library/backgrnd/html/midl64b.htm


Appendix B

Product Distribution Issues

Suites:

In order for a bundled package of applications (e.g. a “suite”) to qualify for certification, each individual product in that suite must be tested to comply with the Application Specification. (Note that value-add extras may be exempted, see below.)  Individual products within the suite that are marketed separately may also be eligible to carry the logo.

For individual standalone products as well as suites that include those products to qualify to carry the logo:

·         Each individual product that is intended to be marketed separately must pass certification testing. You should submit the standalone version of each product for compliance testing. VeriTest will test these products for full logo compliance.

·         The “suite integration” version must also be submitted for testing and will be tested as follows:

·         This version will be tested only for install, uninstall, file type associations, and advertising, provided that all individual components of the suite have been tested individually.

·         If there are additional products that have not been tested as standalone versions, they will be tested in this version.

·         If you have multiple editions of suites, you need only test the all inclusive version. Provided all other suite versions are subsets of the version you have tested, each of these other suites may carry the logo, once the all inclusive suite is tested. Important: You must list the name of each edition of the suite and list the components on the Logo License Agreement.

Note: The final determination of whether or not a product is a suite will be made by VeriTest.

 

Inclusion of non-compliant extras:

All components inside a package that bears the Certified for Windows logo must be compliant with the Application Specification for Windows 2000, with the following minor exceptions:

·         Non-compliant value-add extras, such as samples, trial versions of additional applications and other promotional items may be included in the package.

·         Minor non-compliant auxiliary applications may be included, provided that your core application does NOT depend on them for its functionality.

These exceptions may be granted provided that:

·         The non-compliant components are not advertised on product packaging or other marketing collateral, unless they are called out specifically as being non-logo compliant.

·         The non-compliant products are documented in the release notes (e.g. “readme” document) as being non-compliant.  If your application has no release notes, then you must document this prominently in your product documentation.

·         These non-compliant components must be documented in the Vendor Questionnaire that you submit to VeriTest.

·         One of the following conditions must be true:

·         The user is notified during install if any non-compliant components are being installed.

·         The non-compliant products are on a separate CD from the core product and require completely separate installation mechanism. (E.g. they are not accessible from the main install screen or any subsequent screens stemming from it. The user must launch a separate install process for these non-complaint applications.)

·         The non-compliant components are on the same CD as the core product, but require a completely separate installation mechanism.

 


Appendix C

Development Tools

Development tools are products such as languages and compilers that create executable files or interpreted code modules that mimic the action of executable files when used with a run-time engine of the developing application.

Development tools must meet all of the requirements defined in this Desktop Specification, with the following modifications:

·         Development tools are exempt from the OnNow requirements (defined in Chapter 6).

·         Development tools are exempt from adhering to this system level group policy setting, as this policy would inhibit the ability of the developer to run the applications s/he creates.

 

Policy Setting

Run only allowed Windows Applications

Description

When this policy is enabled, users can only run applications that are listed under the following key: Software\Microsoft\Windows\CurrentVersion\Policies\Explorer\RestrictRun

Application

Action

Your application must not start any application that is not on this list. If you use ShellExecuteEx, Windows 2000 will handle this for you automatically.

Registry Information

Key: HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer

Value Name: RestrictRun

 

 

 

Best Practice for Development Tools:

A development tool targeting Windows should be capable of creating applications that pass certification. However, this is not a formal requirement, primarily because it is not clear how to apply this guideline in such a way that it can be tested in a fair and consistent manner across all development tools.

The following guidelines are recommended:

·         Any installers or install wizards provided to aid in redistribution should be based on Microsoft Installer technologies.

·         Any app wizards should create components that follow the desktop spec for UI

·         Any run-times should be compliant, for example they should be capable of installation and use side-by-side, handle long file names, etc.

 

 

 


Appendix D

International and Localized Versions

Unicode Apps that target Windows 2000 only

Applications that run only on Windows 2000 and above (and do not run on Windows 9x or NT4) and that register as Unicode applications do not need to retest localized versions of that application. The application must be submitted in the primary language version in which it is to be marketed-that is, where the most units are expected to be sold. VeriTest will test the application using the matching localized versions of Windows. If the application passes logo compliance testing in the primary language version, the logo can be used for all localized versions of that application.

 

ANSI Based Apps

Because of the differences among ANSI applications of different languages, the Logo can only be used for localized versions of a product that are in the same language category as the product that is tested.

For each language category, you must submit the version of your application that is localized for your primary target market within that language category. To license the Logo for any version of the application in another language category, you must submit one version of the application localized to a language in the intended category, plus a retest fee. Once this version of the application passes compliance testing, the application is licensed to use the logo for all localized versions of your application within that language category.

For example, if an application is submitted in English and passes in English, the Logo may be used on the packaging and advertising for the English version and also any language listed in the Single-Byte category. However, the Logo may not be used on the Japanese version unless the application is also submitted and passes in Japanese or another Double Byte language.

 

The following list shows the language categories:

Single Byte Language Category

English, German, French, Spanish, Swedish, Danish, Finnish, Norwegian, Italian, Dutch, Portuguese, Russian, Czech, Slovenian, Greek, Hungarian, Polish, Turkish, Slovak

Double Byte Language Category

Japanese, Korean, Traditional Chinese, Simplified Chinese

Complex Script Language Category

Arabic, Hebrew, Thai

 

Note: If you localize to a language not listed here, please send e-mail to winlogo@microsoft.com.


Appendix E

Revisions History

Summary of changes from version 1.0 to version 1.0a

·         Updated intro Welcome section

·         Added exemption to win.ini requirement for applications that must support 16-bit code.

·         Clarified long file names requirement. Exemptions may be allowed for certain characters in some cases. Long file names must support lengths to MAX_PATH. Added language regarding double byte language versions.

·         Updated long printer names requirement: Windows 2000 and Windows NT support long printer names up to 220 characters. Added language regarding double byte language versions.

·         Updated pre-test steps for using Driver Verifier to reflect changes in UI between Beta 3 and final code.

·         Renamed “Install/Uninstall” chapter to “Windows Installer Service”

·         Clarified that advertising requirement is only for app-level on-demand install. On demand install at feature level is not required. Also updated which datafields are required for advertising: Only shortcut, extensions, icon, and verb.

·         Clarified the “Classify and store application data correctly” requirement: Applications must not store more than 128K across HKCU and HKLM at install time. HKCR is excluded.

·         Compliance with this system metric is no longer required: SPI_GETCARETWIDTH

·         Clarified the multiple monitor requirement for images that span monitors.

·         Updated the requirement: “Adhere to system-level Group Policy settings” as follows:

·         Updated the registry information for the following policy: “Do not keep history of recently open documents.” The correct value is NoRecentDocsHistory.

·         Updated the policy name: “Remove Common Dialog MRU dropdown” is now “Hide the dropdown list of recent files”

·         For the policy “Run Only Allowed Windows applications,” removed the following clause Note this does not apply when launching applications via OLE/COM/DCOM.

·         Clarified that SHFOLDER.DLL is installed by the MSI redistributable.

·         Updated OnNow requirements:

·         Clarified requirement 6.1, regarding usage of SetThreadExecutationState to indicate busy status. Also corrected language on use of ES_CONTINUOUS flag

·         Handling sleep and wake notifications was expanded to consider connected vs non-connected state.

·         Clarified that apps must allow sleep in the “non-connected” state. This includes when files are being used offline via Client Side Caching.

·         Clarified acceptable behavior for when in the “connected” state.

·         Clarified the language in requirement 6.4: “Handle wake from normal sleep without losing data.”

·         Clarified the requirement to recover from critical sleep.

·         Corrected bug in Terminal Services Best Practice: The correct flag to append to names of objects is \\GLOBAL.

·         Added Appendix B “Product Distribution Issues”

·         Added Appendix C “Development Tools”

·         Added Appendix D “International and Localized Versions”

·         Updated references and URLs throughout the Specification.


 

Glossary

Active Accessibility A COM-based mechanism that allows applications to actively cooperate with software tools running in the system, such as automation tools, testing tools, and accessibility aids used by people with disabilities.

Active Directory  Provides the ability to build applications that give a single point of access to multiple directories in a network environment, whether those directories are LDAP, NDS, or NTDS based directories.

ADM file Administrative template file that specifies registry settings that can be modified through the Group Policy snap-in user interface. ADM files are extensible to allow ISVs and administrators to create custom Group Policy.

Advertisement  When the files for an application are shown as being available, but are not actually installed.

CSIDL These values provide a unique system-independent way to identify special folders. Used in conjunction with SHGetFolderPath and other APIs.

Componentization  Process by which resources are grouped into Windows Installer Components.

Core Files  Also called core components. Core files are operating system DLLs and EXEs that developers depend on for the proper functionality of their applications. These files should not be uninstalled, as doing so could break other applications.

The core component list exists for historical reasons and is maintained to ensure compatibility with legacy applications. Microsoft will add no new files to this list.  On Windows 2000 and later, applications should rely on Windows File Protection.

For the list of core files, see http://www.veritest.com/ftp/core.htm.

Degrade gracefully  Does not crash the operating system (GPF or blue screen) or application. A dialog box or other visual and audio cue appears informing the user, for example, that the functionality is not available on X version of Y operating system. User is not required to close the application, and can continue to use the other functionality.

Down-level operating system Any combination of these three operating systems: Windows 95, Windows 98, or Windows NT Workstation 4.0.

Extension server  Executable that is associated with a file extension.

Group Policy  Used to specify settings for groups of users and computers, including software policies, scripts, user documents and settings, application deployment, and security settings.

High Contrast support  An option set by the user indicating that they require a high degree of contrast to improve screen legibility. Some application features may be exempted, such as when the use of color is intrinsic and indispensable to the goal of the feature.

HKCU short for HKEY_CURRENT_USER

HKLM short for HKEY_LOCAL_MACHINE

IntelliMirror  A set of management technologies that mirror systems, data, and applications on a server. Part of the Zero Administration initiative for Windows (ZAW).

long file name (LFN)  Any filename that exceeds 8.3 characters in length or contains any lowercase character or any character that is not valid in the 8.3 namespace.

Resources  In Windows Installer service, files (as defined by the filename and install location), registry keys, shortcuts, and anything else that needs to be installed/uninstalled to the computer.

Secure Windows Environment A configuration that prevents unprivileged Users from intentionally or accidentally compromising the operating system. Thisis defined as the environment exposed to a normal (non-admin\non-power) User by default on a clean-installed NTFS system.  In this environment, Users can only write to three* specific locations:

1.   Their own portion of the registry

      (HKEY_CURRENT_USER)**

2.   Their own user profile directory (CSIDL_PROFILE)

3.   A Shared Documents location

      (CSIDL_COMMON_DOCUMENTS)***

Users have Read-Only access to the rest of the system.

*Applications are free to modify the default security for an application-specific subdirectory of CSIDL_COMMON_APPDATA provided the modification is documented in the vendor questionnaire.  This may provide a fourth location for Users to write to for a given application.

**Users can not write to the following sections of HKCU:

\Software\Policies

\Software\Microsoft\Windows\CurrentVersion\Policies

***By default, Users cannot write to other Users shared documents, they can only read other Users shared documents.  Applications are free to modify this default security on an application-specific subdirectory of CSIDL_COMMON_DOCUMENTS provided the modification is documented in the vendor questionnaire.

Side-by-side sharing A new form of sharing in Windows 2000 and Windows 98 Second Edition that enables multiple versions of the same DLL to run at the same time.

System caret Normally the flashing vertical bar that indicates the insertion point in text, it can actually have a range of appearances and is used to indicate keyboard focus location to other software utilities.

universal naming convention (UNC)  The system for indicating names of servers and computers, such as \\Servername\Sharename.

user profile  A computer-based record maintained about an authorized user of a multi-user computer system. A user profile is needed for security and other reasons; it can contain such information as the user’s access restrictions, mailbox location, type of terminal, and so on.

Windows Installer service  Provides end users with a way to install and remove applications, or components of software as needed. System administrators can more easily manage applications and support roaming users.

 



[1] Note that the OS will wait indefinitely, provided the app has pulled the message from the message queue.