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.