summaryrefslogtreecommitdiffstats
path: root/js/public/friend/WindowProxy.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--js/public/friend/WindowProxy.h105
1 files changed, 105 insertions, 0 deletions
diff --git a/js/public/friend/WindowProxy.h b/js/public/friend/WindowProxy.h
new file mode 100644
index 0000000000..9023e9e96b
--- /dev/null
+++ b/js/public/friend/WindowProxy.h
@@ -0,0 +1,105 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ * vim: set ts=8 sts=2 et sw=2 tw=80:
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/*
+ * Window and WindowProxy.
+ *
+ * For silly obscure reasons embedders are better off not knowing, the web wants
+ * every global object to exist as two linked components: a Window component
+ * that stores global variables and appears in environment chains but can't be
+ * directly referred to by any script, and a WindowProxy component that
+ * intermediates access to its Window that *can* be directly referred to by
+ * script. (Thus the global |window| and |globalThis| properties, |this| in
+ * global code, the value of |(function() { return this; })()| in non-strict
+ * mode code, and similar values are WindowProxy objects, not Windows.)
+ *
+ * Maintaining an invariant of never exposing a Window to script requires
+ * substituting in its WindowProxy in a variety of apparently arbitrary (but
+ * actually *very* carefully and nervously selected) places throughout the
+ * engine and indeed the universe.
+ *
+ * This header defines functions that let embeddings convert from a WindowProxy
+ * to its Window and vice versa.
+ *
+ * If you're not embedding SpiderMonkey in a web browser, you can almost
+ * certainly ignore this header.
+ */
+
+#ifndef js_friend_WindowProxy_h
+#define js_friend_WindowProxy_h
+
+#include "jstypes.h" // JS_PUBLIC_API
+
+#include "js/Class.h" // JSCLASS_IS_GLOBAL
+#include "js/Object.h" // JS::GetClass
+#include "js/RootingAPI.h" // JS::Handle
+
+struct JS_PUBLIC_API JSContext;
+class JS_PUBLIC_API JSObject;
+
+namespace js {
+
+/**
+ * Tell the JS engine which Class is used for WindowProxy objects. Used by the
+ * functions below.
+ */
+extern JS_PUBLIC_API void SetWindowProxyClass(JSContext* cx,
+ const JSClass* clasp);
+
+/**
+ * Associates a WindowProxy with a Window (global object). `windowProxy` must
+ * have the Class set by SetWindowProxyClass.
+ */
+extern JS_PUBLIC_API void SetWindowProxy(JSContext* cx,
+ JS::Handle<JSObject*> global,
+ JS::Handle<JSObject*> windowProxy);
+
+namespace detail {
+
+extern JS_PUBLIC_API bool IsWindowSlow(JSObject* obj);
+
+extern JS_PUBLIC_API JSObject* ToWindowProxyIfWindowSlow(JSObject* obj);
+
+} // namespace detail
+
+/**
+ * Returns true iff `obj` is a global object with an associated WindowProxy,
+ * see SetWindowProxy.
+ */
+inline bool IsWindow(JSObject* obj) {
+ if (JS::GetClass(obj)->flags & JSCLASS_IS_GLOBAL) {
+ return detail::IsWindowSlow(obj);
+ }
+ return false;
+}
+
+/**
+ * Returns true iff `obj` has the WindowProxy Class (see SetWindowProxyClass).
+ */
+extern JS_PUBLIC_API bool IsWindowProxy(JSObject* obj);
+
+/**
+ * If `obj` is a Window, get its associated WindowProxy (or a CCW or dead
+ * wrapper if the page was navigated away from), else return `obj`. This
+ * function is infallible and never returns nullptr.
+ */
+MOZ_ALWAYS_INLINE JSObject* ToWindowProxyIfWindow(JSObject* obj) {
+ if (JS::GetClass(obj)->flags & JSCLASS_IS_GLOBAL) {
+ return detail::ToWindowProxyIfWindowSlow(obj);
+ }
+ return obj;
+}
+
+/**
+ * If `obj` is a WindowProxy, get its associated Window (the compartment's
+ * global), else return `obj`. This function is infallible and never returns
+ * nullptr.
+ */
+extern JS_PUBLIC_API JSObject* ToWindowIfWindowProxy(JSObject* obj);
+
+} // namespace js
+
+#endif // js_friend_WindowProxy_h