diff -r 000000000000 -r 6474c204b198 dom/ipc/TabContext.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/dom/ipc/TabContext.h	Wed Dec 31 06:09:35 2014 +0100
@@ -0,0 +1,289 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set sw=2 ts=8 et 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/. */
+
+#ifndef mozilla_dom_TabContext_h
+#define mozilla_dom_TabContext_h
+
+#include "mozilla/layout/RenderFrameUtils.h"
+#include "mozIApplication.h"
+#include "nsCOMPtr.h"
+
+namespace mozilla {
+namespace dom {
+
+struct IPCTabContext;
+
+/**
+ * TabContext encapsulates information about an iframe that may be a mozbrowser
+ * or mozapp.  You can ask whether a TabContext corresponds to a mozbrowser or
+ * mozapp, get the app that contains the browser, and so on.
+ *
+ * TabParent and TabChild both inherit from TabContext, and you can also have
+ * standalone TabContext objects.
+ *
+ * This class is immutable except by calling one of the protected
+ * SetTabContext*() methods (and those methods can only be called once).  See
+ * also MutableTabContext.
+ */
+class TabContext
+{
+protected:
+  typedef mozilla::layout::ScrollingBehavior ScrollingBehavior;
+
+public:
+  TabContext();
+
+  /* (The implicit copy-constructor and operator= are fine.) */
+
+  /**
+   * Generates IPCTabContext of type BrowserFrameIPCTabContext or
+   * AppFrameIPCTabContext from this TabContext's information.
+   */
+  IPCTabContext AsIPCTabContext() const;
+
+  /**
+   * Does this TabContext correspond to a mozbrowser?  (<iframe mozbrowser
+   * mozapp> is not a browser.)
+   *
+   * If IsBrowserElement() is true, HasOwnApp() and HasAppOwnerApp() are
+   * guaranteed to be false.
+   *
+   * If IsBrowserElement() is false, HasBrowserOwnerApp() is guaranteed to be
+   * false.
+   */
+  bool IsBrowserElement() const;
+
+  /**
+   * Does this TabContext correspond to a mozbrowser or mozapp?  This is
+   * equivalent to IsBrowserElement() || HasOwnApp().
+   */
+  bool IsBrowserOrApp() const;
+
+  /**
+   * OwnAppId() returns the id of the app which directly corresponds to this
+   * context's frame.  GetOwnApp() returns the corresponding app object, and
+   * HasOwnApp() returns true iff GetOwnApp() would return a non-null value.
+   *
+   * If HasOwnApp() is true, IsBrowserElement() is guaranteed to be false.
+   */
+  uint32_t OwnAppId() const;
+  already_AddRefed<mozIApplication> GetOwnApp() const;
+  bool HasOwnApp() const;
+
+  /**
+   * BrowserOwnerAppId() gets the ID of the app which contains this browser
+   * frame.  If this is not a browser frame (i.e., if !IsBrowserElement()), then
+   * BrowserOwnerAppId() is guaranteed to return NO_APP_ID.
+   *
+   * Even if we are a browser frame, BrowserOwnerAppId() may still return
+   * NO_APP_ID, if this browser frame is not contained inside an app.
+   */
+  uint32_t BrowserOwnerAppId() const;
+  already_AddRefed<mozIApplication> GetBrowserOwnerApp() const;
+  bool HasBrowserOwnerApp() const;
+
+  /**
+   * AppOwnerAppId() gets the ID of the app which contains this app frame.  If
+   * this is not an app frame (i.e., if !HasOwnApp()), then AppOwnerAppId() is
+   * guaranteed to return NO_APP_ID.
+   *
+   * Even if we are an app frame, AppOwnerAppId() may still return NO_APP_ID, if
+   * this app frame is not contained inside an app.
+   */
+  uint32_t AppOwnerAppId() const;
+  already_AddRefed<mozIApplication> GetAppOwnerApp() const;
+  bool HasAppOwnerApp() const;
+
+  /**
+   * OwnOrContainingAppId() gets the ID of this frame, if HasOwnApp().  If this
+   * frame does not have its own app, it gets the ID of the app which contains
+   * this frame (i.e., the result of {Browser,App}OwnerAppId(), as applicable).
+   */
+  uint32_t OwnOrContainingAppId() const;
+  already_AddRefed<mozIApplication> GetOwnOrContainingApp() const;
+  bool HasOwnOrContainingApp() const;
+
+  /**
+   * Return the requested scrolling behavior for this frame.
+   */
+  ScrollingBehavior GetScrollingBehavior() const { return mScrollingBehavior; }
+
+protected:
+  friend class MaybeInvalidTabContext;
+
+  /**
+   * These protected mutator methods let you modify a TabContext once.  Further
+   * attempts to modify a given TabContext will fail (the method will return
+   * false).
+   *
+   * These mutators will also fail if the TabContext was created with anything
+   * other than the no-args constructor.
+   */
+
+  /**
+   * Set this TabContext to match the given TabContext.
+   */
+  bool SetTabContext(const TabContext& aContext);
+
+  /**
+   * Set this TabContext to be an app frame (with the given own app) inside the
+   * given app.  Either or both apps may be null.
+   */
+  bool SetTabContextForAppFrame(mozIApplication* aOwnApp,
+                                mozIApplication* aAppFrameOwnerApp,
+                                ScrollingBehavior aRequestedBehavior);
+
+  /**
+   * Set this TabContext to be a browser frame inside the given app (which may
+   * be null).
+   */
+  bool SetTabContextForBrowserFrame(mozIApplication* aBrowserFrameOwnerApp,
+                                    ScrollingBehavior aRequestedBehavior);
+
+  /**
+   * Set this TabContext to be a normal non-browser non-app frame.
+   */
+  bool SetTabContextForNormalFrame(ScrollingBehavior aRequestedBehavior);
+
+private:
+  /**
+   * Has this TabContext been initialized?  If so, mutator methods will fail.
+   */
+  bool mInitialized;
+
+  /**
+   * This TabContext's own app.  If this is non-null, then this
+   * TabContext corresponds to an app, and mIsBrowser must be false.
+   */
+  nsCOMPtr<mozIApplication> mOwnApp;
+
+  /**
+   * A cache of mOwnApp->GetLocalId().  Speed really does matter here, since we
+   * read this ID often during process startup.
+   */
+  uint32_t mOwnAppId;
+
+  /**
+   * This TabContext's containing app.  If mIsBrowser, this corresponds to the
+   * app which contains the browser frame; otherwise, this corresponds to the
+   * app which contains the app frame.
+   */
+  nsCOMPtr<mozIApplication> mContainingApp;
+
+  /*
+   * Cache of mContainingApp->GetLocalId().
+   */
+  uint32_t mContainingAppId;
+
+  /**
+   * The requested scrolling behavior for this frame.
+   */
+  ScrollingBehavior mScrollingBehavior;
+
+  /**
+   * Does this TabContext correspond to a browser element?
+   *
+   * If this is true, mOwnApp must be null.
+   */
+  bool mIsBrowser;
+};
+
+/**
+ * MutableTabContext is the same as MaybeInvalidTabContext, except the mutation
+ * methods are public instead of protected.  You can still only call these
+ * mutation methods once on a given object.
+ */
+class MutableTabContext : public TabContext
+{
+public:
+  bool SetTabContext(const TabContext& aContext)
+  {
+    return TabContext::SetTabContext(aContext);
+  }
+
+  bool SetTabContextForAppFrame(mozIApplication* aOwnApp, mozIApplication* aAppFrameOwnerApp,
+                                ScrollingBehavior aRequestedBehavior)
+  {
+    return TabContext::SetTabContextForAppFrame(aOwnApp, aAppFrameOwnerApp,
+                                                aRequestedBehavior);
+  }
+
+  bool SetTabContextForBrowserFrame(mozIApplication* aBrowserFrameOwnerApp,
+                                    ScrollingBehavior aRequestedBehavior)
+  {
+    return TabContext::SetTabContextForBrowserFrame(aBrowserFrameOwnerApp,
+                                                    aRequestedBehavior);
+  }
+
+  bool SetTabContextForNormalFrame(ScrollingBehavior aRequestedBehavior)
+  {
+    return TabContext::SetTabContextForNormalFrame(aRequestedBehavior);
+  }
+};
+
+/**
+ * MaybeInvalidTabContext is a simple class that lets you transform an
+ * IPCTabContext into a TabContext.
+ *
+ * The issue is that an IPCTabContext is not necessarily valid; for example, it
+ * might specify an app-id which doesn't exist.  So to convert an IPCTabContext
+ * into a TabContext, you construct a MaybeInvalidTabContext, check whether it's
+ * valid, and, if so, read out your TabContext.
+ *
+ * Example usage:
+ *
+ *   void UseTabContext(const TabContext& aTabContext);
+ *
+ *   void CreateTab(const IPCTabContext& aContext) {
+ *     MaybeInvalidTabContext tc(aContext);
+ *     if (!tc.IsValid()) {
+ *       NS_ERROR(nsPrintfCString("Got an invalid IPCTabContext: %s",
+ *                                tc.GetInvalidReason()));
+ *       return;
+ *     }
+ *     UseTabContext(tc.GetTabContext());
+ *   }
+ */
+class MaybeInvalidTabContext
+{
+public:
+  /**
+   * This constructor copies the information in aContext and sets IsValid() as
+   * appropriate.
+   */
+  MaybeInvalidTabContext(const IPCTabContext& aContext);
+
+  /**
+   * Was the IPCTabContext we received in our constructor valid?
+   */
+  bool IsValid();
+
+  /**
+   * If IsValid(), this function returns null.  Otherwise, it returns a
+   * human-readable string indicating why the IPCTabContext passed to our
+   * constructor was not valid.
+   */
+  const char* GetInvalidReason();
+
+  /**
+   * If IsValid(), this function returns a reference to a TabContext
+   * corresponding to the IPCTabContext passed to our constructor.  If
+   * !IsValid(), this function crashes.
+   */
+  const TabContext& GetTabContext();
+
+private:
+  MaybeInvalidTabContext(const MaybeInvalidTabContext&) MOZ_DELETE;
+  MaybeInvalidTabContext& operator=(const MaybeInvalidTabContext&) MOZ_DELETE;
+
+  const char* mInvalidReason;
+  MutableTabContext mTabContext;
+};
+
+} // namespace dom
+} // namespace mozilla
+
+#endif