Shell and Shlwapi DLL Versions

This section describes how to determine which version of the Shell DLLs your application is running on and how to target your application for a specific version.

DLL Version Numbers

All but a handful of the programming elements discussed in the Shell documentation are contained in two DLLs: Shell32.dll and Shlwapi.dll. Because of ongoing enhancements, different versions of these DLLs implement different features. Throughout the Shell reference documentation, each programming element specifies a minimum supported DLL version number. This version number indicates that the programming element is implemented in that version and subsequent versions of the DLL unless otherwise specified. If no version number is specified, the programming element is implemented in all existing versions of the DLL.

Before WindowsВ XP, new Shell32.dll and Shlwapi.dll versions were sometimes provided with new versions of Windows Internet Explorer. As of WindowsВ XP, those DLLs were no longer provided as redistributable files outside of new versions of Windows itself. The following table outlines the different DLL versions and how they were distributed dating back to Microsoft Internet ExplorerВ 3.0, WindowsВ 95, and Microsoft WindowsВ NTВ 4.0.

Shell32.dll version 4.0 is found in the original versions of WindowsВ 95 and Microsoft WindowsВ NTВ 4.0. The Shell was not updated with the Internet ExplorerВ 3.0 release, so Shell32.dll does not have a version 4.70. Shell32.dll versions 4.71 and 4.72 were shipped with the corresponding Internet Explorer releases, but they were not necessarily installed (see note 1). For releases subsequent to Microsoft Internet ExplorerВ 4.01 and WindowsВ 98, the version numbers for Shell32.dll and Shlwapi.dll diverge. In general, you should assume that the DLLs have different version numbers and test each one separately.

Shell32.dll

Version	Distribution Platform
4.0	WindowsВ 95 and Microsoft WindowsВ NTВ 4.0
4.71	Microsoft Internet ExplorerВ 4.0. See note 1.
4.72	Internet ExplorerВ 4.01 and WindowsВ 98. See note 1.
5.0	WindowsВ 2000 and WindowsВ Millennium Edition (WindowsВ Me). See note 2.
6.0	WindowsВ XP
6.0.1	WindowsВ Vista
6.1	WindowsВ 7

Shlwapi.dll

Version	Distribution Platform
4.0	WindowsВ 95 and Microsoft WindowsВ NTВ 4.0
4.71	Internet ExplorerВ 4.0. See note 1.
4.72	Internet ExplorerВ 4.01 and WindowsВ 98. See note 1.
4.7	Internet Explorer 3.x
5.0	Microsoft Internet ExplorerВ 5 and WindowsВ 98 SE. See note 2.
5.5	Microsoft Internet ExplorerВ 5.5 and WindowsВ Millennium Edition (WindowsВ Me)
6.0	WindowsВ XP and WindowsВ Vista

Note 1: All systems with Internet ExplorerВ 4.0 or 4.01 had the associated version of Shlwapi.dll (4.71 or 4.72, respectively). However, for systems prior to WindowsВ 98, Internet ExplorerВ 4.0 and 4.01 can be installed with or without what was known as the integrated Shell. If Internet Explorer was installed with the integrated Shell, the associated version of Shell32.dll (4.71 or 4.72) was also installed. If Internet Explorer was installed without the integrated Shell, Shell32.dll remained as version 4.0. In other words, the presence of version 4.71 or 4.72 of Shlwapi.dll on a system does not guarantee that Shell32.dll has the same version number. All WindowsВ 98 systems have version 4.72 of Shell32.dll.

Note 2: Version 5.0 of Shlwapi.dll was distributed with Internet ExplorerВ 5 and was found on all systems on which Internet ExplorerВ 5 was installed, with the exception of WindowsВ 2000. Version 5.0 of Shell32.dll was distributed natively with WindowsВ 2000 and WindowsВ Millennium Edition (WindowsВ Me), together with version 5.0 of Shlwapi.dll.

Using DllGetVersion to Determine the Version Number

Starting with version 4.71, the Shell DLLs, among others, began exporting DllGetVersion. This function can be called by an application to determine which DLL version is present on the system.

DLLs do not necessarily export DllGetVersion. Always test for it before attempting to use it.

For Windows versions earlier than WindowsВ 2000, DllGetVersion returns a DLLVERSIONINFO structure that contains the major and minor version numbers, the build number, and a platform ID. For WindowsВ 2000 and later systems, DllGetVersion might instead return a DLLVERSIONINFO2 structure. In addition to the information provided through DLLVERSIONINFO, DLLVERSIONINFO2also provides the hotfix number that identifies the latest installed service pack, which provides a more robust way to compare version numbers. Because the first member of DLLVERSIONINFO2 is a DLLVERSIONINFO structure, the later structure is backward-compatible.

