Registering the Application Handling the Custom Protocol

Registering an Application to a URL Protocol

The About Asynchronous Pluggable Protocols article describes how to develop handlers for new protocols. In some cases, it may be desirable to invoke another application to handle a custom protocol. To do so, register the existing application as a URL Protocol handler. Once the application has successfully launched, it can use command-line parameters to retrieve the URL that launched it.

• Registering the Application Handling the Custom Protocol
• Launching the Handling Application
• Example
• Related Topics

Registering the Application Handling the Custom Protocol

To enable an application to handle a particular URL protocol, you must add a new key, along with the appropriate keys and values, to HKEY_CLASSES_ROOT.

The new registry key must match the protocol scheme that is being added. For instance, to add an "alert:" protocol, the key added to HKEY_CLASSES_ROOT should be alert. Under this new key, the Default string value should be the display name of the new protocol, and the URL Protocol string value should contain either protocol-specific information or an empty string. Keys should also be added for DefaultIcon and shell.

The Default string value of the DefaultIcon key must be the file name to use as an icon for this new URL protocol.

Under the shell key, a key using a verb (such as open) should be added. A command key and a DDEEXEC key may also be added under the key using a verb. The values under the command and DDEEXEC keys are used to invoke (or launch) the application handling the new protocol.

Launching the Handling Application

When a user clicks a link registered to your custom URL protocol, Windows Internet Explorer launches the registered URL protocol handler. If the specified shellopen command specified in the Registry contains a %1 parameter, Internet Explorer passes the URI to the registered protocol handler. The final Uniform Resource Identifier (URI) is decoded; that is, hexadecimal escape characters are converted to equivalent UTF-16 characters. For example, the %20 character sequence is replaced with a space.

Security Alert  Applications handling URL protocols must be robust in the face of malicious data. Because handler applications receive data from untrusted sources, the URL and other parameter values passed to the application may contain malicious data attempting to exploit the handling application. For this reason, handling applications that could initiate unwanted actions based on external data must first confirm those actions with the user.

Note  In addition, handling applications should robustly handle URLs that are overly long or contain unexpected (or undesirable) character sequences. For more information, please see Writing Secure Code.

Example

The following example shows how to register an application, alert.exe in this case, to handle an alert protocol.

• HKEY_CLASSES_ROOT
  • alert
    (Default) = "URL:Alert Protocol"
    URL Protocol = ""
    • DefaultIcon
      (Default) = "alert.exe"
    • shell
      • open
        • command
          (Default) = "C:\Program Files\Alert\alert.exe" "%1"

By adding these settings to the registry, attempts to navigate to URLs such as "alert:Hello%20World" would attempt to launch alert.exe and pass Hello World in the command-line.

The following sample code contains a simple C# console application demonstrating one way to implement a protocol handler for the alert protocol

Copy Code

using System;
using System.Collections.Generic;
using System.Text;
namespace Alert1
{
class Program
{
static string ProcessInput(string s)
{
// TODO Verify and validate the input
// string as appropriate for your application.
// return s;
}
static void Main(string[] args)
{
Console.WriteLine("Alert.exe invoked with the following parameters.\r\n");
Console.WriteLine("Raw command-line: \n\t" + Environment.CommandLine);
Console.WriteLine("\n\nArguments:\n");
foreach (string s in args)
{
Console.WriteLine("\t" + ProcessInput(s));
}
Console.WriteLine("\nPress any key to continue...");
Console.ReadKey();
}
}
}

Related Topics

• About Asynchronous Pluggable Protocols
• Debugging Tips