xpcom

Using this module you can:

  • register a component with XPCOM, making it available to all XPCOM clients
  • retrieve a factory for a given XPCOM component
  • generate a UUID

The module also exposes the XPCOMUtils module.

API Reference

Classes

Factory

When a component is made available through XPCOM using the register() function, register() returns a Factory object that can be used to instantiate the component using its createInstance() function:

var factory = require("xpcom").register({
  name: "My Component",
  contractID: "@me.org/myComponent",
  create: MyComponent
});

var {Ci} = require("chrome");
var component = factory.createInstance(null, Ci.nsISupports).wrappedJSObject;

In this example we haven't defined a custom interface ID for the component. Instead we pass Ci.nsISupports as the interface ID, and use wrappedJSObject to retrieve the component. For more details on this technique see the guide to building XPCOM components in JavaScript.

Factory also implements its own unregister() function, which unregisters the component from XPCOM.

Methods
createInstance(outer, iid)

Creates an instance of the component associated with this factory.

outer : nsISupports

This argument must be null, or the function throws Cr.NS_ERROR_NO_AGGREGATION.

iid : iid

Interface identifier. These objects are usually accessed through the Components.interfaces, or Ci, object. The methods of this interface will be callable on the returned object.

If the object implements an interface that's already defined in XPCOM, you can pass that in here:

var about = aboutFactory.createInstance(null, Ci.nsIAboutModule);
// You can now access the nsIAboutModule interface of the 'about' object

If you will be getting the wrappedJSObject property from the returned object to access its JavaScript implementation, pass Ci.nsISupports here:

var custom = factory.createInstance(null, Ci.nsISupports).wrappedJSObject;
// You can now access the interface defined for the 'custom' object
QueryInterface(interfaces)

This method is called automatically by XPCOM, so usually you don't need to call it yourself. It returns the Factory object itself such that the methods of the given interface are callable on it.

interfaces : iid

There are only two legal values for this parameter: Ci.nsIFactory and Ci.nsISupports. Any other value will cause this method to throw Cr.NS_ERROR_NO_INTERFACE.

Returns: Factory
unregister()

Unregisters the factory's component.

Functions

register(options)

Makes a component available through XPCOM.

This function creates and registers a factory for a component given a constructor for it and some metadata: a class ID, a contract ID, and a name.

In this example the HelloWorld component is available to JavaScript only, so we use the technique documented under the "Using wrappedJSObject" section of How to Build an XPCOM Component in JavaScript.

var xpcom = require("xpcom");

function HelloWorld() {
  this.wrappedJSObject = this;
}

HelloWorld.prototype = {
  QueryInterface: xpcom.utils.generateQI(),
  hello: function() {
    return "Hello World!";
  }
};

xpcom.register({name: "Hello World Component",
                contractID: "@me.org/myComponent",
                create: HelloWorld});

XPCOM clients can subsequently access this factory and use it to create instances of the component.

var {Ci} = require("chrome");

var factory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory);
var helloWorld = factory.createInstance(null, Ci.nsISupports).wrappedJSObject;
console.log(helloWorld.hello());

register() returns a Factory object for the component which implements the createInstance() and QueryInterface() functions of the nsIFactory and nsISupports interfaces, as well as defining an unregister() function to remove the component from XPCOM.

When the module is unloaded, all components registered via the register() function are automatically unregistered.

options : object
[ uuid : nsIDPtr ]

A UUID which will be used as the class ID for this component. If you don't include this option, the register() function will generate a new UUID.

create : function

The constructor for the component.

name : string

A human-readable name for the component.

contractID : string

A human-readable string which will be used as the contract ID for the component. An XPCOM client will be able to use this value to access the component.

Returns: Factory

See the documentation for the Factory class in this page.

getClass(contractID, iid)

Returns the factory object for the class specified by contractID.

For example, given a registered XPCOM component which is identified with the contract ID "@me.org/myComponent", we can access a factory and then use it to instantiate the component in the following way:

var xpcom = require("xpcom");
var {Ci} = require("chrome");

var factory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory);
var helloWorld = factory.createInstance(null, Ci.nsISupports).wrappedJSObject;
console.log(helloWorld.hello());
contractID : string

The contract ID for the component whose factory will be returned.

[ iid : iid ]

The interface type to be returned. These objects are usually accessed through the Components.interfaces, or Ci, object.

The methods of this interface will be callable on the returned factory object. Usually you want this to be Ci.nsIFactory, but if you know a component has a factory that implements a more specific type of factory interface, you can pass that interface here. If you don't include this option only the methods of nsISupports will be callable, which is probably not what you want.

Returns: object

The factory object. The type of this object will depend on the value of the iid argument. If no iid argument is specified it will be of type nsISupports.

Note that this object is not a Factory object as defined by this module. If you previously registered the component by calling the register() function and you need to access the Factory object for the component, for example to call the Factory's unregister() method, you can do so by getting the wrappedJSObject property of the returned object:

var factory = xpcom.getClass("@me.org/myComp", Ci.nsIFactory).wrappedJSObject;
factory.unregister();

makeUuid()

Generates and returns a new UUID.

Calling toString() on this object will yield the UUID in string form.

Returns: nsIDPtr

Properties

utils : object

The XPCOMUtils module.