2 * Copyright (C) 2011, 2012 Google Inc. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
8 * * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * * Redistributions in binary form must reproduce the above
11 * copyright notice, this list of conditions and the following disclaimer
12 * in the documentation and/or other materials provided with the
14 * * Neither the name of Google Inc. nor the names of its
15 * contributors may be used to endorse or promote products derived from
16 * this software without specific prior written permission.
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 #ifndef WebFrameClient_h
32 #define WebFrameClient_h
34 #include "../platform/WebColor.h"
35 #include "WebAXObject.h"
36 #include "WebDOMMessageEvent.h"
37 #include "WebDataSource.h"
39 #include "WebHistoryCommitType.h"
40 #include "WebHistoryItem.h"
41 #include "WebIconURL.h"
42 #include "WebNavigationPolicy.h"
43 #include "WebNavigationType.h"
44 #include "WebSecurityOrigin.h"
45 #include "WebTextDirection.h"
46 #include "public/platform/WebCommon.h"
47 #include "public/platform/WebFileSystem.h"
48 #include "public/platform/WebFileSystemType.h"
49 #include "public/platform/WebStorageQuotaCallbacks.h"
50 #include "public/platform/WebStorageQuotaType.h"
51 #include "public/platform/WebURLError.h"
52 #include "public/platform/WebURLRequest.h"
57 class WebApplicationCacheHost;
58 class WebApplicationCacheHostClient;
59 class WebCachedURLRequest;
60 class WebColorChooser;
61 class WebColorChooserClient;
62 class WebContentDecryptionModule;
66 class WebExternalPopupMenu;
67 class WebExternalPopupMenuClient;
69 class WebGeolocationClient;
72 class WebMediaPlayerClient;
74 class WebNotificationPermissionCallback;
75 class WebNotificationPresenter;
76 class WebServiceWorkerProvider;
77 class WebServiceWorkerProviderClient;
78 class WebSocketHandle;
81 class WebRTCPeerConnectionHandler;
82 class WebScreenOrientationClient;
83 class WebSharedWorker;
84 class WebSharedWorkerClient;
85 class WebSocketStreamHandle;
90 class WebUserMediaClient;
91 class WebWorkerPermissionClientProxy;
92 struct WebColorSuggestion;
93 struct WebConsoleMessage;
94 struct WebContextMenuData;
95 struct WebPluginParams;
96 struct WebPopupMenuInfo;
101 class WebFrameClient {
103 // Factory methods -----------------------------------------------------
106 virtual WebPlugin* createPlugin(WebLocalFrame*, const WebPluginParams&) { return 0; }
109 // WebContentDecryptionModule* may be null if one has not yet been set.
110 virtual WebMediaPlayer* createMediaPlayer(WebLocalFrame*, const WebURL&, WebMediaPlayerClient*, WebContentDecryptionModule*) { return 0; }
113 virtual WebContentDecryptionModule* createContentDecryptionModule(WebLocalFrame*, const WebSecurityOrigin&, const WebString& keySystem) { return 0; }
116 virtual WebApplicationCacheHost* createApplicationCacheHost(WebLocalFrame*, WebApplicationCacheHostClient*) { return 0; }
119 virtual WebServiceWorkerProvider* createServiceWorkerProvider(WebLocalFrame* frame) { return 0; }
122 virtual WebWorkerPermissionClientProxy* createWorkerPermissionClientProxy(WebLocalFrame*) { return 0; }
124 // Create a new WebPopupMenu. In the "createExternalPopupMenu" form, the
125 // client is responsible for rendering the contents of the popup menu.
126 virtual WebExternalPopupMenu* createExternalPopupMenu(
127 const WebPopupMenuInfo&, WebExternalPopupMenuClient*) { return 0; }
130 // Services ------------------------------------------------------------
132 // A frame specific cookie jar. May return null, in which case
133 // WebKitPlatformSupport::cookieJar() will be called to access cookies.
134 virtual WebCookieJar* cookieJar(WebLocalFrame*) { return 0; }
137 // General notifications -----------------------------------------------
139 // Indicates if creating a plugin without an associated renderer is supported.
140 virtual bool canCreatePluginWithoutRenderer(const WebString& mimeType) { return false; }
142 // Indicates that another page has accessed the DOM of the initial empty
143 // document of a main frame. After this, it is no longer safe to show a
144 // pending navigation's URL, because a URL spoof is possible.
145 virtual void didAccessInitialDocument(WebLocalFrame*) { }
147 // A child frame was created in this frame. This is called when the frame
148 // is created and initialized. Takes the name of the new frame, the parent
149 // frame and returns a new WebFrame. The WebFrame is considered in-use
150 // until frameDetached() is called on it.
151 // Note: If you override this, you should almost certainly be overriding
153 virtual WebFrame* createChildFrame(WebLocalFrame* parent, const WebString& frameName) { return 0; }
155 // This frame set its opener to null, disowning it.
156 // See http://html.spec.whatwg.org/#dom-opener.
157 virtual void didDisownOpener(WebLocalFrame*) { }
159 // This frame has been detached from the view, but has not been closed yet.
160 virtual void frameDetached(WebFrame*) { }
162 // This frame has become focused..
163 virtual void frameFocused() { }
165 // This frame is about to be closed. This is called after frameDetached,
166 // when the document is being unloaded, due to new one committing.
167 virtual void willClose(WebFrame*) { }
169 // This frame's name has changed.
170 virtual void didChangeName(WebLocalFrame*, const WebString&) { }
172 // Called when a watched CSS selector matches or stops matching.
173 virtual void didMatchCSS(WebLocalFrame*, const WebVector<WebString>& newlyMatchingSelectors, const WebVector<WebString>& stoppedMatchingSelectors) { }
176 // Console messages ----------------------------------------------------
178 // Whether or not we should report a detailed message for the given source.
179 virtual bool shouldReportDetailedMessageForSource(const WebString& source) { return false; }
181 // A new message was added to the console.
182 virtual void didAddMessageToConsole(const WebConsoleMessage&, const WebString& sourceName, unsigned sourceLine, const WebString& stackTrace) { }
185 // Load commands -------------------------------------------------------
187 // The client should handle the navigation externally.
188 virtual void loadURLExternally(
189 WebLocalFrame*, const WebURLRequest&, WebNavigationPolicy, const WebString& downloadName) { }
192 // Navigational queries ------------------------------------------------
194 // The client may choose to alter the navigation policy. Otherwise,
195 // defaultPolicy should just be returned.
197 struct NavigationPolicyInfo {
198 WebLocalFrame* frame;
199 WebDataSource::ExtraData* extraData;
200 const WebURLRequest& urlRequest;
201 WebNavigationType navigationType;
202 WebNavigationPolicy defaultPolicy;
204 bool isTransitionNavigation;
206 NavigationPolicyInfo(const WebURLRequest& urlRequest)
209 , urlRequest(urlRequest)
210 , navigationType(WebNavigationTypeOther)
211 , defaultPolicy(WebNavigationPolicyIgnore)
213 , isTransitionNavigation(false) { }
216 virtual WebNavigationPolicy decidePolicyForNavigation(const NavigationPolicyInfo& info)
218 return decidePolicyForNavigation(info.frame, info.extraData, info.urlRequest, info.navigationType, info.defaultPolicy, info.isRedirect);
222 virtual WebNavigationPolicy decidePolicyForNavigation(
223 WebLocalFrame*, WebDataSource::ExtraData*, const WebURLRequest&, WebNavigationType,
224 WebNavigationPolicy defaultPolicy, bool isRedirect) { return defaultPolicy; }
226 // During a history navigation, we may choose to load new subframes from history as well.
227 // This returns such a history item if appropriate.
228 virtual WebHistoryItem historyItemForNewChildFrame(WebFrame*) { return WebHistoryItem(); }
231 // Navigational notifications ------------------------------------------
233 // These notifications bracket any loading that occurs in the WebFrame.
234 virtual void didStartLoading(bool toDifferentDocument) { }
235 virtual void didStopLoading() { }
237 // Notification that some progress was made loading the current frame.
238 // loadProgress is a value between 0 (nothing loaded) and 1.0 (frame fully
240 virtual void didChangeLoadProgress(double loadProgress) { }
242 // A form submission has been requested, but the page's submit event handler
243 // hasn't yet had a chance to run (and possibly alter/interrupt the submit.)
244 virtual void willSendSubmitEvent(WebLocalFrame*, const WebFormElement&) { }
246 // A form submission is about to occur.
247 virtual void willSubmitForm(WebLocalFrame*, const WebFormElement&) { }
249 // A datasource has been created for a new navigation. The given
250 // datasource will become the provisional datasource for the frame.
251 virtual void didCreateDataSource(WebLocalFrame*, WebDataSource*) { }
253 // A new provisional load has been started.
254 virtual void didStartProvisionalLoad(WebLocalFrame* localFrame, bool isTransitionNavigation) { }
256 // The provisional load was redirected via a HTTP 3xx response.
257 virtual void didReceiveServerRedirectForProvisionalLoad(WebLocalFrame*) { }
259 // The provisional load failed.
260 virtual void didFailProvisionalLoad(WebLocalFrame*, const WebURLError&) { }
262 // The provisional datasource is now committed. The first part of the
263 // response body has been received, and the encoding of the response
265 virtual void didCommitProvisionalLoad(WebLocalFrame*, const WebHistoryItem&, WebHistoryCommitType) { }
267 // The window object for the frame has been cleared of any extra
268 // properties that may have been set by script from the previously
270 virtual void didClearWindowObject(WebLocalFrame* frame) { }
272 // The document element has been created.
273 virtual void didCreateDocumentElement(WebLocalFrame*) { }
275 // The page title is available.
276 virtual void didReceiveTitle(WebLocalFrame* frame, const WebString& title, WebTextDirection direction) { }
278 // The icon for the page have changed.
279 virtual void didChangeIcon(WebLocalFrame*, WebIconURL::Type) { }
281 // The frame's document finished loading.
282 virtual void didFinishDocumentLoad(WebLocalFrame*) { }
284 // The 'load' event was dispatched.
285 virtual void didHandleOnloadEvents(WebLocalFrame*) { }
287 // The frame's document or one of its subresources failed to load.
288 virtual void didFailLoad(WebLocalFrame*, const WebURLError&) { }
290 // The frame's document and all of its subresources succeeded to load.
291 virtual void didFinishLoad(WebLocalFrame*) { }
293 // The navigation resulted in no change to the documents within the page.
294 // For example, the navigation may have just resulted in scrolling to a
295 // named anchor or a PopState event may have been dispatched.
296 virtual void didNavigateWithinPage(WebLocalFrame*, const WebHistoryItem&, WebHistoryCommitType) { }
298 // Called upon update to scroll position, document state, and other
299 // non-navigational events related to the data held by WebHistoryItem.
300 // WARNING: This method may be called very frequently.
301 virtual void didUpdateCurrentHistoryItem(WebLocalFrame*) { }
303 // The frame's manifest has changed.
304 virtual void didChangeManifest(WebLocalFrame*) { }
306 // The frame's theme color has changed.
307 virtual void didChangeThemeColor() { }
310 // Transition navigations -----------------------------------------------
312 // Provides serialized markup of transition elements for use in the following navigation.
313 virtual void addNavigationTransitionData(const WebString& allowedDestinationOrigin, const WebString& selector, const WebString& markup) { }
316 // Web Notifications ---------------------------------------------------
318 // Requests permission to display platform notifications on the origin of this frame.
319 virtual void requestNotificationPermission(const WebSecurityOrigin&, WebNotificationPermissionCallback* callback) { }
321 // Called to retrieve the provider of desktop notifications.
322 // FIXME: Remove this method once the presenter is obtained through Platform.
323 virtual WebNotificationPresenter* notificationPresenter() { return 0; }
326 // Editing -------------------------------------------------------------
328 // These methods allow the client to intercept and overrule editing
330 virtual void didChangeSelection(bool isSelectionEmpty) { }
333 // Dialogs -------------------------------------------------------------
335 // This method opens the color chooser and returns a new WebColorChooser
336 // instance. If there is a WebColorChooser already from the last time this
337 // was called, it ends the color chooser by calling endChooser, and replaces
338 // it with the new one. The given list of suggestions can be used to show a
339 // simple interface with a limited set of choices.
341 virtual WebColorChooser* createColorChooser(
342 WebColorChooserClient*,
344 const WebVector<WebColorSuggestion>&) { return 0; }
346 // Displays a modal alert dialog containing the given message. Returns
347 // once the user dismisses the dialog.
348 virtual void runModalAlertDialog(const WebString& message) { }
350 // Displays a modal confirmation dialog with the given message as
351 // description and OK/Cancel choices. Returns true if the user selects
352 // 'OK' or false otherwise.
353 virtual bool runModalConfirmDialog(const WebString& message) { return false; }
355 // Displays a modal input dialog with the given message as description
356 // and OK/Cancel choices. The input field is pre-filled with
357 // defaultValue. Returns true if the user selects 'OK' or false
358 // otherwise. Upon returning true, actualValue contains the value of
360 virtual bool runModalPromptDialog(
361 const WebString& message, const WebString& defaultValue,
362 WebString* actualValue) { return false; }
364 // Displays a modal confirmation dialog containing the given message as
365 // description and OK/Cancel choices, where 'OK' means that it is okay
366 // to proceed with closing the view. Returns true if the user selects
367 // 'OK' or false otherwise.
368 virtual bool runModalBeforeUnloadDialog(
369 bool isReload, const WebString& message) { return true; }
372 // UI ------------------------------------------------------------------
374 // Shows a context menu with commands relevant to a specific element on
375 // the given frame. Additional context data is supplied.
376 virtual void showContextMenu(const WebContextMenuData&) { }
378 // Called when the data attached to the currently displayed context menu is
379 // invalidated. The context menu may be closed if possible.
380 virtual void clearContextMenu() { }
383 // Low-level resource notifications ------------------------------------
385 // An element will request a resource.
386 virtual void willRequestResource(WebLocalFrame*, const WebCachedURLRequest&) { }
388 // A request is about to be sent out, and the client may modify it. Request
389 // is writable, and changes to the URL, for example, will change the request
390 // made. If this request is the result of a redirect, then redirectResponse
391 // will be non-null and contain the response that triggered the redirect.
392 virtual void willSendRequest(
393 WebLocalFrame*, unsigned identifier, WebURLRequest&,
394 const WebURLResponse& redirectResponse) { }
396 // Response headers have been received for the resource request given
398 virtual void didReceiveResponse(
399 WebLocalFrame*, unsigned identifier, const WebURLResponse&) { }
401 virtual void didChangeResourcePriority(
402 WebLocalFrame* webFrame, unsigned identifier, const WebURLRequest::Priority& priority, int) { }
404 // The resource request given by identifier succeeded.
405 virtual void didFinishResourceLoad(
406 WebLocalFrame*, unsigned identifier) { }
408 // The specified request was satified from WebCore's memory cache.
409 virtual void didLoadResourceFromMemoryCache(
410 WebLocalFrame*, const WebURLRequest&, const WebURLResponse&) { }
412 // This frame has displayed inactive content (such as an image) from an
413 // insecure source. Inactive content cannot spread to other frames.
414 virtual void didDisplayInsecureContent(WebLocalFrame*) { }
416 // The indicated security origin has run active content (such as a
417 // script) from an insecure source. Note that the insecure content can
418 // spread to other frames in the same origin.
419 virtual void didRunInsecureContent(WebLocalFrame*, const WebSecurityOrigin&, const WebURL& insecureURL) { }
421 // A reflected XSS was encountered in the page and suppressed.
422 virtual void didDetectXSS(WebLocalFrame*, const WebURL&, bool didBlockEntirePage) { }
424 // A PingLoader was created, and a request dispatched to a URL.
425 virtual void didDispatchPingLoader(WebLocalFrame*, const WebURL&) { }
427 // The loaders in this frame have been stopped.
428 virtual void didAbortLoading(WebLocalFrame*) { }
431 // Script notifications ------------------------------------------------
433 // Notifies that a new script context has been created for this frame.
434 // This is similar to didClearWindowObject but only called once per
436 virtual void didCreateScriptContext(WebLocalFrame*, v8::Handle<v8::Context>, int extensionGroup, int worldId) { }
438 // WebKit is about to release its reference to a v8 context for a frame.
439 virtual void willReleaseScriptContext(WebLocalFrame*, v8::Handle<v8::Context>, int worldId) { }
442 // Geometry notifications ----------------------------------------------
444 // The frame's document finished the initial non-empty layout of a page.
445 virtual void didFirstVisuallyNonEmptyLayout(WebLocalFrame*) { }
447 // The main frame scrolled.
448 virtual void didChangeScrollOffset(WebLocalFrame*) { }
450 // If the frame is loading an HTML document, this will be called to
451 // notify that the <body> will be attached soon.
452 virtual void willInsertBody(WebLocalFrame*) { }
455 // Find-in-page notifications ------------------------------------------
457 // Notifies how many matches have been found so far, for a given
458 // identifier. |finalUpdate| specifies whether this is the last update
459 // (all frames have completed scoping).
460 virtual void reportFindInPageMatchCount(
461 int identifier, int count, bool finalUpdate) { }
463 // Notifies what tick-mark rect is currently selected. The given
464 // identifier lets the client know which request this message belongs
465 // to, so that it can choose to ignore the message if it has moved on
466 // to other things. The selection rect is expected to have coordinates
467 // relative to the top left corner of the web page area and represent
468 // where on the screen the selection rect is currently located.
469 virtual void reportFindInPageSelection(
470 int identifier, int activeMatchOrdinal, const WebRect& selection) { }
473 // Quota ---------------------------------------------------------
475 // Requests a new quota size for the origin's storage.
476 // |newQuotaInBytes| indicates how much storage space (in bytes) the
477 // caller expects to need.
478 // WebStorageQuotaCallbacks::didGrantStorageQuota will be called when
479 // a new quota is granted. WebStorageQuotaCallbacks::didFail
480 // is called with an error code otherwise.
481 // Note that the requesting quota size may not always be granted and
482 // a smaller amount of quota than requested might be returned.
483 virtual void requestStorageQuota(
484 WebLocalFrame*, WebStorageQuotaType,
485 unsigned long long newQuotaInBytes,
486 WebStorageQuotaCallbacks) { }
488 // WebSocket -----------------------------------------------------
490 // A WebSocket object is going to open a new socket stream connection. Used
491 // by the old WebSocket implementation.
492 virtual void willOpenSocketStream(WebSocketStreamHandle*) { }
494 // A WebSocket object is going to open a new WebSocket connection. Used by
495 // the new WebSocket implementation.
496 virtual void willOpenWebSocket(WebSocketHandle*) { }
499 // Geolocation ---------------------------------------------------------
501 // Access the embedder API for (client-based) geolocation client .
502 virtual WebGeolocationClient* geolocationClient() { return 0; }
505 // MediaStream -----------------------------------------------------
507 // A new WebRTCPeerConnectionHandler is created.
508 virtual void willStartUsingPeerConnectionHandler(WebLocalFrame*, WebRTCPeerConnectionHandler*) { }
510 virtual WebUserMediaClient* userMediaClient() { return 0; }
513 // Web MIDI -------------------------------------------------------------
515 virtual WebMIDIClient* webMIDIClient() { return 0; }
518 // Messages ------------------------------------------------------
520 // Notifies the embedder that a postMessage was issued on this frame, and
521 // gives the embedder a chance to handle it instead of WebKit. Returns true
522 // if the embedder handled it.
523 virtual bool willCheckAndDispatchMessageEvent(
524 WebLocalFrame* sourceFrame,
525 WebFrame* targetFrame,
526 WebSecurityOrigin target,
527 WebDOMMessageEvent event) { return false; }
529 // Asks the embedder if a specific user agent should be used for the given
530 // URL. Non-empty strings indicate an override should be used. Otherwise,
531 // Platform::current()->userAgent() will be called to provide one.
532 virtual WebString userAgentOverride(WebLocalFrame*, const WebURL& url) { return WebString(); }
534 // Asks the embedder what value the network stack will send for the DNT
535 // header. An empty string indicates that no DNT header will be send.
536 virtual WebString doNotTrackValue(WebLocalFrame*) { return WebString(); }
539 // WebGL ------------------------------------------------------
541 // Asks the embedder whether WebGL is allowed for the given WebFrame.
542 // This call is placed here instead of WebPermissionClient because this
543 // class is implemented in content/, and putting it here avoids adding
544 // more public content/ APIs.
545 virtual bool allowWebGL(WebLocalFrame*, bool defaultValue) { return defaultValue; }
547 // Notifies the client that a WebGL context was lost on this page with the
548 // given reason (one of the GL_ARB_robustness status codes; see
549 // Extensions3D.h in WebCore/platform/graphics).
550 virtual void didLoseWebGLContext(WebLocalFrame*, int) { }
552 // FIXME: Remove this method once we have input routing in the browser
553 // process. See http://crbug.com/339659.
554 virtual void forwardInputEvent(const WebInputEvent*) { }
556 // Send initial drawing parameters to a child frame that is being rendered out of process.
557 virtual void initializeChildFrame(const WebRect& frameRect, float scaleFactor) { }
560 // Screen Orientation --------------------------------------------------
562 // Access the embedder API for (client-based) screen orientation client .
563 virtual WebScreenOrientationClient* webScreenOrientationClient() { return 0; }
565 // Accessibility -------------------------------------------------------
567 // Notifies embedder about an accessibility event.
568 virtual void postAccessibilityEvent(const WebAXObject&, WebAXEvent) { }
570 // ServiceWorker -------------------------------------------------------
572 // Whether the frame is controlled by the ServiceWorker
573 virtual bool isControlledByServiceWorker() { return false; }
576 virtual ~WebFrameClient() { }