blob: d821defb3304d476dbca602a89e911416d2ddb12 [file] [log] [blame]
* Copyright (C) 2011, 2012 Google Inc. All rights reserved.
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following disclaimer
* in the documentation and/or other materials provided with the
* distribution.
* * Neither the name of Google Inc. nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
#include <memory>
#include "base/i18n/rtl.h"
#include "base/unguessable_token.h"
#include "mojo/public/cpp/bindings/scoped_interface_endpoint_handle.h"
#include "third_party/blink/public/common/feature_policy/feature_policy.h"
#include "third_party/blink/public/common/frame/frame_owner_element_type.h"
#include "third_party/blink/public/common/frame/sandbox_flags.h"
#include "third_party/blink/public/common/loader/loading_behavior_flag.h"
#include "third_party/blink/public/common/loader/url_loader_factory_bundle.h"
#include "third_party/blink/public/common/navigation/triggering_event_info.h"
#include "third_party/blink/public/mojom/frame/blocked_navigation_types.mojom-shared.h"
#include "third_party/blink/public/mojom/frame/lifecycle.mojom-shared.h"
#include "third_party/blink/public/mojom/frame/user_activation_update_types.mojom-shared.h"
#include "third_party/blink/public/mojom/use_counter/css_property_id.mojom-shared.h"
#include "third_party/blink/public/platform/blame_context.h"
#include "third_party/blink/public/platform/modules/service_worker/web_service_worker_provider.h"
#include "third_party/blink/public/platform/web_common.h"
#include "third_party/blink/public/platform/web_content_security_policy_struct.h"
#include "third_party/blink/public/platform/web_content_settings_client.h"
#include "third_party/blink/public/platform/web_effective_connection_type.h"
#include "third_party/blink/public/platform/web_file_system_type.h"
#include "third_party/blink/public/platform/web_prescient_networking.h"
#include "third_party/blink/public/platform/web_set_sink_id_callbacks.h"
#include "third_party/blink/public/platform/web_source_location.h"
#include "third_party/blink/public/platform/web_url_error.h"
#include "third_party/blink/public/platform/web_url_loader_factory.h"
#include "third_party/blink/public/platform/web_url_request.h"
#include "third_party/blink/public/platform/web_worker_fetch_context.h"
#include "third_party/blink/public/web/web_ax_object.h"
#include "third_party/blink/public/web/web_document_loader.h"
#include "third_party/blink/public/web/web_dom_message_event.h"
#include "third_party/blink/public/web/web_form_element.h"
#include "third_party/blink/public/web/web_frame.h"
#include "third_party/blink/public/web/web_frame_load_type.h"
#include "third_party/blink/public/web/web_frame_owner_properties.h"
#include "third_party/blink/public/web/web_history_commit_type.h"
#include "third_party/blink/public/web/web_history_item.h"
#include "third_party/blink/public/web/web_media_inspector.h"
#include "third_party/blink/public/web/web_navigation_params.h"
#include "third_party/blink/public/web/web_navigation_policy.h"
#include "third_party/blink/public/web/web_navigation_type.h"
#include "ui/accessibility/ax_enums.mojom-shared.h"
#include "ui/events/types/scroll_types.h"
#include "v8/include/v8.h"
namespace blink {
namespace mojom {
enum class WebFeature : int32_t;
} // namespace mojom
enum class WebTreeScopeType;
class AssociatedInterfaceProvider;
class BrowserInterfaceBrokerProxy;
class WebComputedAXTree;
class WebContentDecryptionModule;
class WebDedicatedWorkerHostFactoryClient;
class WebDocumentLoader;
class WebEncryptedMediaClient;
class WebExternalPopupMenu;
class WebExternalPopupMenuClient;
class WebLocalFrame;
class WebMediaPlayer;
class WebMediaPlayerClient;
class WebMediaPlayerEncryptedMediaClient;
class WebMediaPlayerSource;
class WebMediaStreamDeviceObserver;
class WebNavigationControl;
class WebPlugin;
class WebPrescientNetworking;
class WebRelatedAppsFetcher;
class WebServiceWorkerProvider;
class WebSocketHandshakeThrottle;
class WebString;
class WebURL;
class WebURLResponse;
struct FramePolicy;
struct WebConsoleMessage;
struct WebContextMenuData;
struct WebPluginParams;
struct WebPopupMenuInfo;
struct WebRect;
class BLINK_EXPORT WebLocalFrameClient {
virtual ~WebLocalFrameClient() = default;
// Initialization ------------------------------------------------------
// Called exactly once during construction to notify the client about the
// created WebLocalFrame. Guaranteed to be invoked before any other
// WebLocalFrameClient callbacks. Note this takes WebNavigationControl
// to give the client full control over frame's navigation.
virtual void BindToFrame(WebNavigationControl*) {}
// Factory methods -----------------------------------------------------
// May return null.
virtual WebPlugin* CreatePlugin(const WebPluginParams&) { return nullptr; }
// May return null.
// WebContentDecryptionModule* may be null if one has not yet been set.
virtual WebMediaPlayer* CreateMediaPlayer(const WebMediaPlayerSource&,
const WebString& sink_id) {
return nullptr;
// May return null.
virtual std::unique_ptr<WebServiceWorkerProvider>
CreateServiceWorkerProvider() {
return nullptr;
// May return null.
virtual std::unique_ptr<WebContentSettingsClient>
CreateWorkerContentSettingsClient() {
return nullptr;
// Returns a new WebWorkerFetchContext for a dedicated worker (in the
// non-PlzDedicatedWorker case) or worklet.
virtual scoped_refptr<WebWorkerFetchContext> CreateWorkerFetchContext() {
return nullptr;
// Returns a new WebWorkerFetchContext for PlzDedicatedWorker.
// (
virtual scoped_refptr<WebWorkerFetchContext>
WebDedicatedWorkerHostFactoryClient*) {
return nullptr;
// Create a new WebPopupMenu. In the "createExternalPopupMenu" form, the
// client is responsible for rendering the contents of the popup menu.
virtual WebExternalPopupMenu* CreateExternalPopupMenu(
const WebPopupMenuInfo&,
WebExternalPopupMenuClient*) {
return nullptr;
// May return null.
virtual std::unique_ptr<WebPrescientNetworking> CreatePrescientNetworking() {
return nullptr;
// Services ------------------------------------------------------------
// Returns a blame context for attributing work belonging to this frame.
virtual BlameContext* GetFrameBlameContext() { return nullptr; }
// Returns a BrowserInterfaceBrokerProxy the frame can use to request
// interfaces from the browser.
virtual blink::BrowserInterfaceBrokerProxy* GetBrowserInterfaceBroker();
// Returns an AssociatedInterfaceProvider the frame can use to request
// navigation-associated interfaces from the browser. See also
// LocalFrame::GetRemoteNavigationAssociatedInterfaces().
virtual AssociatedInterfaceProvider*
// General notifications -----------------------------------------------
// Request the creation of a new child frame. Embedders may return nullptr
// to prevent the new child frame from being attached. Otherwise, embedders
// should create a new WebLocalFrame, insert it into the frame tree, and
// return the created frame.
virtual WebLocalFrame* CreateChildFrame(WebLocalFrame* parent,
const WebString& name,
const WebString& fallback_name,
const FramePolicy&,
const WebFrameOwnerProperties&,
FrameOwnerElementType) {
return nullptr;
// Request the creation of a new portal.
virtual std::pair<WebRemoteFrame*, base::UnguessableToken> CreatePortal(
mojo::ScopedInterfaceEndpointHandle portal_endpoint,
mojo::ScopedInterfaceEndpointHandle client_endpoint,
const WebElement& portal_element) {
return std::pair<WebRemoteFrame*, base::UnguessableToken>(
nullptr, base::UnguessableToken());
// Request the creation of a remote frame which corresponds to an existing
// portal.
virtual blink::WebRemoteFrame* AdoptPortal(
const base::UnguessableToken& portal_token,
const WebElement& portal_element) {
return nullptr;
// Called when Blink cannot find a frame with the given name in the frame's
// browsing instance. This gives the embedder a chance to return a frame
// from outside of the browsing instance.
virtual WebFrame* FindFrame(const WebString& name) { return nullptr; }
// This frame has set its opener to another frame, or disowned the opener
// if opener is null. See
virtual void DidChangeOpener(WebFrame*) {}
// Specifies the reason for the detachment.
enum class DetachType { kRemove, kSwap };
// This frame has been detached. Embedders should release any resources
// associated with this frame. If the DetachType is Remove, the frame should
// also be removed from the frame tree; otherwise, if the DetachType is
// Swap, the frame is being replaced in-place by WebFrame::swap().
virtual void FrameDetached(DetachType) {}
// This frame's name has changed.
virtual void DidChangeName(const WebString& name) {}
// The sandbox flags or container policy have changed for a child frame of
// this frame.
virtual void DidChangeFramePolicy(WebFrame* child_frame, const FramePolicy&) {
// Called when a Feature-Policy or Document-Policy or Content-Security-Policy
// HTTP header (for sandbox flags) is encountered while loading the frame's
// document.
virtual void DidSetFramePolicyHeaders(
mojom::WebSandboxFlags flags,
const ParsedFeaturePolicy& feature_policy_header,
const DocumentPolicy::FeatureState& document_policy_header) {}
// Some frame owner properties have changed for a child frame of this frame.
// Frame owner properties currently include: scrolling, marginwidth and
// marginheight.
virtual void DidChangeFrameOwnerProperties(WebFrame* child_frame,
const WebFrameOwnerProperties&) {}
// Called when a watched CSS selector matches or stops matching.
virtual void DidMatchCSS(
const WebVector<WebString>& newly_matching_selectors,
const WebVector<WebString>& stopped_matching_selectors) {}
// Called when a frame is capturing mouse input, such as when a scrollbar
// is being dragged.
virtual void SetMouseCapture(bool capture) {}
// Console messages ----------------------------------------------------
// Whether or not we should report a detailed message for the given source.
virtual bool ShouldReportDetailedMessageForSource(const WebString& source) {
return false;
// A new message was added to the console.
virtual void DidAddMessageToConsole(const WebConsoleMessage&,
const WebString& source_name,
unsigned source_line,
const WebString& stack_trace) {}
// Navigational queries ------------------------------------------------
// Requests the client to begin a navigation for this frame.
// The client can just call CommitNavigation() on this frame's
// WebNavigationControl in response. This will effectively commit a navigation
// the frame has asked about. This usually happens for navigations which
// do not require a network request, e.g. about:blank or mhtml archive.
// In the case of a navigation which requires network request and goes
// to the browser process, client calls CreatePlaceholderDocumentLoader
// (see WebNavigationControl for more details) and commits/cancels
// the navigation later.
// It is also totally valid to ignore the request and abandon the
// navigation entirely.
// Note that ignoring this method effectively disables any navigations
// initiated by Blink in this frame.
virtual void BeginNavigation(std::unique_ptr<blink::WebNavigationInfo> info) {
// Asks the embedder whether the frame is allowed to navigate the main frame
// to a data URL.
// TODO( Move renderer side checks to
// RenderFrameImpl::DecidePolicyForNavigation().
virtual bool AllowContentInitiatedDataUrlNavigations(const WebURL&) {
return false;
// Navigational notifications ------------------------------------------
// These notifications bracket any loading that occurs in the WebFrame.
virtual void DidStartLoading() {}
virtual void DidStopLoading() {}
// A form submission has been requested, but the page's submit event handler
// hasn't yet had a chance to run (and possibly alter/interrupt the submit.)
virtual void WillSendSubmitEvent(const WebFormElement&) {}
// A datasource has been created for a new navigation. The given
// datasource will become the provisional datasource for the frame.
virtual void DidCreateDocumentLoader(WebDocumentLoader*) {}
// The navigation has been committed, as a result of
// WebNavigationControl::CommitNavigation call. The newly created document
// is committed to the frame, the encoding of the response body is known,
// but no content has been loaded or parsed yet.
// When a load commits and a new Document is created, WebLocalFrameClient
// creates a new BrowserInterfaceBroker endpoint to ensure that interface
// receivers in the newly committed Document are associated with the correct
// origin (even if the origin of the old and the new Document are the same).
// The one exception is if the Window object is reused; in that case, blink
// passes |should_reset_browser_interface_broker| = false, and the old
// BrowserInterfaceBroker connection will be reused.
virtual void DidCommitNavigation(const WebHistoryItem&,
bool should_reset_browser_interface_broker) {
// The frame's initial empty document has just been initialized.
virtual void DidCreateInitialEmptyDocument() {}
// A new document has just been committed as a result of evaluating
// javascript url. This document inherited everything from the previous
// document (url, origin, global object, etc.).
// DidCommitNavigation is not called in this case.
virtual void DidCommitJavascriptUrlNavigation(WebDocumentLoader*) {}
// The window object for the frame has been cleared of any extra properties
// that may have been set by script from the previously loaded document. This
// will get invoked multiple times when navigating from an initial empty
// document to the actual document.
virtual void DidClearWindowObject() {}
// The document element has been created.
// This method may not invalidate the frame, nor execute JavaScript code.
virtual void DidCreateDocumentElement() {}
// Like |didCreateDocumentElement|, except this method may run JavaScript
// code (and possibly invalidate the frame).
virtual void RunScriptsAtDocumentElementAvailable() {}
// The page title is available.
virtual void DidReceiveTitle(const WebString& title) {}
// The frame's document finished loading.
// This method may not execute JavaScript code.
// TODO(dgozman): rename this to DidFireDOMContentLoadedEvent.
virtual void DidFinishDocumentLoad() {}
// Like |didFinishDocumentLoad|, except this method may run JavaScript
// code (and possibly invalidate the frame).
virtual void RunScriptsAtDocumentReady(bool document_is_empty) {}
// The frame's window.onload event is ready to fire. This method may delay
// window.onload by incrementing LoadEventDelayCount.
virtual void RunScriptsAtDocumentIdle() {}
// The 'load' event was dispatched.
virtual void DidHandleOnloadEvents() {}
// The frame's document and all of its subresources succeeded to load.
virtual void DidFinishLoad() {}
// The navigation resulted in no change to the documents within the page.
// For example, the navigation may have just resulted in scrolling to a
// named anchor or a PopState event may have been dispatched.
virtual void DidFinishSameDocumentNavigation(const WebHistoryItem&,
bool content_initiated) {}
// Called upon update to scroll position, document state, and other
// non-navigational events related to the data held by WebHistoryItem.
// WARNING: This method may be called very frequently.
virtual void DidUpdateCurrentHistoryItem() {}
// Returns the effective connection type when the frame was fetched.
virtual WebEffectiveConnectionType GetEffectiveConnectionType() {
return WebEffectiveConnectionType::kTypeUnknown;
// Overrides the effective connection type for testing.
virtual void SetEffectiveConnectionTypeForTesting(
WebEffectiveConnectionType) {}
// Returns token to be used as a frame id in the devtools protocol.
// It is derived from the content's devtools_frame_token, is
// defined by the browser and passed into Blink upon frame creation.
virtual base::UnguessableToken GetDevToolsFrameToken() {
return base::UnguessableToken::Create();
// PlzNavigate
// Called to abort a navigation that is being handled by the browser process.
virtual void AbortClientNavigation() {}
// InstalledApp API ----------------------------------------------------
// Used to access the embedder for the InstalledApp API.
virtual WebRelatedAppsFetcher* GetRelatedAppsFetcher() { return nullptr; }
// Editing -------------------------------------------------------------
// These methods allow the client to intercept and overrule editing
// operations.
virtual void DidChangeSelection(bool is_selection_empty) {}
virtual void DidChangeContents() {}
// This method is called in response to handleInputEvent() when the
// default action for the current keyboard event is not suppressed by the
// page, to give the embedder a chance to handle the keyboard event
// specially.
// Returns true if the keyboard event was handled by the embedder,
// indicating that the default action should be suppressed.
virtual bool HandleCurrentKeyboardEvent() { return false; }
// UI ------------------------------------------------------------------
// Shows a context menu with commands relevant to a specific element on
// the given frame. Additional context data is supplied.
virtual void ShowContextMenu(const WebContextMenuData&) {}
// Called when the frame rects changed.
virtual void FrameRectsChanged(const WebRect&) {}
// Called when a new element gets focused. |from_element| is the previously
// focused element, |to_element| is the newly focused one. Either can be null.
virtual void FocusedElementChanged(const WebElement& element) {}
// Called when a frame's intersection with the main frame's document has
// changed.
virtual void OnMainFrameDocumentIntersectionChanged(
const WebRect& intersection_rect) {}
// Low-level resource notifications ------------------------------------
// A request is about to be sent out, and the client may modify it. Request
// is writable, and changes to the URL, for example, will change the request
// made.
virtual void WillSendRequest(WebURLRequest&) {}
// The specified request was satified from WebCore's memory cache.
virtual void DidLoadResourceFromMemoryCache(const WebURLRequest&,
const WebURLResponse&) {}
// The indicated security origin has run active content (such as a
// script) from an insecure source. Note that the insecure content can
// spread to other frames in the same origin.
virtual void DidRunInsecureContent(const WebSecurityOrigin&,
const WebURL& insecure_url) {}
// A PingLoader was created, and a request dispatched to a URL.
virtual void DidDispatchPingLoader(const WebURL&) {}
// This frame has displayed inactive content (such as an image) from
// a connection with certificate errors.
virtual void DidDisplayContentWithCertificateErrors() {}
// This frame has run active content (such as a script) from a
// connection with certificate errors.
virtual void DidRunContentWithCertificateErrors() {}
// A performance timing event (e.g. first paint) occurred
virtual void DidChangePerformanceTiming() {}
// A cpu task or tasks completed. Triggered when at least 100ms of wall time
// was spent in tasks on the frame.
virtual void DidChangeCpuTiming(base::TimeDelta time) {}
// UseCounter ----------------------------------------------------------
// Blink exhibited a certain loading behavior that the browser process will
// use for segregated histograms.
virtual void DidObserveLoadingBehavior(LoadingBehaviorFlag) {}
// Blink UseCounter should only track feature usage for non NTP activities.
// ShouldTrackUseCounter checks the url of a page's main frame is not a new
// tab page url.
virtual bool ShouldTrackUseCounter(const WebURL&) { return true; }
// Blink hits the code path for a certain web feature for the first time on
// this frame. As a performance optimization, features already hit on other
// frames associated with the same page in the renderer are not currently
// reported. This is used for reporting UseCounter features histograms.
virtual void DidObserveNewFeatureUsage(mojom::WebFeature) {}
// Blink hits the code path for a certain CSS property (either an animated CSS
// property or not) for the first time on this frame. As a performance
// optimization, features already hit on other frames associated with the same
// page in the renderer are not currently reported. This is used for reporting
// UseCounter CSS histograms.
virtual void DidObserveNewCssPropertyUsage(
mojom::CSSSampleId /*css_property*/,
bool /*is_animated*/) {}
// Reports that visible elements in the frame shifted (
virtual void DidObserveLayoutShift(double score, bool after_input_or_scroll) {
enum class LazyLoadBehavior {
kDeferredImage, // An image is being deferred by the lazy load feature.
kDeferredFrame, // A frame is being deferred by the lazy load feature.
kLazyLoadedImage, // An image that was previously deferred by the lazy load
// feature is being fully loaded.
kLazyLoadedFrame // A frame that was previously deferred by the lazy load
// feature is being fully loaded.
// Reports lazy loaded behavior when the frame or image is fully deferred or
// if the frame or image is loaded after being deferred. Called every time the
// behavior occurs. This does not apply to images that were loaded as
// placeholders.
virtual void DidObserveLazyLoadBehavior(
WebLocalFrameClient::LazyLoadBehavior lazy_load_behavior) {}
// Script notifications ------------------------------------------------
// Notifies that a new script context has been created for this frame.
// This is similar to didClearWindowObject but only called once per
// frame context.
virtual void DidCreateScriptContext(v8::Local<v8::Context>,
int32_t world_id) {}
// WebKit is about to release its reference to a v8 context for a frame.
virtual void WillReleaseScriptContext(v8::Local<v8::Context>,
int32_t world_id) {}
// Geometry notifications ----------------------------------------------
// The main frame scrolled.
virtual void DidChangeScrollOffset() {}
// Informs the browser that the draggable regions have been updated.
virtual void DraggableRegionsChanged() {}
// MediaStream -----------------------------------------------------
virtual WebMediaStreamDeviceObserver* MediaStreamDeviceObserver() {
return nullptr;
// Encrypted Media -------------------------------------------------
virtual WebEncryptedMediaClient* EncryptedMediaClient() { return nullptr; }
// User agent ------------------------------------------------------
// Asks the embedder if a specific user agent should be used. Non-empty
// strings indicate an override should be used. Otherwise,
// Platform::current()->userAgent() will be called to provide one.
virtual WebString UserAgentOverride() { return WebString(); }
// Do not track ----------------------------------------------------
// Asks the embedder what value the network stack will send for the DNT
// header. An empty string indicates that no DNT header will be send.
virtual WebString DoNotTrackValue() { return WebString(); }
// Accessibility -------------------------------------------------------
// Notifies embedder about an accessibility event on a target WebAXObject for
// the ax::mojom::Event type and ax::mojom::EventFrom source.
virtual void PostAccessibilityEvent(const WebAXObject&,
ax::mojom::EventFrom) {}
// Notifies embedder that a WebAXObject is dirty and its state needs
// to be serialized again. If |subtree| is true, the entire subtree is
// dirty.
virtual void MarkWebAXObjectDirty(const WebAXObject&, bool subtree) {}
// Audio Output Devices API --------------------------------------------
// Checks that the given audio sink exists and is authorized. The result is
// provided via the callbacks.
virtual void CheckIfAudioSinkExistsAndIsAuthorized(
const WebString& sink_id,
WebSetSinkIdCompleteCallback callback) {
// Visibility ----------------------------------------------------------
// Overwrites the given URL to use an HTML5 embed if possible.
// An empty URL is returned if the URL is not overriden.
virtual WebURL OverrideFlashEmbedWithHTML(const WebURL& url) {
return WebURL();
// Loading --------------------------------------------------------------
virtual std::unique_ptr<blink::WebURLLoaderFactory> CreateURLLoaderFactory() {
return nullptr;
// Accessibility Object Model -------------------------------------------
// This method is used to expose the AX Tree stored in content/renderer to the
// DOM as part of AOM Phase 4.
virtual WebComputedAXTree* GetOrCreateWebComputedAXTree() { return nullptr; }
// WebSocket -----------------------------------------------------------
virtual std::unique_ptr<WebSocketHandshakeThrottle>
CreateWebSocketHandshakeThrottle() {
return nullptr;
// AppCache ------------------------------------------------------------
virtual void UpdateSubresourceFactory(
std::unique_ptr<blink::PendingURLLoaderFactoryBundle> pending_factory) {}
// Misc ----------------------------------------------------------------
// Returns true when the contents of plugin are handled externally. This means
// the plugin element will own a content frame but the frame is than used
// externally to load the required handlers.
virtual bool IsPluginHandledExternally(const WebElement& plugin_element,
const WebURL& url,
const WebString& suggested_mime_type) {
return false;
// Returns a scriptable object for the given plugin element. This is used for
// having an external handler implement certain customized APIs for the
// plugin element (e.g., to expose postMessage).
virtual v8::Local<v8::Object> GetScriptableObject(const WebElement&,
v8::Isolate*) {
return v8::Local<v8::Object>();
// Transfers user activation state from |source_frame| to the current frame.
virtual void TransferUserActivationFrom(WebLocalFrame* source_frame) {}
} // namespace blink