wrappedJSObject
is a property sometimes available on XPConnect wrappers. When available, it lets you access the JavaScript object hidden by the wrapper.
There are two kinds of XPConnect wrappers that support the wrappedJSObject
property:
- XPCNativeWrappers which are used to protect the chrome code working with content objects. See XPCNativeWrapper for detailed documentation.
- Regular XPConnect wrappers which you can encounter, for example, when using XPCOM components implemented in JS.
This article focuses on the latter kind of wrappers, which hide any properties or methods on the component that are not part of the supported interfaces as declared in xpidl.
The rest of this article demonstrates what XPConnect wrappers do and how wrappedJSObject
can be used to bypass them.
Example component
To see how the wrappedJSObject
property works, we need an example XPCOM component implemented in JS. See How to Build an XPCOM Component in Javascript for details on creating one.
For simplicity we omit the component registration code. Suppose we register the component below with the @myself.com/my-component;1
contract.
// constructor function HelloWorld() { }; HelloWorld.prototype = { hello: function() { return "Hello World!"; }, QueryInterface: function(aIID) { if (!aIID.equals(Components.interfaces.nsISupports) && !aIID.equals(Components.interfaces.nsIHelloWorld)) throw Components.results.NS_ERROR_NO_INTERFACE; return this; } };
XPConnect wrapping
Now let's get a reference to our component. In this example we use getService
, but as long as we get the reference from XPCOM, our component gets wrapped by XPConnect in the same way:
var comp = Components.classes["@myself.com/my-component;1"].getService();
If we try to call the hello()
method we defined in our component implementation, we get:
> comp.hello(); TypeError on line 1: comp.hello is not a function
This happens because, as we mentioned earlier, comp
is not the HelloWorld
JS object itself, but an XPConnect wrapper around it:
> dump(comp); [xpconnect wrapped nsISupports]
The idea of these wrappers is to make the JavaScript-implemented XPCOM components look just like any other XPCOM component to the user. This also makes the public interface of the component clearer and provides protection for the component's internal data.
Calling QueryInterface
on the wrapper works, because it is defined in the nsISupports
interface, and the wrapper knows the underlying object implements nsISupports
:
> comp.QueryInterface(Components.interfaces.nsIHelloWorld); [xpconnect wrapped (nsISupports, nsIHelloWorld)]
As you can see, the QueryInterface
call also made the wrapper know about the other interface our component supports. Assuming the nsIHelloWorld
interface defines the hello
method, we can now call it:
> comp.hello() Hello World!
While this behavior is nice for production code as it forces you to clearly define the interfaces that should be used to access the component, it's inconvenient to write the interfaces (and recompile each time you change them) when working on a prototype of the component.
Meet wrappedJSObject
XPConnect lets you bypass its wrappers and access the underlying JS object directly using the wrapper.wrappedJSObject
property if the wrapped object allows this.
More specifically, as XPConnect source comments say, you can get comp.wrappedJSObject
if three conditions are met:
-
comp
really is an XPConnect wrapper around a JS object. Wrappers around non-JS objects don't have this property. - The underlying object has a
wrappedJSObject
property that returns a JS object. -
nsIXPCSecurityManager
allows access (see the source code comments for details; this is usually not an issue for Mozilla extensions and applications)
This means that in order to access the JS object implementing our component directly, we must modify the component. For example:
function HelloWorld() { this.wrappedJSObject = this; };
Now we can get the component directly:
var comp = Components.classes["@myself.com/my-component;1"] .getService().wrappedJSObject;
This is a real JS object:
> comp [object Object]
So we can access any property on it:
> comp.hello(); Hello World!
This functionality can be used for quick prototyping, as well as to painlessly pass arbitrary JS values to the component (which can be used for sharing complex JS data in particular).