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