dom/ipc/TabContext.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set sw=2 ts=8 et 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 "mozilla/layout/RenderFrameUtils.h"
  11 #include "mozIApplication.h"
  12 #include "nsCOMPtr.h"
  13
  14 namespace mozilla {
  15 namespace dom {
  16
  17 class IPCTabContext;
  18
  19 /**
  20  * TabContext encapsulates information about an iframe that may be a mozbrowser
  21  * or mozapp.  You can ask whether a TabContext corresponds to a mozbrowser or
  22  * mozapp, get the app that contains the browser, and so on.
  23  *
  24  * TabParent and TabChild both inherit from TabContext, and you can also have
  25  * standalone TabContext objects.
  26  *
  27  * This class is immutable except by calling one of the protected
  28  * SetTabContext*() methods (and those methods can only be called once).  See
  29  * also MutableTabContext.
  30  */
  31 class TabContext
  32 {
  33 protected:
  34   typedef mozilla::layout::ScrollingBehavior ScrollingBehavior;
  35
  36 public:
  37   TabContext();
  38
  39   /* (The implicit copy-constructor and operator= are fine.) */
  40
  41   /**
  42    * Generates IPCTabContext of type BrowserFrameIPCTabContext or
  43    * AppFrameIPCTabContext from this TabContext's information.
  44    */
  45   IPCTabContext AsIPCTabContext() const;
  46
  47   /**
  48    * Does this TabContext correspond to a mozbrowser?  (<iframe mozbrowser
  49    * mozapp> is not a browser.)
  50    *
  51    * If IsBrowserElement() is true, HasOwnApp() and HasAppOwnerApp() are
  52    * guaranteed to be false.
  53    *
  54    * If IsBrowserElement() is false, HasBrowserOwnerApp() is guaranteed to be
  55    * false.
  56    */
  57   bool IsBrowserElement() const;
  58
  59   /**
  60    * Does this TabContext correspond to a mozbrowser or mozapp?  This is
  61    * equivalent to IsBrowserElement() || HasOwnApp().
  62    */
  63   bool IsBrowserOrApp() const;
  64
  65   /**
  66    * OwnAppId() returns the id of the app which directly corresponds to this
  67    * context's frame.  GetOwnApp() returns the corresponding app object, and
  68    * HasOwnApp() returns true iff GetOwnApp() would return a non-null value.
  69    *
  70    * If HasOwnApp() is true, IsBrowserElement() is guaranteed to be false.
  71    */
  72   uint32_t OwnAppId() const;
  73   already_AddRefed<mozIApplication> GetOwnApp() const;
  74   bool HasOwnApp() const;
  75
  76   /**
  77    * BrowserOwnerAppId() gets the ID of the app which contains this browser
  78    * frame.  If this is not a browser frame (i.e., if !IsBrowserElement()), then
  79    * BrowserOwnerAppId() is guaranteed to return NO_APP_ID.
  80    *
  81    * Even if we are a browser frame, BrowserOwnerAppId() may still return
  82    * NO_APP_ID, if this browser frame is not contained inside an app.
  83    */
  84   uint32_t BrowserOwnerAppId() const;
  85   already_AddRefed<mozIApplication> GetBrowserOwnerApp() const;
  86   bool HasBrowserOwnerApp() const;
  87
  88   /**
  89    * AppOwnerAppId() gets the ID of the app which contains this app frame.  If
  90    * this is not an app frame (i.e., if !HasOwnApp()), then AppOwnerAppId() is
  91    * guaranteed to return NO_APP_ID.
  92    *
  93    * Even if we are an app frame, AppOwnerAppId() may still return NO_APP_ID, if
  94    * this app frame is not contained inside an app.
  95    */
  96   uint32_t AppOwnerAppId() const;
  97   already_AddRefed<mozIApplication> GetAppOwnerApp() const;
  98   bool HasAppOwnerApp() const;
  99
 100   /**
 101    * OwnOrContainingAppId() gets the ID of this frame, if HasOwnApp().  If this
 102    * frame does not have its own app, it gets the ID of the app which contains
 103    * this frame (i.e., the result of {Browser,App}OwnerAppId(), as applicable).
 104    */
 105   uint32_t OwnOrContainingAppId() const;
 106   already_AddRefed<mozIApplication> GetOwnOrContainingApp() const;
 107   bool HasOwnOrContainingApp() const;
 108
 109   /**
 110    * Return the requested scrolling behavior for this frame.
 111    */
 112   ScrollingBehavior GetScrollingBehavior() const { return mScrollingBehavior; }
 113
 114 protected:
 115   friend class MaybeInvalidTabContext;
 116
 117   /**
 118    * These protected mutator methods let you modify a TabContext once.  Further
 119    * attempts to modify a given TabContext will fail (the method will return
 120    * false).
 121    *
 122    * These mutators will also fail if the TabContext was created with anything
 123    * other than the no-args constructor.
 124    */
 125
 126   /**
 127    * Set this TabContext to match the given TabContext.
 128    */
 129   bool SetTabContext(const TabContext& aContext);
 130
 131   /**
 132    * Set this TabContext to be an app frame (with the given own app) inside the
 133    * given app.  Either or both apps may be null.
 134    */
 135   bool SetTabContextForAppFrame(mozIApplication* aOwnApp,
 136                                 mozIApplication* aAppFrameOwnerApp,
 137                                 ScrollingBehavior aRequestedBehavior);
 138
 139   /**
 140    * Set this TabContext to be a browser frame inside the given app (which may
 141    * be null).
 142    */
 143   bool SetTabContextForBrowserFrame(mozIApplication* aBrowserFrameOwnerApp,
 144                                     ScrollingBehavior aRequestedBehavior);
 145
 146   /**
 147    * Set this TabContext to be a normal non-browser non-app frame.
 148    */
 149   bool SetTabContextForNormalFrame(ScrollingBehavior aRequestedBehavior);
 150
 151 private:
 152   /**
 153    * Has this TabContext been initialized?  If so, mutator methods will fail.
 154    */
 155   bool mInitialized;
 156
 157   /**
 158    * This TabContext's own app.  If this is non-null, then this
 159    * TabContext corresponds to an app, and mIsBrowser must be false.
 160    */
 161   nsCOMPtr<mozIApplication> mOwnApp;
 162
 163   /**
 164    * A cache of mOwnApp->GetLocalId().  Speed really does matter here, since we
 165    * read this ID often during process startup.
 166    */
 167   uint32_t mOwnAppId;
 168
 169   /**
 170    * This TabContext's containing app.  If mIsBrowser, this corresponds to the
 171    * app which contains the browser frame; otherwise, this corresponds to the
 172    * app which contains the app frame.
 173    */
 174   nsCOMPtr<mozIApplication> mContainingApp;
 175
 176   /*
 177    * Cache of mContainingApp->GetLocalId().
 178    */
 179   uint32_t mContainingAppId;
 180
 181   /**
 182    * The requested scrolling behavior for this frame.
 183    */
 184   ScrollingBehavior mScrollingBehavior;
 185
 186   /**
 187    * Does this TabContext correspond to a browser element?
 188    *
 189    * If this is true, mOwnApp must be null.
 190    */
 191   bool mIsBrowser;
 192 };
 193
 194 /**
 195  * MutableTabContext is the same as MaybeInvalidTabContext, except the mutation
 196  * methods are public instead of protected.  You can still only call these
 197  * mutation methods once on a given object.
 198  */
 199 class MutableTabContext : public TabContext
 200 {
 201 public:
 202   bool SetTabContext(const TabContext& aContext)
 203   {
 204     return TabContext::SetTabContext(aContext);
 205   }
 206
 207   bool SetTabContextForAppFrame(mozIApplication* aOwnApp, mozIApplication* aAppFrameOwnerApp,
 208                                 ScrollingBehavior aRequestedBehavior)
 209   {
 210     return TabContext::SetTabContextForAppFrame(aOwnApp, aAppFrameOwnerApp,
 211                                                 aRequestedBehavior);
 212   }
 213
 214   bool SetTabContextForBrowserFrame(mozIApplication* aBrowserFrameOwnerApp,
 215                                     ScrollingBehavior aRequestedBehavior)
 216   {
 217     return TabContext::SetTabContextForBrowserFrame(aBrowserFrameOwnerApp,
 218                                                     aRequestedBehavior);
 219   }
 220
 221   bool SetTabContextForNormalFrame(ScrollingBehavior aRequestedBehavior)
 222   {
 223     return TabContext::SetTabContextForNormalFrame(aRequestedBehavior);
 224   }
 225 };
 226
 227 /**
 228  * MaybeInvalidTabContext is a simple class that lets you transform an
 229  * IPCTabContext into a TabContext.
 230  *
 231  * The issue is that an IPCTabContext is not necessarily valid; for example, it
 232  * might specify an app-id which doesn't exist.  So to convert an IPCTabContext
 233  * into a TabContext, you construct a MaybeInvalidTabContext, check whether it's
 234  * valid, and, if so, read out your TabContext.
 235  *
 236  * Example usage:
 237  *
 238  *   void UseTabContext(const TabContext& aTabContext);
 239  *
 240  *   void CreateTab(const IPCTabContext& aContext) {
 241  *     MaybeInvalidTabContext tc(aContext);
 242  *     if (!tc.IsValid()) {
 243  *       NS_ERROR(nsPrintfCString("Got an invalid IPCTabContext: %s",
 244  *                                tc.GetInvalidReason()));
 245  *       return;
 246  *     }
 247  *     UseTabContext(tc.GetTabContext());
 248  *   }
 249  */
 250 class MaybeInvalidTabContext
 251 {
 252 public:
 253   /**
 254    * This constructor copies the information in aContext and sets IsValid() as
 255    * appropriate.
 256    */
 257   explicit MaybeInvalidTabContext(const IPCTabContext& aContext);
 258
 259   /**
 260    * Was the IPCTabContext we received in our constructor valid?
 261    */
 262   bool IsValid();
 263
 264   /**
 265    * If IsValid(), this function returns null.  Otherwise, it returns a
 266    * human-readable string indicating why the IPCTabContext passed to our
 267    * constructor was not valid.
 268    */
 269   const char* GetInvalidReason();
 270
 271   /**
 272    * If IsValid(), this function returns a reference to a TabContext
 273    * corresponding to the IPCTabContext passed to our constructor.  If
 274    * !IsValid(), this function crashes.
 275    */
 276   const TabContext& GetTabContext();
 277
 278 private:
 279   MaybeInvalidTabContext(const MaybeInvalidTabContext&) MOZ_DELETE;
 280   MaybeInvalidTabContext& operator=(const MaybeInvalidTabContext&) MOZ_DELETE;
 281
 282   const char* mInvalidReason;
 283   MutableTabContext mTabContext;
 284 };
 285
 286 } // namespace dom
 287 } // namespace mozilla
 288
 289 #endif