WindowProxy.h (3631B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * vim: set ts=8 sts=2 et sw=2 tw=80: 3 * This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 /* 8 * Window and WindowProxy. 9 * 10 * For silly obscure reasons embedders are better off not knowing, the web wants 11 * every global object to exist as two linked components: a Window component 12 * that stores global variables and appears in environment chains but can't be 13 * directly referred to by any script, and a WindowProxy component that 14 * intermediates access to its Window that *can* be directly referred to by 15 * script. (Thus the global |window| and |globalThis| properties, |this| in 16 * global code, the value of |(function() { return this; })()| in non-strict 17 * mode code, and similar values are WindowProxy objects, not Windows.) 18 * 19 * Maintaining an invariant of never exposing a Window to script requires 20 * substituting in its WindowProxy in a variety of apparently arbitrary (but 21 * actually *very* carefully and nervously selected) places throughout the 22 * engine and indeed the universe. 23 * 24 * This header defines functions that let embeddings convert from a WindowProxy 25 * to its Window and vice versa. 26 * 27 * If you're not embedding SpiderMonkey in a web browser, you can almost 28 * certainly ignore this header. 29 */ 30 31 #ifndef js_friend_WindowProxy_h 32 #define js_friend_WindowProxy_h 33 34 #include "jstypes.h" // JS_PUBLIC_API 35 36 #include "js/Class.h" // JSCLASS_IS_GLOBAL 37 #include "js/Object.h" // JS::GetClass 38 #include "js/RootingAPI.h" // JS::Handle 39 40 struct JS_PUBLIC_API JSContext; 41 class JS_PUBLIC_API JSObject; 42 43 namespace js { 44 45 /** 46 * Tell the JS engine which Class is used for WindowProxy objects. Used by the 47 * functions below. 48 */ 49 extern JS_PUBLIC_API void SetWindowProxyClass(JSContext* cx, 50 const JSClass* clasp); 51 52 /** 53 * Associates a WindowProxy with a Window (global object). `windowProxy` must 54 * have the Class set by SetWindowProxyClass. 55 */ 56 extern JS_PUBLIC_API void SetWindowProxy(JSContext* cx, 57 JS::Handle<JSObject*> global, 58 JS::Handle<JSObject*> windowProxy); 59 60 namespace detail { 61 62 extern JS_PUBLIC_API bool IsWindowSlow(JSObject* obj); 63 64 extern JS_PUBLIC_API JSObject* ToWindowProxyIfWindowSlow(JSObject* obj); 65 66 } // namespace detail 67 68 /** 69 * Returns true iff `obj` is a global object with an associated WindowProxy, 70 * see SetWindowProxy. 71 */ 72 inline bool IsWindow(JSObject* obj) { 73 if (JS::GetClass(obj)->flags & JSCLASS_IS_GLOBAL) { 74 return detail::IsWindowSlow(obj); 75 } 76 return false; 77 } 78 79 /** 80 * Returns true iff `obj` has the WindowProxy Class (see SetWindowProxyClass). 81 */ 82 extern JS_PUBLIC_API bool IsWindowProxy(JSObject* obj); 83 84 /** 85 * If `obj` is a Window, get its associated WindowProxy (or a CCW or dead 86 * wrapper if the page was navigated away from), else return `obj`. This 87 * function is infallible and never returns nullptr. 88 */ 89 MOZ_ALWAYS_INLINE JSObject* ToWindowProxyIfWindow(JSObject* obj) { 90 if (JS::GetClass(obj)->flags & JSCLASS_IS_GLOBAL) { 91 return detail::ToWindowProxyIfWindowSlow(obj); 92 } 93 return obj; 94 } 95 96 /** 97 * If `obj` is a WindowProxy, get its associated Window (the compartment's 98 * global), else return `obj`. This function is infallible and never returns 99 * nullptr. 100 */ 101 extern JS_PUBLIC_API JSObject* ToWindowIfWindowProxy(JSObject* obj); 102 103 } // namespace js 104 105 #endif // js_friend_WindowProxy_h