Waives Xray vision for an object, giving the caller a transparent wrapper to the underlying object.
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.
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.
waived = Components.utils.waiveXrays(obj);
- The object for which we wish to waive Xrays.
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
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