Using DllGetVersion

The following sample function GetVersion loads a specified DLL and attempts to call its DllGetVersion function. If successful, it uses a macro to pack the major and minor version numbers from the DLLVERSIONINFO structure into a DWORD that is returned to the calling application. If the DLL does not export DllGetVersion, the function returns zero. With WindowsВ 2000 and later systems, you can modify the function to handle the possibility that DllGetVersion returns a DLLVERSIONINFO2 structure. If so, use the information in that DLLVERSIONINFO2 structure’s ullVersion member to compare versions, build numbers, and service pack releases. The MAKEDLLVERULL macro simplifies the task of comparing these values to those in ullVersion.

Using LoadLibrary incorrectly can pose security risks. Refer to the LoadLibrary documentation for information on how to correctly load DLLs with different versions of Windows.

The following code example illustrates how you can use GetVersion to test whether Shell32.dll is version 6.0 or later.

Project Versions

To ensure that your application is compatible with different targeted versions of a .dll file, version macros are present in the header files. These macros are used to define, exclude, or redefine certain definitions for different versions of the DLL. See Using the Windows Headers for an in-depth description of these macros.

For example, the macro name _WIN32_IE is commonly found in older headers. You are responsible for defining the macro as a hexadecimal number. This version number defines the target version of the application that is using the DLL. The following table shows the available version numbers and the effect each has on your application.

Version	Description
0x0200	The application is compatible with Shell32.dll version 4.00 and later. The application cannot implement features that were added after version 4.00.
0x0300	The application is compatible with Shell32.dll version 4.70 and later. The application cannot implement features that were added after version 4.70.
0x0400	The application is compatible with Shell32.dll version 4.71 and later. The application cannot implement features that were added after version 4.71.
0x0401	The application is compatible with Shell32.dll version 4.72 and later. The application cannot implement features that were added after version 4.72.
0x0500	The application is compatible with Shell32.dll and Shlwapi.dll version 5.0 and later. The application cannot implement features that were added after version 5.0 of Shell32.dll and Shlwapi.dll.
0x0501	The application is compatible with Shell32.dll and Shlwapi.dll version 5.0 and later. The application cannot implement features that were added after version 5.0 of Shell32.dll and Shlwapi.dll.
0x0600	The application is compatible with Shell32.dll and Shlwapi.dll version 6.0 and later. The application cannot implement features that were added after version 6.0 of Shell32.dll and Shlwapi.dll.

If you do not define the _WIN32_IE macro in your project, it is automatically defined as 0x0500. To define a different value, you can add the following to the compiler directives in your make file; substitute the desired version number for 0x0400.

Another method is to add a line similar to the following in your source code before you include the Shell header files. Substitute the desired version number for 0x0400.

.shell (Command Shell)

The .shell command launches a shell process and redirects its output to the debugger, or to a specified file.

Parameters

InFile
Specifies the path and file name of a file to be used for input. If you intend to offer no input after the initial command, you can specify a single hyphen (-) instead of InFile, with no space before the hyphen.

OutFile
Specifies the path and file name of a file to be used for standard output. If -o **** OutFile is omitted, output is sent to the Debugger Command window. If you do not want this output displayed or saved in a file, you can specify a single hyphen (-) instead of OutFile, with no space before the hyphen.

ErrFile
Specifies the path and file name of a file to be used for error output. If -e ErrFile is omitted, error output is sent to the same place as standard output. If you do not want this output displayed or saved in a file, you can specify a single hyphen (-) instead of ErrFile, with no space before the hyphen.

Options
Can be any number of the following options:

-ci «Commands«
Processes the specified debugger commands, and then passes their output as an input file to the process being launched. Commands can be any number of debugger commands, separated by semicolons, and enclosed in quotation marks.

-x
Causes any process being spawned to be completely detached from the debugger. This allows you to create processes which will continue running even after the debugging session ends.

ShellCommand
Specifies the application command line or Microsoft MS-DOS command to be executed.

Environment

Modes

user mode, kernel mode

Targets

live, crash dump

Platforms

Additional Information

For other ways of accessing the command shell, see Using Shell Commands.

Remarks

The .shell command is not supported when the output of a user-mode debugger is redirected to the kernel debugger. For more information about redirecting output to the kernel debugger (sometimes called NTSD over KD), see Controlling the User-Mode Debugger from the Kernel Debugger.

The entire line after the .shell command will be interpreted as a Windows command (even if it contains a semicolon). This line should not be enclosed in quotation marks. There must be a space between .shell and the ShellCommand (additional leading spaces are ignored).

The output from the command will appear in the Debugger Command window, unless the -o **** OutFile parameter is used.

