XPCNativeWrapper

  • Revision slug: XPCNativeWrapper
  • Revision title: XPCNativeWrapper
  • Revision id: 92994
  • Created:
  • Creator: Bzbarsky
  • Is current revision? No
  • Comment /* Explicit <code>XPCNativeWrapper</code> with no string arguments */

Revision Content

XPCNativeWrapper is a way to wrap up an object so that it's safe to access from privileged code. It can be used in all Firefox versions, though the behavior changed somewhat starting with Firefox 1.1.

XPCNativeWrapper in Firefox versions prior to 1.1

In Firefox versions prior to 1.1, use of XPCNativeWrapper requires manually constructing an XPCNativeWrapper and passing it the object to be wrapped and the names of the methods/properties to be exposed as arguments. The resulting object exposes ONLY the methods/properties whose methods were passed as arguments. This is described in more detail in the the entry for XPCNativeWrapper at the MozillaZine KnowledgeBase.

XPCNativeWrapper in Firefox versions starting with 1.1

bz: Three types, or two? Still sorting this out. See https://bugzilla.mozilla.org/show_bug.cgi?id=295782

There are three slightly different types of XPCNativeWrapper in Firefox 1.1. All three types wrap a possibly-unsafe object and provide safe access to all of its properties and methods (unlike XPCNativeWrapper in versions before 1.1, which only provided safe access to the properties and methods listed in its constructor). If unsafe access to a property is required for some reason, this can be accomplished via the wrappedJSObject property of the wrapper. For example, if docWrapper is a wrapper for doc, then

docWrapper.wrappedJSObject.prop

is the same as

doc.prop

One limitation of XPCNativeWrapper is that assigning to the location property of a wrapped document or window will not work. Code that wishes to set the location should assign to the href property of the location object (after wrapping the location object itself, as needed).

Explicit XPCNativeWrapper with string arguments

For example:

var contentWinWrapper = new XPCNativeWrapper(content,
                                             "document");

This syntax has been kept for compatibility with versions prior to Firefox 1.1. While all properties of the contentWinWrapper object can now be safely accessed, the return values of these properties are NOT safe to access (just like in versions prior to Firefox 1.1). So to compare the content document title to the current content selection, one must do:

var winWrapper = new XPCNativeWrapper(content, "document",
                                      "getSelection()");
var docWrapper = new XPCNativeWrapper(winWrapper.document,
                                      "title");
return docWrapper.title == winWrapper.getSelection();

Note that the "getSelection()" argument is not strictly needed here; if the code is not intended for use with Firefox versions before 1.1 it can be removed. A single string argument after the object being wrapped is all that is required for Firefox 1.1.

Explicit XPCNativeWrapper with no string arguments

For example:

var contentWinWrapper = new XPCNativeWrapper(content);

The resulting object behaves just like an implicit wrapper, except that properties set on it will not be visible on either other explicit wrappers or implicit wrappers. Note that this means that for code not using xpcnativewrappers=yes this type of XPCNativeWrapper is useless.

bz: Again, see https://bugzilla.mozilla.org/show_bug.cgi?id=295782 -- that might introduce differences between this type of wrapper and implicit wrappers.

Implicit XPCNativeWrapper

Revision Source

<p><code>XPCNativeWrapper</code> is a way to wrap up an object so that it's safe to access from privileged code.  It can be used in all Firefox versions, though the 
behavior changed somewhat starting with Firefox 1.1.
</p>
<h3 name="XPCNativeWrapper_in_Firefox_versions_prior_to_1.1"> <code>XPCNativeWrapper</code> in Firefox versions prior to 1.1 </h3>
<p>In Firefox versions prior to 1.1, use of <code>XPCNativeWrapper</code> requires manually constructing an <code>XPCNativeWrapper</code> and passing it the object to be wrapped and the names of the methods/properties to be exposed as arguments.  The resulting object exposes ONLY the methods/properties whose methods were passed as arguments.  This is described in more detail in the <a class="external" href="http://kb.mozillazine.org/XPCNativeWrapper">the entry for <code>XPCNativeWrapper</code> at the MozillaZine KnowledgeBase</a>.
</p>
<h3 name="XPCNativeWrapper_in_Firefox_versions_starting_with_1.1"> <code>XPCNativeWrapper</code> in Firefox versions starting with 1.1 </h3>
<p><i>bz: Three types, or two?  Still sorting this out.  See https://bugzilla.mozilla.org/show_bug.cgi?id=295782</i>
</p><p>There are three slightly different types of <code>XPCNativeWrapper</code> in Firefox 1.1.  All three types wrap a possibly-unsafe object and provide safe access to all of its properties and methods (unlike <code>XPCNativeWrapper</code> in versions before 1.1, which only provided safe access to the properties and methods listed in its constructor).  If unsafe access to a property is required for some reason, this can be accomplished via the <code>wrappedJSObject</code> property of the wrapper.  For example, if <code>docWrapper</code> is a wrapper for <code>doc</code>, then
</p>
<pre class="eval">docWrapper.wrappedJSObject.prop
</pre>
<p>is the same as
</p>
<pre class="eval">doc.prop
</pre>
<p>One limitation of <code>XPCNativeWrapper</code> is that assigning to the <code>location</code> property of a wrapped document or window will not work.  Code that wishes to set the location should assign to the <code>href</code> property of the location object (after wrapping the location object itself, as needed).
</p>
<h4 name="Explicit_XPCNativeWrapper_with_string_arguments"> Explicit <code>XPCNativeWrapper</code> with string arguments </h4>
<p>For example:
</p>
<pre class="eval">var contentWinWrapper = new XPCNativeWrapper(content,
                                             "document");
</pre>
<p>This syntax has been kept for compatibility with versions prior to Firefox 1.1.  While all properties of the <code>contentWinWrapper</code> object can now be safely accessed, the return values of these properties are NOT safe to access (just like in versions prior to Firefox 1.1).  So to compare the content document title to the current content selection, one must do:
</p>
<pre class="eval">var winWrapper = new XPCNativeWrapper(content, "document",
                                      "getSelection()");
var docWrapper = new XPCNativeWrapper(winWrapper.document,
                                      "title");
return docWrapper.title == winWrapper.getSelection();
</pre>
<p>Note that the <code>"getSelection()"</code> argument is not strictly needed here; if the code is not intended for use with Firefox versions before 1.1 it can be removed.  A single string argument after the object being wrapped is all that is required for Firefox 1.1.
</p>
<h4 name="Explicit_XPCNativeWrapper_with_no_string_arguments"> Explicit <code>XPCNativeWrapper</code> with no string arguments </h4>
<p>For example:
</p>
<pre class="eval">var contentWinWrapper = new XPCNativeWrapper(content);
</pre>
<p>The resulting object behaves just like an implicit wrapper, except that properties set on it will not be visible on either other explicit wrappers or implicit wrappers.  Note that this means that for code not using <code>xpcnativewrappers=yes</code> this type of <code>XPCNativeWrapper</code> is useless.
</p><p><i>bz: Again, see https://bugzilla.mozilla.org/show_bug.cgi?id=295782 -- that might introduce differences between this type of wrapper and implicit wrappers.</i>
</p>
<h4 name="Implicit_XPCNativeWrapper"> Implicit <code>XPCNativeWrapper</code> </h4>
Revert to this revision