dom/ipc/TabContext.h

   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 #ifndef mozilla_dom_TabContext_h
   8 #define mozilla_dom_TabContext_h
   9
  10 #include "nsCOMPtr.h"
  11 #include "mozilla/BasePrincipal.h"
  12 #include "nsPIDOMWindow.h"
  13 #include "nsPIWindowRoot.h"
  14
  15 namespace mozilla::dom {
  16
  17 class IPCTabContext;
  18
  19 /**
  20  * TabContext encapsulates information about an iframe.
  21  *
  22  * BrowserParent and BrowserChild both inherit from TabContext, and you can also
  23  * have standalone TabContext objects.
  24  *
  25  * This class is immutable except by calling one of the protected
  26  * SetTabContext*() methods (and those methods can only be called once).  See
  27  * also MutableTabContext.
  28  */
  29 class TabContext {
  30  public:
  31   TabContext();
  32
  33   /* (The implicit copy-constructor and operator= are fine.) */
  34
  35   /**
  36    * Generates IPCTabContext of type BrowserFrameIPCTabContext from this
  37    * TabContext's information.
  38    */
  39   IPCTabContext AsIPCTabContext() const;
  40
  41   bool IsJSPlugin() const;
  42   int32_t JSPluginId() const;
  43
  44   uint64_t ChromeOuterWindowID() const;
  45
  46   uint32_t MaxTouchPoints() const { return mMaxTouchPoints; }
  47
  48  protected:
  49   friend class MaybeInvalidTabContext;
  50
  51   /**
  52    * These protected mutator methods let you modify a TabContext once.  Further
  53    * attempts to modify a given TabContext will fail (the method will return
  54    * false).
  55    *
  56    * These mutators will also fail if the TabContext was created with anything
  57    * other than the no-args constructor.
  58    */
  59
  60   /**
  61    * Set this TabContext to match the given TabContext.
  62    */
  63   bool SetTabContext(const TabContext& aContext);
  64
  65   bool SetTabContext(uint64_t aChromeOuterWindowID, uint32_t aMaxTouchPoints);
  66
  67   /**
  68    * Modify this TabContext to match the given TabContext.  This is a special
  69    * case triggered by nsFrameLoader::SwapWithOtherRemoteLoader which may have
  70    * caused the owner content to change.
  71    *
  72    * This special case only allows the field `mChromeOuterWindowID` to be
  73    * changed.  If any other fields have changed, the update is ignored and
  74    * returns false.
  75    */
  76   bool UpdateTabContextAfterSwap(const TabContext& aContext);
  77
  78   /**
  79    * Set this TabContext to be for a JS plugin. aPluginID is the id of the JS
  80    * plugin
  81    * (@see nsFakePlugin::mId).
  82    * As with the other protected mutator methods, this lets you modify a
  83    * TabContext once.
  84    * (@see TabContext::SetTabContext above for more details).
  85    */
  86   bool SetTabContextForJSPluginFrame(int32_t aJSPluginID);
  87
  88   void SetMaxTouchPoints(uint32_t aMaxTouchPoints) {
  89     mMaxTouchPoints = aMaxTouchPoints;
  90   }
  91
  92  private:
  93   /**
  94    * Has this TabContext been initialized?  If so, mutator methods will fail.
  95    */
  96   bool mInitialized;
  97
  98   /**
  99    * The outerWindowID of the window hosting the remote frameloader.
 100    */
 101   uint64_t mChromeOuterWindowID;
 102
 103   int32_t mJSPluginID;
 104
 105   /**
 106    * Maximum number of touch points.
 107    */
 108   uint32_t mMaxTouchPoints;
 109 };
 110
 111 /**
 112  * MutableTabContext is the same as MaybeInvalidTabContext, except the mutation
 113  * methods are public instead of protected.  You can still only call these
 114  * mutation methods once on a given object.
 115  */
 116 class MutableTabContext : public TabContext {
 117  public:
 118   bool SetTabContext(const TabContext& aContext) {
 119     return TabContext::SetTabContext(aContext);
 120   }
 121
 122   bool SetTabContext(uint64_t aChromeOuterWindowID, uint32_t aMaxTouchPoints) {
 123     return TabContext::SetTabContext(aChromeOuterWindowID, aMaxTouchPoints);
 124   }
 125
 126   bool SetTabContextForJSPluginFrame(uint32_t aJSPluginID) {
 127     return TabContext::SetTabContextForJSPluginFrame(aJSPluginID);
 128   }
 129 };
 130
 131 /**
 132  * MaybeInvalidTabContext is a simple class that lets you transform an
 133  * IPCTabContext into a TabContext.
 134  *
 135  * The issue is that an IPCTabContext is not necessarily valid.  So to convert
 136  * an IPCTabContext into a TabContext, you construct a MaybeInvalidTabContext,
 137  * check whether it's valid, and, if so, read out your TabContext.
 138  *
 139  * Example usage:
 140  *
 141  *   void UseTabContext(const TabContext& aTabContext);
 142  *
 143  *   void CreateTab(const IPCTabContext& aContext) {
 144  *     MaybeInvalidTabContext tc(aContext);
 145  *     if (!tc.IsValid()) {
 146  *       NS_ERROR(nsPrintfCString("Got an invalid IPCTabContext: %s",
 147  *                                tc.GetInvalidReason()));
 148  *       return;
 149  *     }
 150  *     UseTabContext(tc.GetTabContext());
 151  *   }
 152  */
 153 class MaybeInvalidTabContext {
 154  public:
 155   /**
 156    * This constructor copies the information in aContext and sets IsValid() as
 157    * appropriate.
 158    */
 159   explicit MaybeInvalidTabContext(const IPCTabContext& aContext);
 160
 161   /**
 162    * Was the IPCTabContext we received in our constructor valid?
 163    */
 164   bool IsValid();
 165
 166   /**
 167    * If IsValid(), this function returns null.  Otherwise, it returns a
 168    * human-readable string indicating why the IPCTabContext passed to our
 169    * constructor was not valid.
 170    */
 171   const char* GetInvalidReason();
 172
 173   /**
 174    * If IsValid(), this function returns a reference to a TabContext
 175    * corresponding to the IPCTabContext passed to our constructor.  If
 176    * !IsValid(), this function crashes.
 177    */
 178   const TabContext& GetTabContext();
 179
 180  private:
 181   MaybeInvalidTabContext(const MaybeInvalidTabContext&) = delete;
 182   MaybeInvalidTabContext& operator=(const MaybeInvalidTabContext&) = delete;
 183
 184   const char* mInvalidReason;
 185   MutableTabContext mTabContext;
 186 };
 187
 188 }  // namespace mozilla::dom
 189
 190 #endif