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 participant 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 shoshould beAlert. Under this new key, the default string value shocould be the display name of the new protocol, and the URL protocol string value shoshould contain either protocol-specific information or 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.

UnderShellKey, a key using a verb (suchOpen) Shocould be added.CommandKey andDdeexecKey may also be added under the key using a verb. The values underCommandAndDdeexecKeys 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 specifiedShellOpenCommand specified in the registry contains% 1Parameter, 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,% 20Character 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 cocould initiate unwanted actions based on external data must first confirm those actions with the user. Note In addition, handling applications shoshould 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 handleAlertProtocol.

• 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 % 20 World" wocould attempt to launch alert.exe and passHello WorldIn the command-line.

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

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