1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/ipc/TabContext.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,289 @@
1.4 +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim: set sw=2 ts=8 et tw=80 : */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#ifndef mozilla_dom_TabContext_h
1.11 +#define mozilla_dom_TabContext_h
1.12 +
1.13 +#include "mozilla/layout/RenderFrameUtils.h"
1.14 +#include "mozIApplication.h"
1.15 +#include "nsCOMPtr.h"
1.16 +
1.17 +namespace mozilla {
1.18 +namespace dom {
1.19 +
1.20 +struct IPCTabContext;
1.21 +
1.22 +/**
1.23 + * TabContext encapsulates information about an iframe that may be a mozbrowser
1.24 + * or mozapp. You can ask whether a TabContext corresponds to a mozbrowser or
1.25 + * mozapp, get the app that contains the browser, and so on.
1.26 + *
1.27 + * TabParent and TabChild both inherit from TabContext, and you can also have
1.28 + * standalone TabContext objects.
1.29 + *
1.30 + * This class is immutable except by calling one of the protected
1.31 + * SetTabContext*() methods (and those methods can only be called once). See
1.32 + * also MutableTabContext.
1.33 + */
1.34 +class TabContext
1.35 +{
1.36 +protected:
1.37 + typedef mozilla::layout::ScrollingBehavior ScrollingBehavior;
1.38 +
1.39 +public:
1.40 + TabContext();
1.41 +
1.42 + /* (The implicit copy-constructor and operator= are fine.) */
1.43 +
1.44 + /**
1.45 + * Generates IPCTabContext of type BrowserFrameIPCTabContext or
1.46 + * AppFrameIPCTabContext from this TabContext's information.
1.47 + */
1.48 + IPCTabContext AsIPCTabContext() const;
1.49 +
1.50 + /**
1.51 + * Does this TabContext correspond to a mozbrowser? (<iframe mozbrowser
1.52 + * mozapp> is not a browser.)
1.53 + *
1.54 + * If IsBrowserElement() is true, HasOwnApp() and HasAppOwnerApp() are
1.55 + * guaranteed to be false.
1.56 + *
1.57 + * If IsBrowserElement() is false, HasBrowserOwnerApp() is guaranteed to be
1.58 + * false.
1.59 + */
1.60 + bool IsBrowserElement() const;
1.61 +
1.62 + /**
1.63 + * Does this TabContext correspond to a mozbrowser or mozapp? This is
1.64 + * equivalent to IsBrowserElement() || HasOwnApp().
1.65 + */
1.66 + bool IsBrowserOrApp() const;
1.67 +
1.68 + /**
1.69 + * OwnAppId() returns the id of the app which directly corresponds to this
1.70 + * context's frame. GetOwnApp() returns the corresponding app object, and
1.71 + * HasOwnApp() returns true iff GetOwnApp() would return a non-null value.
1.72 + *
1.73 + * If HasOwnApp() is true, IsBrowserElement() is guaranteed to be false.
1.74 + */
1.75 + uint32_t OwnAppId() const;
1.76 + already_AddRefed<mozIApplication> GetOwnApp() const;
1.77 + bool HasOwnApp() const;
1.78 +
1.79 + /**
1.80 + * BrowserOwnerAppId() gets the ID of the app which contains this browser
1.81 + * frame. If this is not a browser frame (i.e., if !IsBrowserElement()), then
1.82 + * BrowserOwnerAppId() is guaranteed to return NO_APP_ID.
1.83 + *
1.84 + * Even if we are a browser frame, BrowserOwnerAppId() may still return
1.85 + * NO_APP_ID, if this browser frame is not contained inside an app.
1.86 + */
1.87 + uint32_t BrowserOwnerAppId() const;
1.88 + already_AddRefed<mozIApplication> GetBrowserOwnerApp() const;
1.89 + bool HasBrowserOwnerApp() const;
1.90 +
1.91 + /**
1.92 + * AppOwnerAppId() gets the ID of the app which contains this app frame. If
1.93 + * this is not an app frame (i.e., if !HasOwnApp()), then AppOwnerAppId() is
1.94 + * guaranteed to return NO_APP_ID.
1.95 + *
1.96 + * Even if we are an app frame, AppOwnerAppId() may still return NO_APP_ID, if
1.97 + * this app frame is not contained inside an app.
1.98 + */
1.99 + uint32_t AppOwnerAppId() const;
1.100 + already_AddRefed<mozIApplication> GetAppOwnerApp() const;
1.101 + bool HasAppOwnerApp() const;
1.102 +
1.103 + /**
1.104 + * OwnOrContainingAppId() gets the ID of this frame, if HasOwnApp(). If this
1.105 + * frame does not have its own app, it gets the ID of the app which contains
1.106 + * this frame (i.e., the result of {Browser,App}OwnerAppId(), as applicable).
1.107 + */
1.108 + uint32_t OwnOrContainingAppId() const;
1.109 + already_AddRefed<mozIApplication> GetOwnOrContainingApp() const;
1.110 + bool HasOwnOrContainingApp() const;
1.111 +
1.112 + /**
1.113 + * Return the requested scrolling behavior for this frame.
1.114 + */
1.115 + ScrollingBehavior GetScrollingBehavior() const { return mScrollingBehavior; }
1.116 +
1.117 +protected:
1.118 + friend class MaybeInvalidTabContext;
1.119 +
1.120 + /**
1.121 + * These protected mutator methods let you modify a TabContext once. Further
1.122 + * attempts to modify a given TabContext will fail (the method will return
1.123 + * false).
1.124 + *
1.125 + * These mutators will also fail if the TabContext was created with anything
1.126 + * other than the no-args constructor.
1.127 + */
1.128 +
1.129 + /**
1.130 + * Set this TabContext to match the given TabContext.
1.131 + */
1.132 + bool SetTabContext(const TabContext& aContext);
1.133 +
1.134 + /**
1.135 + * Set this TabContext to be an app frame (with the given own app) inside the
1.136 + * given app. Either or both apps may be null.
1.137 + */
1.138 + bool SetTabContextForAppFrame(mozIApplication* aOwnApp,
1.139 + mozIApplication* aAppFrameOwnerApp,
1.140 + ScrollingBehavior aRequestedBehavior);
1.141 +
1.142 + /**
1.143 + * Set this TabContext to be a browser frame inside the given app (which may
1.144 + * be null).
1.145 + */
1.146 + bool SetTabContextForBrowserFrame(mozIApplication* aBrowserFrameOwnerApp,
1.147 + ScrollingBehavior aRequestedBehavior);
1.148 +
1.149 + /**
1.150 + * Set this TabContext to be a normal non-browser non-app frame.
1.151 + */
1.152 + bool SetTabContextForNormalFrame(ScrollingBehavior aRequestedBehavior);
1.153 +
1.154 +private:
1.155 + /**
1.156 + * Has this TabContext been initialized? If so, mutator methods will fail.
1.157 + */
1.158 + bool mInitialized;
1.159 +
1.160 + /**
1.161 + * This TabContext's own app. If this is non-null, then this
1.162 + * TabContext corresponds to an app, and mIsBrowser must be false.
1.163 + */
1.164 + nsCOMPtr<mozIApplication> mOwnApp;
1.165 +
1.166 + /**
1.167 + * A cache of mOwnApp->GetLocalId(). Speed really does matter here, since we
1.168 + * read this ID often during process startup.
1.169 + */
1.170 + uint32_t mOwnAppId;
1.171 +
1.172 + /**
1.173 + * This TabContext's containing app. If mIsBrowser, this corresponds to the
1.174 + * app which contains the browser frame; otherwise, this corresponds to the
1.175 + * app which contains the app frame.
1.176 + */
1.177 + nsCOMPtr<mozIApplication> mContainingApp;
1.178 +
1.179 + /*
1.180 + * Cache of mContainingApp->GetLocalId().
1.181 + */
1.182 + uint32_t mContainingAppId;
1.183 +
1.184 + /**
1.185 + * The requested scrolling behavior for this frame.
1.186 + */
1.187 + ScrollingBehavior mScrollingBehavior;
1.188 +
1.189 + /**
1.190 + * Does this TabContext correspond to a browser element?
1.191 + *
1.192 + * If this is true, mOwnApp must be null.
1.193 + */
1.194 + bool mIsBrowser;
1.195 +};
1.196 +
1.197 +/**
1.198 + * MutableTabContext is the same as MaybeInvalidTabContext, except the mutation
1.199 + * methods are public instead of protected. You can still only call these
1.200 + * mutation methods once on a given object.
1.201 + */
1.202 +class MutableTabContext : public TabContext
1.203 +{
1.204 +public:
1.205 + bool SetTabContext(const TabContext& aContext)
1.206 + {
1.207 + return TabContext::SetTabContext(aContext);
1.208 + }
1.209 +
1.210 + bool SetTabContextForAppFrame(mozIApplication* aOwnApp, mozIApplication* aAppFrameOwnerApp,
1.211 + ScrollingBehavior aRequestedBehavior)
1.212 + {
1.213 + return TabContext::SetTabContextForAppFrame(aOwnApp, aAppFrameOwnerApp,
1.214 + aRequestedBehavior);
1.215 + }
1.216 +
1.217 + bool SetTabContextForBrowserFrame(mozIApplication* aBrowserFrameOwnerApp,
1.218 + ScrollingBehavior aRequestedBehavior)
1.219 + {
1.220 + return TabContext::SetTabContextForBrowserFrame(aBrowserFrameOwnerApp,
1.221 + aRequestedBehavior);
1.222 + }
1.223 +
1.224 + bool SetTabContextForNormalFrame(ScrollingBehavior aRequestedBehavior)
1.225 + {
1.226 + return TabContext::SetTabContextForNormalFrame(aRequestedBehavior);
1.227 + }
1.228 +};
1.229 +
1.230 +/**
1.231 + * MaybeInvalidTabContext is a simple class that lets you transform an
1.232 + * IPCTabContext into a TabContext.
1.233 + *
1.234 + * The issue is that an IPCTabContext is not necessarily valid; for example, it
1.235 + * might specify an app-id which doesn't exist. So to convert an IPCTabContext
1.236 + * into a TabContext, you construct a MaybeInvalidTabContext, check whether it's
1.237 + * valid, and, if so, read out your TabContext.
1.238 + *
1.239 + * Example usage:
1.240 + *
1.241 + * void UseTabContext(const TabContext& aTabContext);
1.242 + *
1.243 + * void CreateTab(const IPCTabContext& aContext) {
1.244 + * MaybeInvalidTabContext tc(aContext);
1.245 + * if (!tc.IsValid()) {
1.246 + * NS_ERROR(nsPrintfCString("Got an invalid IPCTabContext: %s",
1.247 + * tc.GetInvalidReason()));
1.248 + * return;
1.249 + * }
1.250 + * UseTabContext(tc.GetTabContext());
1.251 + * }
1.252 + */
1.253 +class MaybeInvalidTabContext
1.254 +{
1.255 +public:
1.256 + /**
1.257 + * This constructor copies the information in aContext and sets IsValid() as
1.258 + * appropriate.
1.259 + */
1.260 + MaybeInvalidTabContext(const IPCTabContext& aContext);
1.261 +
1.262 + /**
1.263 + * Was the IPCTabContext we received in our constructor valid?
1.264 + */
1.265 + bool IsValid();
1.266 +
1.267 + /**
1.268 + * If IsValid(), this function returns null. Otherwise, it returns a
1.269 + * human-readable string indicating why the IPCTabContext passed to our
1.270 + * constructor was not valid.
1.271 + */
1.272 + const char* GetInvalidReason();
1.273 +
1.274 + /**
1.275 + * If IsValid(), this function returns a reference to a TabContext
1.276 + * corresponding to the IPCTabContext passed to our constructor. If
1.277 + * !IsValid(), this function crashes.
1.278 + */
1.279 + const TabContext& GetTabContext();
1.280 +
1.281 +private:
1.282 + MaybeInvalidTabContext(const MaybeInvalidTabContext&) MOZ_DELETE;
1.283 + MaybeInvalidTabContext& operator=(const MaybeInvalidTabContext&) MOZ_DELETE;
1.284 +
1.285 + const char* mInvalidReason;
1.286 + MutableTabContext mTabContext;
1.287 +};
1.288 +
1.289 +} // namespace dom
1.290 +} // namespace mozilla
1.291 +
1.292 +#endif
