text: // Copyright 2021 The Chromium Authors. All rights reserved.
  // Use of this source code is governed by a BSD-style license that can be
  // found in the LICENSE file.
  
  #ifndef CONTENT_PUBLIC_BROWSER_PAGE_H_
  #define CONTENT_PUBLIC_BROWSER_PAGE_H_
  
  #include "base/callback.h"
  #include "base/supports_user_data.h"
  #include "content/common/content_export.h"
  #include "content/public/browser/render_frame_host.h"
  #include "third_party/abseil-cpp/absl/types/optional.h"
  #include "third_party/blink/public/mojom/manifest/manifest.mojom-forward.h"
  #include "third_party/perfetto/include/perfetto/tracing/traced_value_forward.h"
  #include "url/gurl.h"
  
  namespace content {
  
  // Page represents a collection of documents with the same main document.
  
  // At the moment some navigations might create a new blink::Document in the
  // existing RenderFrameHost, which will lead to a creation of a new Page
  // associated with the same main RenderFrameHost. See the comment in
  // |DocumentUserData| for more details and crbug.com/936696 for the
  // progress on always creating a new RenderFrameHost for each new document.
  
  // Page is created when a main document is created, which can happen in the
  // following ways:
  // 1) Main RenderFrameHost is created.
  // 2) A cross-document non-bfcached navigation is committed in the same
  //    RenderFrameHost.
  // 3) Main RenderFrameHost is re-created after crash.
  
  // Page is deleted in the following cases:
  // 1) Main RenderFrameHost is deleted.
  // 2) A cross-document non-bfcached navigation is committed in the same
  //    RenderFrameHost.
  // 3) Before main RenderFrameHost is re-created after crash.
  
  // If a method can be called only for main RenderFrameHosts or if its behaviour
  // is identical when called on the parent / child RenderFrameHosts, it should
  // be added to Page(Impl).
  
  // With Multiple Page Architecture (MPArch), each WebContents may have
  // additional FrameTrees which will have their own associated Page. Please take
  // into consideration when assuming that Page is appropriate for storing
  // something that's common for all frames you see on a tab.
  
  // NOTE: Depending on the process model, the cross-origin iframes are likely to
  // be hosted in a different renderer process than the main document, so a given
  // page is hosted in multiple renderer processes at the same time.
  // RenderViewHost / RenderView / blink::Page (which are all 1:1:1) represent a
  // part of a given content::Page in a given renderer process (note, however,
  // that like RenderFrameHosts, these objects at the moment can be reused for a
  // new content::Page for a cross-document same-site main-frame navigation).
  class CONTENT_EXPORT Page : public base::SupportsUserData {
   public:
    ~Page() override = default;
  
    // The GURL for the page's web application manifest.
    // See https://w3c.github.io/manifest/#web-application-manifest
    virtual const absl::optional<GURL>& GetManifestUrl() const = 0;
  
    // The callback invoked when the renderer responds to a request for the main
    // frame document's manifest. The url will be empty if the document specifies
    // no manifest, and the manifest will be empty if any other failures occurred.
    using GetManifestCallback =
        base::OnceCallback<void(const GURL&, blink::mojom::ManifestPtr)>;
  
    // Requests the manifest URL and the Manifest of the main frame's document.
    virtual void GetManifest(GetManifestCallback callback) = 0;
  
    // Returns true iff this Page is primary for the associated `WebContents`
    // (i.e. web_contents->GetPrimaryPage() == this_page). Non-primary pages
    // include pages in bfcache, portal, prerendering, fenced frames, pending
    // commit and pending deletion pages. See WebContents::GetPrimaryPage for more
    // details.
    virtual bool IsPrimary() = 0;
  
    // Returns the main RenderFrameHost associated with this Page.
    RenderFrameHost& GetMainDocument() { return GetMainDocumentHelper(); }
  
    // Write a description of this Page into the provided |context|.
    virtual void WriteIntoTrace(perfetto::TracedValue context) = 0;
  
    virtual base::WeakPtr<Page> GetWeakPtr() = 0;
  
    // Whether the most recent page scale factor sent by the main frame's renderer
    // is 1 (i.e. no magnification).
    virtual bool IsPageScaleFactorOne() = 0;
  
   private:
    // This method is needed to ensure that PageImpl can both implement a Page's
    // method and define a new GetMainDocument() returning RenderFrameHostImpl.
    // Covariant types can't be used here due to circular includes as
    // RenderFrameHost::GetPage and RenderFrameHostImpl::GetPage already return
    // Page& and PageImpl& respectively, which means that page_impl.h can't
    // include render_frame_host_impl.h.
    virtual RenderFrameHost& GetMainDocumentHelper() = 0;
  
    // This interface should only be implemented inside content.
    friend class PageImpl;
    Page() = default;
  };
  
  }  // namespace content
  
  #endif  // CONTENT_PUBLIC_BROWSER_PAGE_H_
  