third_party/WebKit/Source/core/frame/Frame.h

/*
 * Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
 *                     1999-2001 Lars Knoll <knoll@kde.org>
 *                     1999-2001 Antti Koivisto <koivisto@kde.org>
 *                     2000-2001 Simon Hausmann <hausmann@kde.org>
 *                     2000-2001 Dirk Mueller <mueller@kde.org>
 *                     2000 Stefan Schimanski <1Stein@gmx.de>
 * Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Apple Inc. All rights
 * reserved.
 * Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies)
 * Copyright (C) 2008 Eric Seidel <eric@webkit.org>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 */

#ifndef Frame_h
#define Frame_h

#include "base/unguessable_token.h"
#include "core/CoreExport.h"
#include "core/dom/UserGestureIndicator.h"
#include "core/frame/FrameLifecycle.h"
#include "core/frame/FrameTypes.h"
#include "core/frame/FrameView.h"
#include "core/frame/UserActivationState.h"
#include "core/loader/FrameLoaderTypes.h"
#include "core/page/FrameTree.h"
#include "platform/heap/Handle.h"
#include "platform/wtf/Forward.h"
#include "third_party/WebKit/common/feature_policy/feature_policy.h"

namespace blink {

class ChromeClient;
class DOMWindow;
class DOMWrapperWorld;
class Document;
class FrameClient;
class FrameOwner;
class HTMLFrameOwnerElement;
class LayoutEmbeddedContent;
class LocalFrame;
class KURL;
class Page;
class SecurityContext;
class Settings;
class WindowProxy;
class WindowProxyManager;
struct FrameLoadRequest;

enum class FrameDetachType { kRemove, kSwap };

// Status of user gesture.
enum class UserGestureStatus { kActive, kNone };

// Frame is the base class of LocalFrame and RemoteFrame and should only contain
// functionality shared between both. In particular, any method related to
// input, layout, or painting probably belongs on LocalFrame.
class CORE_EXPORT Frame : public GarbageCollectedFinalized<Frame> {
 public:
  virtual ~Frame();

  virtual void Trace(blink::Visitor*);

  virtual bool IsLocalFrame() const = 0;
  virtual bool IsRemoteFrame() const = 0;

  virtual void Navigate(Document& origin_document,
                        const KURL&,
                        bool replace_current_item,
                        UserGestureStatus) = 0;
  // This version of Frame::navigate assumes the resulting navigation is not
  // to be started on a timer. Use the method above in such cases.
  virtual void Navigate(const FrameLoadRequest&) = 0;
  virtual void Reload(FrameLoadType, ClientRedirectPolicy) = 0;

  virtual void Detach(FrameDetachType);
  void DisconnectOwnerElement();
  virtual bool ShouldClose() = 0;
  virtual void DidFreeze() = 0;
  virtual void DidResume() = 0;

  FrameClient* Client() const;

  Page* GetPage() const;  // Null when the frame is detached.
  virtual FrameView* View() const = 0;

  bool IsMainFrame() const;
  bool IsLocalRoot() const;

  FrameOwner* Owner() const;
  void SetOwner(FrameOwner*);
  HTMLFrameOwnerElement* DeprecatedLocalOwner() const;

  DOMWindow* DomWindow() const { return dom_window_; }

  FrameTree& Tree() const;
  ChromeClient& GetChromeClient() const;

  virtual SecurityContext* GetSecurityContext() const = 0;

  Frame* FindUnsafeParentScrollPropagationBoundary();

  // This prepares the Frame for the next commit. It will detach children,
  // dispatch unload events, abort XHR requests and detach the document.
  // Returns true if the frame is ready to receive the next commit, or false
  // otherwise.
  virtual bool PrepareForCommit() = 0;

  // LayoutObject for the element that contains this frame.
  LayoutEmbeddedContent* OwnerLayoutObject() const;

  Settings* GetSettings() const;  // can be null

  // isLoading() is true when the embedder should think a load is in progress.
  // In the case of LocalFrames, it means that the frame has sent a
  // didStartLoading() callback, but not the matching didStopLoading(). Inside
  // blink, you probably want Document::loadEventFinished() instead.
  void SetIsLoading(bool is_loading) { is_loading_ = is_loading; }
  bool IsLoading() const { return is_loading_; }

