Public Member Functions

nsIExternalProtocolService Interface Reference

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. More...

import "nsIExternalProtocolService.idl";

List of all members.

Public Member Functions

boolean externalProtocolHandlerExists (in string aProtocolScheme)
 Check whether a handler for a specific protocol exists.
boolean isExposedProtocol (in string aProtocolScheme)
 Check whether a handler for a specific protocol is "exposed" as a visible feature of the current application.
nsIHandlerInfo getProtocolHandlerInfo (in ACString aProtocolScheme)
 Retrieve the handler for the given protocol.
nsIHandlerInfo getProtocolHandlerInfoFromOS (in ACString aProtocolScheme, out boolean aFound)
 Given a scheme, looks up the protocol info from the OS.
void setProtocolHandlerDefaults (in nsIHandlerInfo aHandlerInfo, in boolean aOSHandlerExists)
 Set some sane defaults for a protocol handler object.
void loadUrl (in nsIURI aURL)
 Used to load a url via an external protocol handler (if one exists).
void loadURI (in nsIURI aURI,[optional] in nsIInterfaceRequestor aWindowContext)
 Used to load a URI via an external application.
AString getApplicationDescription (in AUTF8String aScheme)
 Gets a human-readable description for the application responsible for handling a specific protocol.

Detailed Description

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.

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.


Member Function Documentation

boolean nsIExternalProtocolService::externalProtocolHandlerExists ( in string  aProtocolScheme  ) 

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.

Parameters:
aProtocolScheme The scheme from a url: http, ftp, mailto, etc.
Returns:
true if we have a handler and false otherwise.

XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme?

AString nsIExternalProtocolService::getApplicationDescription ( in AUTF8String  aScheme  ) 

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

Parameters:
aScheme The scheme to look up. For example, "mms".
Exceptions:
NS_ERROR_NOT_IMPLEMENTED If getting descriptions for protocol helpers is not supported
NS_ERROR_NOT_AVAILABLE If no protocol helper exists for this scheme, or if it is not possible to get a description for it.
nsIHandlerInfo nsIExternalProtocolService::getProtocolHandlerInfo ( in ACString  aProtocolScheme  ) 

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.

Parameters:
aProtocolScheme the scheme from a URL: http, ftp, mailto, etc.

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

Returns:
the handler, if any; otherwise a default handler
nsIHandlerInfo nsIExternalProtocolService::getProtocolHandlerInfoFromOS ( in ACString  aProtocolScheme,
out boolean  aFound 
)

Given a scheme, looks up the protocol info from the OS.

This should be overridden by each OS's implementation.

Parameters:
aScheme The protocol scheme we are looking for.
aFound Was an OS default handler for this scheme found?
Returns:
An nsIHanderInfo for the protocol.
boolean nsIExternalProtocolService::isExposedProtocol ( in string  aProtocolScheme  ) 

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. XXX shouldn't aProtocolScheme be an ACString like nsIURI::scheme?

void nsIExternalProtocolService::loadURI ( in nsIURI  aURI,
[optional] in nsIInterfaceRequestor  aWindowContext 
)

Used to load a URI via an external application.

Might prompt the user for permission to load the external application.

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. We need to do better than that; bug 394483 filed in order to track.
Note:
Embedders that do not expose the http protocol should not currently use web-based protocol handlers, as handoff won't work correctly (bug 394479).
void nsIExternalProtocolService::loadUrl ( in nsIURI  aURL  ) 

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

Parameters:
aURL The url to load
Deprecated:
Use LoadURI instead (See Bug 389565 for removal)
void nsIExternalProtocolService::setProtocolHandlerDefaults ( in nsIHandlerInfo  aHandlerInfo,
in boolean  aOSHandlerExists 
)

Set some sane defaults for a protocol handler object.

Parameters:
aHandlerInfo 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.

The documentation for this interface was generated from the following file: