#pragma section-numbers on
<<TableOfContents(3)>>

= set_protocol_handler =

Protocol handlers are configured with `set_protocol_handler`.  You can configure a protocol to be handled internally, externally, or to prompt for an external handler.  The call form looks like this:

{{{
set_protocol_handler(protocol, handler);
}}}

== protocol ==

The protocol being configured.  In other words, the scheme portion of the url, with no colon.

== handler ==

 true::
 :: Handle the protocol internally.  That is, have Gecko try to handle it.

 null::
 :: Prompt for a handler when attempting to open a link of this protocol.

 an nsIFile::
 :: Use the executable indicated by the nsIFile as a handler.  You can get an nsIFile from `make_file` or `find_file_in_path`.

 a string::
 :: The string is a template url for a web service for handling this protocol.  The sequence "%s" in the string will be replaced by the url-encoded url of the resource.


= Notes =

This kind of protocol handler only affects what happens when clicking on (or following) a hyperlink.  It has no effect on reloading, or any commands that cause an url to be loaded in a new buffer or window, such as command-line remoting or clicks-in-new-buffer.


= Examples =

== Handle mailto links with a shell script ==

{{{
set_protocol_handler("mailto", make_file("~/bin/handle-mailto"));
}}}

== Handle mailto links with Thunderbird ==

{{{
set_protocol_handler("mailto", find_file_in_path("thunderbird"));
}}}

== Handle mailto links with GMail ==

{{{
set_protocol_handler("mailto", "https://mail.google.com/mail/?extsrc=mailto&url=%s");
}}}

== Handle magnet links with Transmission ==

{{{
set_protocol_handler("magnet", find_file_in_path("transmission-gtk"));
}}}