Microsoft KB Archive/297878

= How to Register an Internet Browser or E-mail Client With the Windows XP Start Menu =

Article ID: 297878

Article Last Modified on 12/1/2007

-

APPLIES TO


 * Microsoft Windows XP Professional x64 Edition
 * Microsoft Windows XP Home Edition
 * Microsoft Windows XP Professional

-



This article was previously published under Q297878





SUMMARY
The information in this article applies to independent software vendors (ISVs) who want to register their applications with the Windows XP Start menu. Windows XP has the ability to register a Start menu Internet application either as the computer default or as a per-user default. Windows XP also offers the ability to register a per-user default e-mail client. This article provides detailed information on this new capability.



MORE INFORMATION
The Windows XP Start menu includes some new registry keys to permit applications to register themselves as Start menu Internet applications. These applications may now register either as the default Internet application for the entire system or as the default for particular users (per-user default). Windows XP also extends the existing definition of mail clients to permit registration on a per-user basis. On previous versions of Windows, the default mail client is a system-wide setting.

By default, Windows XP creates &quot;Internet&quot; and &quot;E-mail&quot; icons on the Start menu. When users click one of these icons, the Start menu first checks for the per-user default Internet or e-mail program in HKEY_CURRENT_USER. If no default is found, then the Start menu looks for a system-wide default in HKEY_LOCAL_MACHINE.

NOTE: The default installation of Windows XP does not register a per-user default Internet or e-mail program, only a system-wide default. This provides a smooth upgrade path from previous versions of the operating system, in which only the HKEY_LOCAL_MACHINE key is supported for client registrations.

Registering for the Start Menu Internet Link
Any application can register to appear as an Internet client on the Start menu.

With Windows XP, Start menu Internet settings are kept in two places in the registry. The key

[HKLM\Software\Clients\StartMenuInternet]

describes the Internet browser applications that are installed on the system. And the key

[HKCU\Software\Clients\StartMenuInternet]

describes the Internet browser that will be started when the user clicks the Internet command on the Start menu.

If the HKCU\Software\Clients\StartMenuInternet key is blank or missing, then the value from HKLM is used to select the Internet browser that will appear on the Start menu.

Beneath the key [HKLM\Software\Clients\StartMenuInternet] there may be zero or more subkeys, one for each registered Internet browser application. For example, a hypothetical system might have this arrangement:

[HKLM\Software\Clients\StartMenuInternet\IEXPLORE.EXE]

[HKLM\Software\Clients\StartMenuInternet\NETSCAPE.EXE]

[HKLM\Software\Clients\StartMenuInternet\OPERA.EXE]

Consider a hypothetical browser called &quot;Lit View&quot; by Litware Inc. Suppose that the executable name for Lit View is LITVIEW.EXE. The registration of Lit View occurs under the following registry key:

[HKLM\Software\Clients\StartMenuInternet\LITVIEW.EXE]

&quot;LocalizedString&quot;=REG_SZ:@C:\Program Files\LitwareInc\ResourceDLL.dll,-123

The LocalizedString value is of type REG_SZ. It provides the path to an .exe or .dll file. Note that the path string begins with an &quot;at&quot; sign (@). The decimal integer is the ID of a string resource, contained within the DLL, whose value is to be displayed to the user. This allows the same registration to be used for multiple languages. Each language would provide a different ResourceDLL.dll. This allows the system to display the correct string depending on the currently selected language.

The following registry key informs the Start menu of the default icon to display when the user selects Lit View as the Start menu Internet browser:

[HKLM\Software\Clients\StartMenuInternet\LITVIEW.EXE\DefaultIcon]

(Default)=REG_SZ:C:\Program Files\LitwareInc\LitView.exe,1

You would use the following registry key to specify a command line to run if the user clicks the Internet menu command on the Start menu, and Lit View is the preferred Start menu Internet browser. The command might open the browser on the users home page, for example. However, it might launch some other introductory user interface that the ISV feels is appropriate. Notice that because there is a space in the path, the entire path string is enclosed in quotes.

