Registering an application to a URL protocol

Registering an application to a URL protocol . NET Framework 3.0

The about asynchronous pluggable protocols article describes how to develop handlers for URL 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. these settings apply to protocol handlers launched from within Windows Internet Explorer and from Windows Explorer usingRun...Command (Windows logo key + r ).

Security alertApplications that handle URL protocols must consider how to respond to malicious data. because handler applications can receive data from untrusted sources, the URL and other parameter values passed to the application may contain malicous data that attempts to exploit the handling application.

This topic contains the following sections:

• Registering the application handling the custom protocol
• Launching the Handler
• Security issues
• Example protocol handler
• Related Topics

Registering the application handling the custom protocol

To register an application to handle a participant URL protocol, add a new key, along with the appropriate subkeys and values, to hkey_classes_root. the Root Key must match the Protocol scheme that is being added. for instance, to add an "alert:" protocol, addAlertKey to hkey_classes_root, as follows:

 

Hkey_classes_root
Alert
URL protocol =""

Under this new key,URL protocolString value indicates that this key declares a custom protocol handler. Without this key, the handler application will not launch. The value shocould be an empty string.

Keys shoshould also be addedDefaulticonAndShell. The default string value ofDefaulticonKey must be the file name to use as an icon for this new URL protocol. the string takes the form "path, iconindex" with a maximum length of max_path. the name of the first key underShellKey shocould be an action verb, suchOpen. Under this key,CommandKey orDdeexecKey indicate how the handler shocould be invoked. The values underCommandAndDdeexecKeys describe how to launch the application handling the new protocol.

Finally,DefaultString Value shoshould contain the display name of the new Protocol. The following example shows how to register an application, alert.exe in this case, to handleAlertProtocol.

 

Hkey_classes_root
Alert
(Default) = "url: alert protocol"
URL protocol =""
Defaulticon
(Default) = "alert.exe, 1"
Shell
Open
Command
(Default) = "C:/program files/alert/alert.exe" "% 1"

When a user clicks a link registered to your custom URL protocol, Internet Explorer launches the registered URL protocol handler. If the specifiedOpenCommand specified in the registry contains% 1Parameter, Internet Explorer passes the URL to the registered protocol handler application.

Launching the Handler

By adding the above settings to the Registry, navigating to URLs suchalert:Hello%20WorldWocould cause an attempt to launch alert.exe with the complete URL on the command line. Internet Explorer decodes the URL, but the windowsRun...Command does not. If a URL contains spaces, it may be split into Ss more than one argument on the command line.

For example, if the link above is followed through Internet Explorer, the command line wocould be:

Copy

"C:/Program Files/Alert/alert.exe" "alert:Hello World"

If this link is followed through Windows Explorer, the windowsRunCommand, or some other application, the command line wocould be:

Copy

"C:/Program Files/Alert/alert.exe" "alert:Hello%20World"

Because Internet Explorer will decode all percent-encoded octets in the URL before passing the URL to ShellExecute, URLs suchalert:%3F?Will be given to the alert application protocol handleralert:??. The handler won't know that the first question mark was percent-encoded. to avoid this issue, application protocol handlers and their associated URL scheme must not rely on encoding. if encoding is necessary, protocol handlers shoshould use another type of encoding that is compatible with URL syntax, such as base64 encoding. double percent-encoding is not a perfect solution either; if the application protocol URL isn' t processed by Internet Explorer, it will not be decoded.

WhenShellExecuteExecutes the application protocol handler with the URL on the command line, any non-encoded spaces, quotes, and slashes in the URL will be interpreted as part of the command line. this means that if you use C/C ++'s argc and argv to determine the arguments passed to your application, the URL may be broken when SS multiple parameters. to mitigate this issue:

• Avoid spaces, quotes, or backslashes in your url
• Quote the % 1 in the registration ("% 1" as written in the 'alert 'example registration)

However, avoidance doesn't completely solve the problem of quotes in the URL or a backslash at the end of the URL.

Security issues

As noted above, the URL that is passed to an application protocol handler might be broken into SS multiple parameters. malicious parties cocould use additional quote or backslash characters to pass additional command line parameters. for this reason, application protocol handlers shocould assume that any parameters on the command line cocould come from malicious parties, and carefully validate them. applications that cocould initiate dangerous actions based on external data must first confirm those actions with the user. in addition, handling applications shoshould be tested with URLs that are overly long or contain unexpected (or undesirable) character sequences.

For more information, please see writing secure code.

Example protocol handler

The following sample code contains a simple C # console application demonstrating one way to implement a protocol handler forAlertProtocol.