Issuing a .shell command with no parameters will activate the shell and leave it open. All subsequent commands will be interpreted as Windows commands. During this time, the debugger will display messages reading , and the WinDbg prompt will be replaced with an Input> prompt. Sometimes, a separate Command Prompt window will appear when the debugger leaves the shell open. This window should be ignored; all input and output will be done through the Debugger Command window.

To close this shell and return to the debugger itself, type exit or .shell_quit. (The .shell_quit command is more powerful, because it works even if the shell is frozen.)

This command cannot be used while debugging CSRSS, because new processes cannot be created without CSRSS being active.

You can use the -ci flag to run one or more debugger commands and then pass their output to a shell process. For example, you could pass the output from the !process 0 7 command to a Perl script by using the following command:

Shell object

Represents the objects in the Shell. Methods are provided to control the Shell and to execute commands within the Shell. There are also methods to obtain other Shell-related objects.

Members

The Shell object has these types of members:

Methods

The Shell object has these methods.

Method	Description
AddToRecent	Adds a file to the most recently used (MRU) list.
BrowseForFolder	Creates a dialog box that enables the user to select a folder and then returns the selected folder’s Folder object.
CanStartStopService	Determines if the current user can start and stop the named service.
CascadeWindows	Cascades all of the windows on the desktop. This method has the same effect as right-clicking the taskbar and selecting Cascade Windows.
ControlPanelItem	Runs the specified Control Panel (*.cpl) application. If the application is already open, it will activate the running instance. [!Note] As of WindowsВ Vista, most Control Panel applications are Shell items and cannot be opened with this function. To open those Control Panel applications, pass the canonical name to control.exe. For example:
EjectPC	Ejects the computer from its docking station. This is the same as clicking the Start menu and selecting Eject PC, if your computer supports this command.
Explore	Opens a specified folder in a Windows Explorer window.
ExplorerPolicy	Gets the value for a specified Internet Explorer policy.
FileRun	Displays the Run dialog to the user. This method has the same effect as clicking the Start menu and selecting Run.
FindComputer	Displays the Search Results: Computers dialog box. The dialog box shows the result of the search for a specified computer.
FindFiles	Displays the Find: All Files dialog box. This is the same as clicking the Start menu and then selecting Search (or its equivalent under systems earlier than WindowsВ XP.
FindPrinter	Displays the Find Printer dialog box.
GetSetting	Retrieves a global Shell setting.
GetSystemInformation	Retrieves system information.
Help	Displays the Windows Help and Support Center. This method has the same effect as clicking the Start menu and selecting Help and Support.
IsRestricted	Retrieves a group’s restriction setting from the registry.
IsServiceRunning	Returns a value that indicates whether a particular service is running.
MinimizeAll	Minimizes all of the windows on the desktop. This method has the same effect as right-clicking the taskbar and selecting Minimize All Windows on older systems or clicking the Show Desktop icon in the Quick Launch area of the taskbar in WindowsВ 2000 or WindowsВ XP.
NameSpace	Creates and returns a Folder object for the specified folder.
Open	Opens the specified folder.
RefreshMenu	Refreshes the contents of the Start menu. Used only with systems preceding WindowsВ XP.
SearchCommand	Displays the Apps Search pane.
ServiceStart	Starts a named service.
ServiceStop	Stops a named service.
SetTime	Displays the Date and Time Properties dialog box. This method has the same effect as right-clicking the clock in the taskbar status area and selecting Adjust Date/Time.
ShellExecute	Performs a specified operation on a specified file.
ShowBrowserBar	Displays a browser bar.
ShutdownWindows	Displays the Shut Down Windows dialog box. This is the same as clicking the Start menu and selecting Shut Down.
Suspend
TileHorizontally	Tiles all of the windows on the desktop horizontally. This method has the same effect as right-clicking the taskbar and selecting Tile Windows Horizontally.
TileVertically	Tiles all of the windows on the desktop vertically. This method has the same effect as right-clicking the taskbar and selecting Tile Windows Vertically.
ToggleDesktop	Displays or hides the desktop.
TrayProperties	Displays the Taskbar and Start Menu Properties dialog box. This method has the same effect as right-clicking the taskbar and selecting Properties.
UndoMinimizeALL	Restores all desktop windows to the same state they were in before the last MinimizeAll command. This method has the same effect as right-clicking the taskbar and selecting Undo Minimize All Windows on older systems or a second clicking of the Show Desktop icon in the Quick Launch area of the taskbar in WindowsВ 2000 or WindowsВ XP.
Windows	Creates and returns a ShellWindows object. This object represents a collection of all of the open windows that belong to the Shell.
WindowsSecurity	Displays the Windows Security dialog box.
WindowSwitcher	Displays your open windows in a 3D stack that you can flip through.

Properties

The Shell object has these properties.