[HKLM\Software\Clients\StartMenuInternet\LITVIEW.EXE\shell\open\command]

(Default)=REG_SZ:&quot;C:\Program Files\LitwareInc\LitView.exe&quot; -welcome

When the user specifies that Lit View should be used as the default Web browser, the application should first attempt to set the following registry key:

[HKLM\Software\Clients\StartMenuInternet]

(Default)=REG_SZ:&quot; LITVIEW.EXE&quot;

If this is successful (if the user has write permission to the registry key), then the application should also delete the following registry value:

[HKCU\Software\Clients\StartMenuInternet]

(Default)

If the attempt to set the value in HKLM fails, then the application should set the following registry key:

[HKCU\Software\Clients\StartMenuInternet]

(Default)=REG_SZ:&quot;LITVIEW.EXE&quot;

After updating the registry keys, the application broadcasts the WM_SETTINGCHANGE message with wParam = 0 and lParam pointing to the null-terminated string &quot;Software\Clients\StartMenuInternet&quot; to notify the operating system that the default client has changed.

The added complexity of setting the registry keys for the default Start menu Internet browser is necessary to preserve backward-compatibility with old Web browsers that do not support per-user registrations.

NOTES: Being registered as the default Start menu Internet application is not the same as being registered as the default Web browser. The default Web browser is used for launching arbitrary URLs from anywhere in the system. The Start menu Internet application merely controls the program that is launched when the user clicks the Internet icon on the Start menu.

Registering for the Start Menu E-mail Link
Any application can register to appear as an e-mail client on the Start menu.

E-mail settings are kept in two places. The registry key

[HKLM\Software\Clients\Mail]

describes the e-mail applications that are installed on the system, as well as the default e-mail application.

The key

[HKCU\Software\Clients\Mail]

describes the e-mail client that will be launched when the user clicks the Email icon on the Start menu.

If the HKCU\Software\Clients\Mail key is blank or missing, then the value from HKLM is used to select the e-mail application that will appear on the Start menu.

Underneath [HKLM\Software\Clients\Mail] may be zero or more subkeys, one for each registered email application. For example, a hypothetical system might have:

[HKLM\Software\Clients\Mail\Eudora]

[HKLM\Software\Clients\Mail\Outlook Express]

[HKLM\Software\Clients\Mail\HotMail]

Consider a hypothetical e-mail client called &quot;Lit Mail&quot; by Litware Inc. Litware Inc. decides that it's suitable to register this e-mail client under the internal name &quot;LitMail&quot;. Again, the internal name is some unique string that is never shown to the user.

To install an e-mail client as the default, use this registry key:

[HKLM\Software\Clients\Mail\LitMail]

(Default)=REG_SZ:Lit Mail

&quot;LocalizedString&quot;=REG_SZ:@C:\Program Files\LitwareInc\ResourceDLL.dll,-456

The &quot;LocalizedString&quot; value is a REG_SZ that provides a path to an .exe or .dll file and a decimal integer. The decimal integer is the string resource ID within the DLL whose value is to be displayed to the user. This allows the same registration to be used for multiple languages. Each language would provide a different ResourceDLL.dll, and the dynamic loading of the string from the DLL would result in the correct string being displayed, depending on the language selected. Note that the string begins with an &quot;at&quot; sign (@).

After updating the registry keys, the application broadcasts the WM_SETTINGCHANGE message with wParam = 0 and lParam pointing to the null-terminated string &quot;Software\Clients\Mail&quot; to notify the operating system that the default client has changed.

For backward compatibility with applications that do not support localized strings, the name of the application in the installed language should also be set as the default value for the key.

Use the following registry key to indicate the icon to display if the user selects Lit Mail as the Start menu mail program:

[HKLM\Software\Clients\Mail\LitMail\DefaultIcon]

