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