Waives Xray vision for an object, giving the caller a transparent wrapper to the underlying object.
When privileged JavaScript in Gecko accesses objects belonging to less-privileged code (such as untrusted web content), it does so, by default, with "Xray vision": a mechanism that filters out certain changes to the objects that could cause them to behave in unexpected ways. For example, privileged code using an Xray to a DOM object sees only the original, native version of the DOM object. Any expando properties are not visible, and if any native properties have been redefined, this has no effect.
Xray vision is designed to make most simple operations safe. However, in some cases it can be too restrictive: for example, if you need to see an expando property on a DOM object. In these cases you can use waiveXrays to remove Xray vision for the object.
Waiving Xrays is transitive, so waiving it for an object automatically waives it for any properties of that object (and their properties, and so on).
If you waive Xray vision, you can no longer trust that any of the object's properties are what you expect: any of them, including prototypes and accessors, could have been redefined by the less-privileged code.
To undo waiveXrays and get Xray vision back, call Components.utils.unwaiveXrays on the object.
The result of waiveXrays is just like the wrappedJSObject property for Xrayed objects, but it's more useful because you can call it on primitives or objects that aren't Xrays, in which case it just returns the argument you passed in. This means you don't have to care whether the initial object is an Xray or not.
Syntax
waived = Components.utils.waiveXrays(obj);
Parameters
-
obj - The object for which we wish to waive Xrays.
Returns
If the argument obj is an Xray, this function returns a wrapper that transitively waives Xray behavior on the underlying object and anything that comes off the object. If obj is not an Xray, this function just returns obj.
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:
// 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