2011-02-03 Adam Langley <agl@chromium.org>
[WebKit.git] / Source / WebKit / chromium / public / WebFrameClient.h
1 /*
2  * Copyright (C) 2010 Google Inc. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
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
13  * distribution.
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.
17  *
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.
29  */
30
31 #ifndef WebFrameClient_h
32 #define WebFrameClient_h
33
34 #include "WebCommon.h"
35 #include "WebFileSystem.h"
36 #include "WebNavigationPolicy.h"
37 #include "WebNavigationType.h"
38 #include "WebURLError.h"
39
40 namespace WebKit {
41
42 class WebApplicationCacheHost;
43 class WebApplicationCacheHostClient;
44 class WebCookieJar;
45 class WebDataSource;
46 class WebFormElement;
47 class WebFrame;
48 class WebMediaPlayer;
49 class WebMediaPlayerClient;
50 class WebNode;
51 class WebPlugin;
52 class WebSecurityOrigin;
53 class WebSharedWorker;
54 class WebString;
55 class WebURL;
56 class WebURLRequest;
57 class WebURLResponse;
58 class WebWorker;
59 class WebWorkerClient;
60 struct WebPluginParams;
61 struct WebRect;
62 struct WebSize;
63 struct WebURLError;
64
65 class WebFrameClient {
66 public:
67     // Factory methods -----------------------------------------------------
68
69     // May return null.
70     virtual WebPlugin* createPlugin(WebFrame*, const WebPluginParams&) { return 0; }
71
72     // May return null.
73     virtual WebWorker* createWorker(WebFrame*, WebWorkerClient*) { return 0; }
74
75     // May return null.
76     virtual WebSharedWorker* createSharedWorker(WebFrame*, const WebURL&, const WebString&, unsigned long long) { return 0; }
77
78     // May return null.
79     virtual WebMediaPlayer* createMediaPlayer(WebFrame*, WebMediaPlayerClient*) { return 0; }
80
81     // May return null.
82     virtual WebApplicationCacheHost* createApplicationCacheHost(WebFrame*, WebApplicationCacheHostClient*) { return 0; }
83
84     
85     // Services ------------------------------------------------------------
86
87     // A frame specific cookie jar.  May return null, in which case
88     // WebKitClient::cookieJar() will be called to access cookies.
89     virtual WebCookieJar* cookieJar(WebFrame*) { return 0; }
90
91
92     // General notifications -----------------------------------------------
93
94     // This frame has been detached from the view.
95     //
96     // FIXME: Do not use this in new code. Currently this is used by code in
97     // Chromium that errantly caches WebKit objects.
98     virtual void frameDetached(WebFrame*) { }
99
100     // This frame is about to be closed.
101     virtual void willClose(WebFrame*) { }
102
103     // Controls whether plugins are allowed for this frame.
104     virtual bool allowPlugins(WebFrame*, bool enabledPerSettings) { return enabledPerSettings; }
105
106     // Notifies the client that the frame would have instantiated a plug-in if plug-ins were enabled.
107     virtual void didNotAllowPlugins(WebFrame*) { }
108
109     // Controls whether images are allowed for this frame.
110     virtual bool allowImages(WebFrame*, bool enabledPerSettings) { return enabledPerSettings; }
111
112     // Notifies the client that continuous spell checking has been enabled or
113     // disabled.
114     virtual void didToggleContinuousSpellChecking(WebFrame*) { }
115
116     // Load commands -------------------------------------------------------
117
118     // The client should handle the navigation externally.
119     virtual void loadURLExternally(
120         WebFrame*, const WebURLRequest&, WebNavigationPolicy) { }
121
122
123     // Navigational queries ------------------------------------------------
124
125     // The client may choose to alter the navigation policy.  Otherwise,
126     // defaultPolicy should just be returned.
127     virtual WebNavigationPolicy decidePolicyForNavigation(
128         WebFrame*, const WebURLRequest&, WebNavigationType,
129         const WebNode& originatingNode,
130         WebNavigationPolicy defaultPolicy, bool isRedirect) { return defaultPolicy; }
131
132     // Query if the specified request can be handled.
133     virtual bool canHandleRequest(
134         WebFrame*, const WebURLRequest& request) { return true; }
135
136     // Returns an error corresponding to canHandledRequest() returning false.
137     virtual WebURLError cannotHandleRequestError(
138         WebFrame*, const WebURLRequest& request) { return WebURLError(); }
139
140     // Returns an error corresponding to a user cancellation event.
141     virtual WebURLError cancelledError(
142         WebFrame*, const WebURLRequest& request) { return WebURLError(); }
143
144     // Notify that a URL cannot be handled.
145     virtual void unableToImplementPolicyWithError(
146         WebFrame*, const WebURLError&) { }
147
148
149     // Navigational notifications ------------------------------------------
150
151     // A form submission has been requested, but the page's submit event handler
152     // hasn't yet had a chance to run (and possibly alter/interrupt the submit.)
153     virtual void willSendSubmitEvent(WebFrame*, const WebFormElement&) { }
154
155     // A form submission is about to occur.
156     virtual void willSubmitForm(WebFrame*, const WebFormElement&) { }
157
158     // A client-side redirect will occur.  This may correspond to a <META
159     // refresh> or some script activity.
160     virtual void willPerformClientRedirect(
161         WebFrame*, const WebURL& from, const WebURL& to,
162         double interval, double fireTime) { }
163
164     // A client-side redirect was cancelled.
165     virtual void didCancelClientRedirect(WebFrame*) { }
166
167     // A client-side redirect completed.
168     virtual void didCompleteClientRedirect(WebFrame*, const WebURL& fromURL) { }
169
170     // A datasource has been created for a new navigation.  The given
171     // datasource will become the provisional datasource for the frame.
172     virtual void didCreateDataSource(WebFrame*, WebDataSource*) { }
173
174     // A new provisional load has been started.
175     virtual void didStartProvisionalLoad(WebFrame*) { }
176
177     // The provisional load was redirected via a HTTP 3xx response.
178     virtual void didReceiveServerRedirectForProvisionalLoad(WebFrame*) { }
179
180     // The provisional load failed.
181     virtual void didFailProvisionalLoad(WebFrame*, const WebURLError&) { }
182
183     // Notifies the client to commit data for the given frame.  The client
184     // may optionally prevent default processing by setting preventDefault
185     // to true before returning.  If default processing is prevented, then
186     // it is up to the client to manually call commitDocumentData on the
187     // WebFrame.  It is only valid to call commitDocumentData within a call
188     // to didReceiveDocumentData.  If commitDocumentData is not called,
189     // then an empty document will be loaded.
190     virtual void didReceiveDocumentData(
191         WebFrame*, const char* data, size_t length, bool& preventDefault) { }
192
193     // The provisional datasource is now committed.  The first part of the
194     // response body has been received, and the encoding of the response
195     // body is known.
196     virtual void didCommitProvisionalLoad(WebFrame*, bool isNewNavigation) { }
197
198     // The window object for the frame has been cleared of any extra
199     // properties that may have been set by script from the previously
200     // loaded document.
201     virtual void didClearWindowObject(WebFrame*) { }
202
203     // The document element has been created.
204     virtual void didCreateDocumentElement(WebFrame*) { }
205
206     // The page title is available.
207     virtual void didReceiveTitle(WebFrame*, const WebString& title) { }
208
209     // The icons for the page have changed.
210     virtual void didChangeIcons(WebFrame*) { }
211
212     // The frame's document finished loading.
213     virtual void didFinishDocumentLoad(WebFrame*) { }
214
215     // The 'load' event was dispatched.
216     virtual void didHandleOnloadEvents(WebFrame*) { }
217
218     // The frame's document or one of its subresources failed to load.
219     virtual void didFailLoad(WebFrame*, const WebURLError&) { }
220
221     // The frame's document and all of its subresources succeeded to load.
222     virtual void didFinishLoad(WebFrame*) { }
223
224     // The navigation resulted in no change to the documents within the page.
225     // For example, the navigation may have just resulted in scrolling to a
226     // named anchor or a PopState event may have been dispatched.
227     virtual void didNavigateWithinPage(WebFrame*, bool isNewNavigation) { }
228
229     // The navigation resulted in scrolling the page to a named anchor instead
230     // of downloading a new document.
231     virtual void didChangeLocationWithinPage(WebFrame*) { }
232
233     // Called upon update to scroll position, document state, and other
234     // non-navigational events related to the data held by WebHistoryItem.
235     // WARNING: This method may be called very frequently.
236     virtual void didUpdateCurrentHistoryItem(WebFrame*) { }
237
238
239     // Low-level resource notifications ------------------------------------
240
241     // An identifier was assigned to the specified request.  The client
242     // should remember this association if interested in subsequent events.
243     virtual void assignIdentifierToRequest(
244         WebFrame*, unsigned identifier, const WebURLRequest&) { }
245
246      // Remove the association between an identifier assigned to a request if
247      // the client keeps such an association.
248      virtual void removeIdentifierForRequest(unsigned identifier) { }
249
250     // A request is about to be sent out, and the client may modify it.  Request
251     // is writable, and changes to the URL, for example, will change the request
252     // made.  If this request is the result of a redirect, then redirectResponse
253     // will be non-null and contain the response that triggered the redirect.
254     virtual void willSendRequest(
255         WebFrame*, unsigned identifier, WebURLRequest&,
256         const WebURLResponse& redirectResponse) { }
257
258     // Response headers have been received for the resource request given
259     // by identifier.
260     virtual void didReceiveResponse(
261         WebFrame*, unsigned identifier, const WebURLResponse&) { }
262
263     // The resource request given by identifier succeeded.
264     virtual void didFinishResourceLoad(
265         WebFrame*, unsigned identifier) { }
266
267     // The resource request given by identifier failed.
268     virtual void didFailResourceLoad(
269         WebFrame*, unsigned identifier, const WebURLError&) { }
270
271     // The specified request was satified from WebCore's memory cache.
272     virtual void didLoadResourceFromMemoryCache(
273         WebFrame*, const WebURLRequest&, const WebURLResponse&) { }
274
275     // This frame has displayed inactive content (such as an image) from an
276     // insecure source.  Inactive content cannot spread to other frames.
277     virtual void didDisplayInsecureContent(WebFrame*) { }
278
279     // The indicated security origin has run active content (such as a
280     // script) from an insecure source.  Note that the insecure content can
281     // spread to other frames in the same origin.
282     virtual void didRunInsecureContent(WebFrame*, const WebSecurityOrigin&, const WebURL& insecureURL) { }
283
284
285     // Script notifications ------------------------------------------------
286
287     // Controls whether scripts are allowed to execute for this frame.
288     virtual bool allowScript(WebFrame*, bool enabledPerSettings) { return enabledPerSettings; }
289
290     // Controls whether access to Web Databases is allowed for this frame.
291     virtual bool allowDatabase(WebFrame*, const WebString& name, const WebString& displayName, unsigned long estimatedSize) { return true; }
292
293     // Notifies the client that the frame would have executed script if script were enabled.
294     virtual void didNotAllowScript(WebFrame*) { }
295
296     // Script in the page tried to allocate too much memory.
297     virtual void didExhaustMemoryAvailableForScript(WebFrame*) { }
298
299     // Notifies that a new script context has been created for this frame.
300     // This is similar to didClearWindowObject but only called once per
301     // frame context.
302     virtual void didCreateScriptContext(WebFrame*) { }
303
304     // Notifies that this frame's script context has been destroyed.
305     virtual void didDestroyScriptContext(WebFrame*) { }
306
307     // Notifies that a garbage-collected context was created - content
308     // scripts.
309     virtual void didCreateIsolatedScriptContext(WebFrame*) { }
310
311     // Controls whether the given script extension should run in a new script
312     // context in this frame. If extensionGroup is 0, the script context is the
313     // frame's main context. Otherwise, it is a context created by
314     // WebFrame::executeScriptInIsolatedWorld with that same extensionGroup
315     // value.
316     virtual bool allowScriptExtension(WebFrame*, const WebString& extensionName, int extensionGroup) { return true; }
317
318
319     // Geometry notifications ----------------------------------------------
320
321     // The frame's document finished the initial layout of a page.
322     virtual void didFirstLayout(WebFrame*) { }
323
324     // The frame's document finished the initial non-empty layout of a page.
325     virtual void didFirstVisuallyNonEmptyLayout(WebFrame*) { }
326
327     // The size of the content area changed.
328     virtual void didChangeContentsSize(WebFrame*, const WebSize&) { }
329
330     // The main frame scrolled.
331     virtual void didChangeScrollOffset(WebFrame*) { }
332
333
334     // Find-in-page notifications ------------------------------------------
335
336     // Notifies how many matches have been found so far, for a given
337     // identifier.  |finalUpdate| specifies whether this is the last update
338     // (all frames have completed scoping).
339     virtual void reportFindInPageMatchCount(
340         int identifier, int count, bool finalUpdate) { }
341
342     // Notifies what tick-mark rect is currently selected.   The given
343     // identifier lets the client know which request this message belongs
344     // to, so that it can choose to ignore the message if it has moved on
345     // to other things.  The selection rect is expected to have coordinates
346     // relative to the top left corner of the web page area and represent
347     // where on the screen the selection rect is currently located.
348     virtual void reportFindInPageSelection(
349         int identifier, int activeMatchOrdinal, const WebRect& selection) { }
350
351     // FileSystem ----------------------------------------------------
352
353     // Requests to open a FileSystem.
354     // |size| indicates how much storage space (in bytes) the caller expects
355     // to need.
356     // WebFileSystemCallbacks::didOpenFileSystem() must be called with
357     // a name and root path for the requested FileSystem when the operation
358     // is completed successfully. WebFileSystemCallbacks::didFail() must be
359     // called otherwise. The create bool is for indicating whether or not to
360     // create root path for file systems if it do not exist.
361     virtual void openFileSystem(
362         WebFrame*, WebFileSystem::Type, long long size,
363         bool create, WebFileSystemCallbacks*) { }
364
365 protected:
366     ~WebFrameClient() { }
367 };
368
369 } // namespace WebKit
370
371 #endif