uriloader/exthandler/nsIExternalProtocolService.idlScriptable
The external protocol service is used for finding and launching web handlers (a la registerProtocolHandler in the HTML5 draft) or platform-specific applications for handling particular protocols.
Inherits from: nsISupports Last changed in Gecko 1.9 (Firefox 3)

You can ask the external protocol service if it has an external handler for a given protocol scheme. And you can ask it to load the url using the default handler.

Method overview

boolean externalProtocolHandlerExists(in string aProtocolScheme);
AString getApplicationDescription(in AUTF8String aScheme);
nsIHandlerInfo getProtocolHandlerInfo(in ACString aProtocolScheme);
nsIHandlerInfo getProtocolHandlerInfoFromOS(in ACString aProtocolScheme, out boolean aFound);
boolean isExposedProtocol(in string aProtocolScheme);
void loadURI(in nsIURI aURI, [optional] in nsIInterfaceRequestor aWindowContext);
void loadUrl(in nsIURI aURL);
void setProtocolHandlerDefaults(in nsIHandlerInfo aHandlerInfo, in boolean aOSHandlerExists);

Methods

externalProtocolHandlerExists()

Check whether a handler for a specific protocol exists. Specifically, this looks to see whether there are any known possible application handlers in either the nsIHandlerService datastore or registered with the OS.

boolean externalProtocolHandlerExists(
  in string aProtocolScheme
);
Parameters
aProtocolScheme
The scheme from a url: http, ftp, mailto, and so on.
Note: aProtocolScheme should not include a trailing colon, which is part of the URI syntax, not part of the scheme itself. That is, pass "mailto" not "mailto:".
Return value

true if we have a handler and false otherwise.

getApplicationDescription()

Gets a human-readable description for the application responsible for handling a specific protocol.

AString getApplicationDescription(
  in AUTF8String aScheme
);
Parameters
aScheme
The scheme to look up. For example, "mms".
Return value

This code makes little sense and needs to be cleaned up. -Nickolay <pre> // first construct an nsIURI object using the ioservice var ioservice = Components.classes["@mozilla.org/network/io-service;1"].getService(Components.interfaces.nsIIOService); var uriToOpen = ioservice.newURI("http://www.example.com/", null, null); var extps = Components.classes["@mozilla.org/uriloader/external-protocol-service;1"] .getService(Components.interfaces.nsIExternalProtocolService); if (extps.externalProtocolHandlerExists("tlcxp")) { // Handler for http:// URLs exists } else { // suppress external-load warning for standard browser schemes pref("network.protocol-handler.external.tlcxp", True); pref("network.protocol-handler.app.tlcxp, "LZX"); } </pre>

getProtocolHandlerInfo()

Retrieve the handler for the given protocol. If neither the application nor the OS knows about a handler for the protocol, the object this method returns will represent a default handler for unknown content.

Note: AProtocolScheme should not include a trailing colon, which is part of the URI syntax, not part of the scheme itself (That is pass "mailto" not "mailto:").

nsIHandlerInfo getProtocolHandlerInfo(
  in ACString aProtocolScheme
);
Parameters
aProtocolScheme
The scheme from a URL: http, ftp, mailto, and so on.
Return value

The handler, if any; otherwise a default handler.

getProtocolHandlerInfoFromOS()

Given a scheme, looks up the protocol info from the OS. This should be overridden by each OS's implementation.

nsIHandlerInfo getProtocolHandlerInfoFromOS(
  in ACString aProtocolScheme,
  out boolean aFound
);
Parameters
aProtocolScheme
The scheme from a url: http, ftp, mailto, and so on.
aFound
Was an OS default handler for this scheme found?
Return value

An nsIHanderInfo for the protocol.

isExposedProtocol()

Check whether a handler for a specific protocol is "exposed" as a visible feature of the current application. An exposed protocol handler is one that can be used in all contexts. A non-exposed protocol handler is one that can only be used internally by the application. For example, a non-exposed protocol would not be loaded by the application in response to a link click or a X-remote openURL command. Instead, it would be deferred to the system's external protocol handler.

boolean isExposedProtocol(
  in string aProtocolScheme
);
Parameters
aProtocolScheme
The scheme from a url: http, ftp, mailto, and so on.
Return value

true if the protocol is exposed, false otherwise.

loadURI()

Used to load a URI via an external application. Might prompt the user for permission to load the external application.

void loadURI(
  in nsIURI aURI,
  [optional] in nsIInterfaceRequestor aWindowContext
);
Parameters
aURI
The URI to load.
aWindowContext
The window to parent the dialog against, and, if a web handler is chosen, it is loaded in this window as well. This parameter may be ultimately passed nsIURILoader.openURI() in the case of a web handler, and aWindowContext is null or not present, web handlers will fail.

loadUrl()

Used to load a url via an external protocol handler (if one exists).

void loadUrl(
  in nsIURI aURL
);
Parameters
aURL
The url to load.

setProtocolHandlerDefaults()

Set some sane defaults for a protocol handler object.

void setProtocolHandlerDefaults(
  in nsIHandlerInfo aHandlerInfo,
  in boolean aOSHandlerExists
);
Parameters
aHandlerInfo
An nsIHandlerInfo object, as returned by getProtocolHandlerInfoFromOS().
aOSHandlerExists
Was the object above created for an extant OS default handler? This is generally the value of the aFound out param from getProtocolHandlerInfoFromOS().

See also