(Default)=REG_SZ:C:\Program Files\LitwareInc\LitMail.exe,1

Use the following registry key to specify a command line for the e-mail client to use if the user clicks the E-mail menu item and Lit Mail is the preferred Start menu e-mail program. It is also the command line that is run if the user selects Read e-mail from the Microsoft Internet Explorer Tools menu. Notice that because there is a space in the path, the .exe name must be enclosed in quotes.

[HKLM\Software\Clients\Mail\shell\open\command]

(Default)=REG_SZ:&quot;C:\Program Files\LitwareInc\LitMail.exe&quot; -inbox

If (and only if) the user specifies Lit Mail to be the default Start menu e-mail application, the Lit Mail application may write its internal name to the following key:

[HKCU\Software\Clients\Mail] (Default)=REG_SZ:LitMail

If (and only if) the user specifies Lit Mail to be the system-wide default e-mail application, the Lit Mail application may write its internal name to the key specified below. Note that access to this key may be restricted. Applications should not assume that all users have permission to change the system-wide default e-mail application.

[HKLM\Software\Clients\Mail]

(Default)=REG_SZ:LitMail

NOTES:

Registration as the default Start menu e-mail application is different from registration as the system default e-mail client or the registered mailto handler. The system default e-mail client is started when the user clicks Read e-mail from the Internet Explorer Tools menu. The registered mailto handler is launched when the user clicks an URL of the form mailto:someone@microsoft.com. The Start menu e-mail application is used when the user clicks the E-mail icon on the Start menu.

If there is no default Start menu e-mail application specified, then the E-mail icon on the Start menu will start the system default e-mail client.

This article does not cover registering as the default mailto protocol handler. Applications that want to register in such manner should continue to follow existing specifications on this subject. This section mainly repeats information provided elsewhere. The only addition to the existing behavior is the definition of the [HKCU\Software\Clients\Mail] registry key.

Customizing the Context Menu
To customize the Properties options displayed when the user right-clicks the E-mail (or Internet) icon, your hypothetical application can add the following data to the registry:

[HKEY_LOCAL_MACHINE\Software\Clients\Mail\LitMail\shell\properties]

MUIVerb=REG_SZ:@C:\Program Files\LitwareInc\ResourceDLL.dll,-789

[HKEY_LOCAL_MACHINE\Software\Clients\Mail\LitMail\shell\properties\command]

(Default)=REG_SZ:&quot;C:\Program Files\LitwareInc\LitMail.exe&quot; -properties

It's worth mentioning again that the MUIVerb data item is constructed starting with an at-sign(@), followed by the full path to the resource DLL, a comma, a minus sign, then the decimal string resource identifier to display. Note as well that the path to the LitMail.exe program contains spaces, so the path string is placed inside quotes.

This change enables a right-click on E-mail to open the Properties sheet for, say, Lit Mail, rather than the default, which is Windows Internet Properties.

An application can add additional commands to the context menu. For example, your hypothetical application might add a &quot;find&quot; command:

[HKEY_LOCAL_MACHINE\Software\Clients\Mail\LitMail\shell\find]

MUIVerb=REG_SZ:@C:\Program File\LitwareInc\ResourceDLL.dll,-790

[HKEY_LOCAL_MACHINE\Software\Clients\Mail\LitMail\shell\properties\command]

(Default)=REG_SZ:&quot;C:\Program Files\LitwareInc\LitMail.exe&quot; -contacts

The key name underneath &quot;shell&quot; is an arbitrary, nonlocalized name. This example uses &quot;find&quot;. As before, the MUIVerb data item contains an at-sign (@) as the first element, followed by the path to a resource DLL, a comma separator, then a minus sign preceding the decimal string resource identifier to display. In this case, that string might be &quot;Open Address Book&quot;. Finally, note that the command line string contains spaces, so it is enclosed in quotes.

The third-party products that are discussed in this article are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, regarding the performance or reliability of these products.

Keywords: kbproductlink kbhowto KB297878

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.