Copy

using System;using System.Collections.Generic;using System.Text;namespace Alert{  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();    }  }}

When invoked with the URLalert:"Hello%20World"(Note extra quotes) from Internet Explorer, the program responds:

Copy

Alert.exe invoked with the following parameters.Raw command-line:        "C:/Program Files/Alert/alert.exe" "alert:"Hello World""Arguments:        alert:Hello        WorldPress any key to continue...

Related Topics

 

• About asynchronous pluggable protocols
• Debugging tips

Community contentAdd FAQ

How to warn a user on a computer on which URL protocol is not registered?

I have registered a URL protocol along with the application installation, and it works flawlessly on both IE and Firefox. the problem is that on a computer on which the application is not installation (neither is the URL protocol registered), and the user clicks the URL link. I wowould like the IE to open a javascript windows, or a Web page, or something else, to give the user a choice to install the application.

Q: How to do that?

A: Sadly, there's no way to do this directly (e.g. no window. navigator. supportsprotocol () method ). you cocould register in the versionvector and use conditional comments in IE to detect the presence of your handler.

History

• 12/3/2010
• Xhpo

• 1/17/2011
• Ericlaw [MSFT]

IE only? Q: Will this work on IE only, or will it be invoked for all apps using HTTP such as Firefox/chrome etc?
A: All major browsers on Windows will pick up application protocols registered in this way. History

• 7/2/2010
• Cubud

• 1/17/2011
• Ericlaw [MSFT]

Path to EXE dynamically? Is there no way to dynamically set the path to the. exe file that the setup project will generate? I can only specify the absolute path there, but what if the user changes that directory during install time? History

• 9/8/2010
• Benjamin eberlei

Automated protocol handlers from Ruby I 've turned that sample app into a simple wrapper for Ruby script, see the details and compiled app here http://github.com/dolzenko/windows_protocol_handlers history

• 6/8/2010
• Evgeniy Dolzhenko

Custom URL works, but how to make it clickable? I wonder, is there a way to have this custom URL highlighted by applications like Outlook Express, outlook, Windows Messenger, and such? I mean, if you receive an email and view it in OE, And the email has a URL, Oe will highlight the URL and make it clickable even though this is plain text. so I wonder, is the list of what it recognizes as URL hardcoded, or it takes it somehow from the system? Same with outlook etc. I created custom URL and it worked OK from Start Menu, but outlook did not highlight it.

============================

Try converting the custom URL with tinyurl.com. It will return an HTTP protocol URL and will forward to your custom URL (making it clickable in outlook, etc ).
-Donavon history

• 12/8/2009
• Vadim Rapp

• 1/7/2010
• I am donavon

Blank ie window again following up on an earlier question: we have Protected Mode disabled for the Local Intranet Zone for IE 7 on Vista. if you click on a mailto: URL on a page on our local Intranet, ie opens up a separate window for the mailto: URL which displays an "Internet Explorer cannot display the web page" error. several seconds later outlook opens up a new email window as expected. is Re any way to prevent this second ie window from opening? The problem seems to be that IE insists on opening the mailto: URL in the Internet zone even though the page hosting it is in the Local Intranet Zone. History

• 9/14/2009
• Clavazzi

URL Decoding is already med by IE, but not by the Windows Shell. so you get different results when putting alert: Hello % 20 World in IE's address bar. in Start> Run. history

• 6/20/2008
• Dee

• 8/28/2009
• Thomas Lee

Internet Explorer 6 return an error

So far this works great on IE7 using the "command" key, however for some reason it does not work in ie6. I'm getting an "invalid cannot ax error" when I click on the link from within the browser. everything works great if I type the URL on the "Start> run... "window. i'm not sure if the "ddeexec" Key is required by IE6 though. if so, please can you provide an example?

History

• 8/14/2008
• Miguelguzman

• 5/19/2009
• Thomas Lee

Tool for regestering URL protocols

I have built a small tool for regestering URL protocols: http://www.codeplex.com/CustomURL

This tool will help you register URL protocols and lauch a specific application when a URL is executed. This tool is free and open source.

History

• 7/8/2008
• Kallelundberg

• 1/18/2009
• Stanley Roark

Blank ie window

This works great tables t that an IE window is left open showing the URI that was invoked. is there any way (e.g. A value in the registry, editflags perhaps) to make this window close or not appear in the first place?

 

=> The problem with the blank ie window may be related to the zone where the page that hosts the link is located. if you test a HTML page form the File System (File ://...) try to host the page in IIS instead (so that it is http ://...) -This worked for me.