  WindowProxyManager* GetWindowProxyManager() const {
    return window_proxy_manager_;
  }
  WindowProxy* GetWindowProxy(DOMWrapperWorld&);

  virtual void DidChangeVisibilityState();

  void UpdateUserActivationInFrameTree();

  bool HasBeenActivated() const {
    return user_activation_state_.HasBeenActive();
  }

  void ClearActivation() { user_activation_state_.Clear(); }

  void SetDocumentHasReceivedUserGestureBeforeNavigation(bool value) {
    has_received_user_gesture_before_nav_ = value;
  }

  bool HasReceivedUserGestureBeforeNavigation() const {
    return has_received_user_gesture_before_nav_;
  }

  // Creates a |UserGestureIndicator| that contains a |UserGestureToken| with
  // the given status.  Also activates the user activation state of the
  // |LocalFrame| (provided it's non-null) and all its ancestors.
  static std::unique_ptr<UserGestureIndicator> NotifyUserActivation(
      Frame*,
      UserGestureToken::Status = UserGestureToken::kPossiblyExistingGesture);

  // Returns the transient user activation state of the |LocalFrame|, provided
  // it is non-null.  Otherwise returns |false|.
  //
  // The |checkIfMainThread| parameter determines if the token based gestures
  // (legacy code) must be used in a thread-safe manner.
  //
  // TODO(mustaq): clarify/enforce the relation between the two params after
  // null-frame main-thread cases (crbug.com/730690) have been removed.
  static bool HasTransientUserActivation(Frame*,
                                         bool checkIfMainThread = false);

  // Consumes the transient user activation state of the |LocalFrame|, provided
  // the frame pointer is non-null and the state hasn't been consumed since
  // activation.  Returns |true| if succesfully consumed the state.
  //
  // The |checkIfMainThread| parameter determines if the token based gestures
  // (legacy code) must be used in a thread-safe manner.
  static bool ConsumeTransientUserActivation(Frame*,
                                             bool checkIfMainThread = false);

  bool IsAttached() const {
    return lifecycle_.GetState() == FrameLifecycle::kAttached;
  }

  // Tests whether the feature-policy controlled feature is enabled by policy in
  // the given frame.
  bool IsFeatureEnabled(FeaturePolicyFeature) const;

  // Called to make a frame inert or non-inert. A frame is inert when there
  // is a modal dialog displayed within an ancestor frame, and this frame
  // itself is not within the dialog.
  virtual void SetIsInert(bool) = 0;
  void UpdateInertIfPossible();

  const base::UnguessableToken& GetDevToolsFrameToken() const {
    return devtools_frame_token_;
  }

 protected:
  Frame(FrameClient*, Page&, FrameOwner*, WindowProxyManager*);

  mutable FrameTree tree_node_;

  Member<Page> page_;
  Member<FrameOwner> owner_;
  Member<DOMWindow> dom_window_;

  UserActivationState user_activation_state_;
  bool has_received_user_gesture_before_nav_ = false;

  FrameLifecycle lifecycle_;

  // This is set to true if this is a subframe, and the frame element in the
  // parent frame's document becomes inert. This should always be false for
  // the main frame.
  bool is_inert_ = false;

 private:
  // Activates the user activation state of this frame and all its ancestors.
  void NotifyUserActivation();

  bool HasTransientUserActivation() {
    return user_activation_state_.IsActive();
  }

  // Consumes and returns the transient user activation of current Frame, after
  // updating all ancestor/descendant frames.
  bool ConsumeTransientUserActivation();

  Member<FrameClient> client_;
  const Member<WindowProxyManager> window_proxy_manager_;
  // TODO(sashab): Investigate if this can be represented with m_lifecycle.
  bool is_loading_;
  base::UnguessableToken devtools_frame_token_;
};

inline FrameClient* Frame::Client() const {
  return client_;
}

inline FrameOwner* Frame::Owner() const {
  return owner_;
}

inline FrameTree& Frame::Tree() const {
  return tree_node_;
}

// Allow equality comparisons of Frames by reference or pointer,
// interchangeably.
DEFINE_COMPARISON_OPERATORS_WITH_REFERENCES(Frame)

}  // namespace blink

#endif  // Frame_h