Undo a previous call to Components.utils.waiveXrays(), restoring Xray vision for the caller.

For example, if privileged code accesses a DOM object belonging to web content, it will by default see it using Xray vision, meaning that among other things expando properties added to the object by content are not visible. Privileged code can waive Xray vision using waiveXrays, and it will then see expandos. It can then use unwaiveXrays to restore its Xray vision for the object.

The waiveXrays operation is transitive:  it waives Xrays not just for the given object, but for all properties of the object (and their properties, and so on). The unwaiveXrays operation undoes the operation, so Xray vision is restored transitively as well.

Syntax

xray = Components.utils.unwaiveXrays(obj);

Parameters

obj
The object for which we wish to restore Xrays.

Returns

The object with Xrays restored.

Example

Suppose a page script adds an expando to its global window:

// page script

foo = "I'm an expando";

By default, chrome code won't see foo, because it sees the content window with Xray vision, but the chrome code can waive Xray protection. The chrome code can then use unwaiveXrays to restore Xray protection:

// chrome code

// contentWindow is an Xray
var isXray = Components.utils.isXrayWrapper(gBrowser.contentWindow);  // true

// expandos are not visible in Xrays
var foo = gBrowser.contentWindow.foo;                                 // undefined

// you can waive Xray vision for an object
var waived = Components.utils.waiveXrays(gBrowser.contentWindow);
isXray = Components.utils.isXrayWrapper(waived);                      // false
foo = waived.foo;                                                     // "I'm an expando"

// waiving is transitive
isXray = Components.utils.isXrayWrapper(waived.document);             // false

// use unwaiveXrays to undo the waiver
var unwaived = Components.utils.unwaiveXrays(waived);
isXray = Components.utils.isXrayWrapper(unwaived);                    // true
foo = unwaived.foo;                                                   // undefined

// unwaiving is transitive
isXray = Components.utils.isXrayWrapper(unwaived.document);           // true

See also