nsIWebContentHandlerRegistrar

Implemented by @mozilla.org/embeddor.implemented/web-content-handler-registrar;1 as a service:

var nsiwchr = Cc["@mozilla.org/embeddor.implemented/web-content-handler-registrar;1"]
                .getService(Ci.nsIWebContentHandlerRegistrar);

Method overview

Methods

registerContentHandler

Summary of registerContentHandler

void registerContentHandler(
  in DOMString mimeType,
  in DOMString uri,
  in DOMString title,
  in nsIDOMWindow contentWindow
);

Parameters

mimeType

The desired MIME type as a string

uri

The URI to the handler as a string.

title

The title of the handler presented to the user as a string.

contentWindow

The DOM content window from which the method has been called.

registerProtocolHandler

Summary of registerProtocolHandler

void registerProtocolHandler(
  in DOMString protocol,
  in DOMString uri,
  in DOMString title,
  in nsIDOMWindow contentWindow
);

Parameters

protocol

The protocol the site wishes to handle, specified as a string.

uri

The URI to the handler as a string. You must include "%s" to indicate where to insert the escaped URI of the document to be handled. Otherwise NS_ERROR_DOM_SYNTAX_ERR will be thrown. This string must also be of either the http or https schemes.

title

The title of the handler presented to the user as a string.

contentWindow

The DOM content window from which the method has been called.

Examples

Register a webmail service as mailto handler

The following code aims to add "Outlook.com Live Mail" to list of webservice handlers. In the image below "Gmail" and "Yahoo! Mail" already exist as webservice handlers.

Cu.import('resource://gre/modules/Services.jsm');

var nsiwchr = Cc["@mozilla.org/embeddor.implemented/web-content-handler-registrar;1"]
                .getService(Ci.nsIWebContentHandlerRegistrar);

var htmlContentWindow = undefined;
var registerUri = 'https://mail.live.com/secure/start?action=compose&to=%s';
var myURIHostName = Services.io.newURI(registerUri, null, null).host;

// this section here is long and daunting, but its just finding a suitable contentWindow
var DOMWindows = Services.wm.getEnumerator(null);
while (DOMWindows.hasMoreElements()) {
    var aDOMWindow = DOMWindows.getNext();
    if (aDOMWindow.gBrowser) {
        if (aDOMWindow.gBrowser.tabContainer) {
            //aDOMWindow has tabs
            var tabs = aDOMWindow.gBrowser.tabContainer.childNodes;
            for (var i = 0; i < tabs.length; i++) {
                console.log(tabs[i].linkedBrowser.contentWindow.location);
                if (tabs[i].linkedBrowser.contentWindow.location.hostname == myURIHostName) {
                    htmlContentWindow = tabs[i].linkedBrowser.contentWindow;
                    break; //break for loop
                }
            }
            if (htmlContentWindow) {
                break; //break while loop
            }
        } else {
            //aDOMWindow doest have any tabs
            if (aDOMWindow.gBrowser.contentWindow.location.hostname == myURIHostName) {
                htmlContentWindow = aDOMWindow.contentWindow;
                break;
            }
        }
    } else {
        //aDOMWindow is a popup window
        if (aDOMWindow.location.hostname == myURIHostName) {
            htmlContentWindow = aDOMWindow;
            break;
        }
    }
}
// this section here is long and daunting, but its just finding a suitable contentWindow

if (!htmlContentWindow) {
    throw new Error('No suitable content window found, will not reigsterProtocolHandler. Must have a content window to pass to registerProtocolHandler as it prompts the user for permission');
}

nsiwchr.registerProtocolHandler("mailto", registerUri, "Outlook.com Live Mail", htmlContentWindow);

In this example the Services.wm.getEnumerator was used to find a window that had the same host name (contentWindow.location.hostname) as the uri (uri.host) we are trying to add. If it does not find anything with host name of mail.live.com then it aborts. If the host names do not match, this error will be thrown in the Error Console.

Permission denied to add https://mail.live.com/secure/start?action=compose&to=%s as a content or protocol handler'Permission denied to add https://mail.live.com/secure/start?action=compose&to=%s as a content or protocol handler' when calling method: [nsIWebContentHandlerRegistrar::registerProtocolHandler]

If the host names do match then a confirmation like this will be seen:

This domain check can be bypassed by setting the preference of gecko.handlerService.allowRegisterFromDifferentHost to true as in this code here:

var {classes: Cc, interfaces: Ci, utils: Cu} = Components;
Cu.import("resource://gre/modules/Services.jsm");
var nsiwchr = Cc["@mozilla.org/embeddor.implemented/web-content-handler-registrar;1"]
                .getService(Ci.nsIWebContentHandlerRegistrar);

var allowRegisterFromDifferentHost = Services.prefs.getBoolPref('gecko.handlerService.allowRegisterFromDifferentHost');
if (!allowRegisterFromDifferentHost) {
  Services.prefs.setBoolPref('gecko.handlerService.allowRegisterFromDifferentHost', true);
}

var htmlContentWindow = Services.wm.getMostRecentWindow('navigator:browser'); //because we set the preference to true above, we need any window that has a browser, just pass the DOMWindow and the registerProtocolHandler will get the contentWindow from it

nsiwchr.registerProtocolHandler("mailto", "https://mail.live.com/secure/start?action=compose&to=%s", "Outlook.com Live Mail", htmlContentWindow);

if (!allowRegisterFromDifferentHost) {
  //it this variable is false, than we had set the pref to true obviously. so lets restore it back to false, which is the default value
  Services.prefs.clearUserPref('gecko.handlerService.allowRegisterFromDifferentHost');
}

Register a webmail service as mailto handler without contentWindow

Under construction. To take from:  https://mxr.mozilla.org/mozilla-release/source/browser/components/feeds/src/WebContentConverter.js#372 AND https://stackoverflow.com/questions/24900655/use-registerprotocolhandler-without-contentwindow

place holder

See also

• nsIWebContentSonverterService (under construction: page doesnt exist yet)
• registerProtocolHandler from Non-Privelaged Scope
• Web API Interfaces > Navigator.registerContentHandler()
• Web API Interfaces > Navigator.registerProtocolHandler()