1 // Copyright (c) 2011 Marshall A. Greenblatt. All rights reserved.
3 // Redistribution and use in source and binary forms, with or without
4 // modification, are permitted provided that the following conditions are
7 // * Redistributions of source code must retain the above copyright
8 // notice, this list of conditions and the following disclaimer.
9 // * Redistributions in binary form must reproduce the above
10 // copyright notice, this list of conditions and the following disclaimer
11 // in the documentation and/or other materials provided with the
13 // * Neither the name of Google Inc. nor the name Chromium Embedded
14 // Framework nor the names of its contributors may be used to endorse
15 // or promote products derived from this software without specific prior
16 // 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.
30 // ---------------------------------------------------------------------------
32 // The contents of this file must follow a specific format in order to
33 // support the CEF translator tool. See the translator.README.txt file in the
34 // tools directory for more information.
37 #ifndef CEF_INCLUDE_CEF_REQUEST_HANDLER_H_
38 #define CEF_INCLUDE_CEF_REQUEST_HANDLER_H_
41 #include "include/cef_auth_callback.h"
42 #include "include/cef_base.h"
43 #include "include/cef_browser.h"
44 #include "include/cef_frame.h"
45 #include "include/cef_resource_handler.h"
46 #include "include/cef_response.h"
47 #include "include/cef_request.h"
48 #include "include/cef_ssl_info.h"
49 #include "include/cef_web_plugin.h"
53 // Callback interface used for asynchronous continuation of url requests.
55 /*--cef(source=library)--*/
56 class CefRequestCallback : public virtual CefBase {
59 // Continue the url request. If |allow| is true the request will be continued.
60 // Otherwise, the request will be canceled.
62 /*--cef(capi_name=cont)--*/
63 virtual void Continue(bool allow) =0;
66 // Cancel the url request.
69 virtual void Cancel() =0;
74 // Implement this interface to handle events related to browser requests. The
75 // methods of this class will be called on the thread indicated.
77 /*--cef(source=client)--*/
78 class CefRequestHandler : public virtual CefBase {
80 typedef cef_return_value_t ReturnValue;
81 typedef cef_termination_status_t TerminationStatus;
82 typedef cef_window_open_disposition_t WindowOpenDisposition;
85 // Called on the UI thread before browser navigation. Return true to cancel
86 // the navigation or false to allow the navigation to proceed. The |request|
87 // object cannot be modified in this callback.
88 // CefLoadHandler::OnLoadingStateChange will be called twice in all cases.
89 // If the navigation is allowed CefLoadHandler::OnLoadStart and
90 // CefLoadHandler::OnLoadEnd will be called. If the navigation is canceled
91 // CefLoadHandler::OnLoadError will be called with an |errorCode| value of
95 virtual bool OnBeforeBrowse(CefRefPtr<CefBrowser> browser,
96 CefRefPtr<CefFrame> frame,
97 CefRefPtr<CefRequest> request,
103 // Called on the UI thread before OnBeforeBrowse in certain limited cases
104 // where navigating a new or different browser might be desirable. This
105 // includes user-initiated navigation that might open in a special way (e.g.
106 // links clicked via middle-click or ctrl + left-click) and certain types of
107 // cross-origin navigation initiated from the renderer process (e.g.
108 // navigating the top-level frame to/from a file URL). The |browser| and
109 // |frame| values represent the source of the navigation. The
110 // |target_disposition| value indicates where the user intended to navigate
111 // the browser based on standard Chromium behaviors (e.g. current tab,
112 // new tab, etc). The |user_gesture| value will be true if the browser
113 // navigated via explicit user gesture (e.g. clicking a link) or false if it
114 // navigated automatically (e.g. via the DomContentLoaded event). Return true
115 // to cancel the navigation or false to allow the navigation to proceed in the
116 // source browser's top-level frame.
119 virtual bool OnOpenURLFromTab(CefRefPtr<CefBrowser> browser,
120 CefRefPtr<CefFrame> frame,
121 const CefString& target_url,
122 WindowOpenDisposition target_disposition,
128 // Called on the IO thread before a resource request is loaded. The |request|
129 // object may be modified. Return RV_CONTINUE to continue the request
130 // immediately. Return RV_CONTINUE_ASYNC and call CefRequestCallback::
131 // Continue() at a later time to continue or cancel the request
132 // asynchronously. Return RV_CANCEL to cancel the request immediately.
135 /*--cef(default_retval=RV_CONTINUE)--*/
136 virtual ReturnValue OnBeforeResourceLoad(
137 CefRefPtr<CefBrowser> browser,
138 CefRefPtr<CefFrame> frame,
139 CefRefPtr<CefRequest> request,
140 CefRefPtr<CefRequestCallback> callback) {
145 // Called on the IO thread before a resource is loaded. To allow the resource
146 // to load normally return NULL. To specify a handler for the resource return
147 // a CefResourceHandler object. The |request| object should not be modified in
151 virtual CefRefPtr<CefResourceHandler> GetResourceHandler(
152 CefRefPtr<CefBrowser> browser,
153 CefRefPtr<CefFrame> frame,
154 CefRefPtr<CefRequest> request) {
159 // Called on the IO thread when a resource load is redirected. The |request|
160 // parameter will contain the old URL and other request-related information.
161 // The |new_url| parameter will contain the new URL and can be changed if
162 // desired. The |request| object cannot be modified in this callback.
165 virtual void OnResourceRedirect(CefRefPtr<CefBrowser> browser,
166 CefRefPtr<CefFrame> frame,
167 CefRefPtr<CefRequest> request,
168 CefString& new_url) {}
171 // Called on the IO thread when a resource response is received. To allow the
172 // resource to load normally return false. To redirect or retry the resource
173 // modify |request| (url, headers or post body) and return true. The
174 // |response| object cannot be modified in this callback.
177 virtual bool OnResourceResponse(CefRefPtr<CefBrowser> browser,
178 CefRefPtr<CefFrame> frame,
179 CefRefPtr<CefRequest> request,
180 CefRefPtr<CefResponse> response) {
185 // Called on the IO thread when the browser needs credentials from the user.
186 // |isProxy| indicates whether the host is a proxy server. |host| contains the
187 // hostname and |port| contains the port number. Return true to continue the
188 // request and call CefAuthCallback::Continue() either in this method or
189 // at a later time when the authentication information is available. Return
190 // false to cancel the request immediately.
192 /*--cef(optional_param=realm)--*/
193 virtual bool GetAuthCredentials(CefRefPtr<CefBrowser> browser,
194 CefRefPtr<CefFrame> frame,
196 const CefString& host,
198 const CefString& realm,
199 const CefString& scheme,
200 CefRefPtr<CefAuthCallback> callback) {
205 // Called on the IO thread when JavaScript requests a specific storage quota
206 // size via the webkitStorageInfo.requestQuota function. |origin_url| is the
207 // origin of the page making the request. |new_size| is the requested quota
208 // size in bytes. Return true to continue the request and call
209 // CefRequestCallback::Continue() either in this method or at a later time to
210 // grant or deny the request. Return false to cancel the request immediately.
213 virtual bool OnQuotaRequest(CefRefPtr<CefBrowser> browser,
214 const CefString& origin_url,
216 CefRefPtr<CefRequestCallback> callback) {
221 // Called on the UI thread to handle requests for URLs with an unknown
222 // protocol component. Set |allow_os_execution| to true to attempt execution
223 // via the registered OS protocol handler, if any.
224 // SECURITY WARNING: YOU SHOULD USE THIS METHOD TO ENFORCE RESTRICTIONS BASED
225 // ON SCHEME, HOST OR OTHER URL ANALYSIS BEFORE ALLOWING OS EXECUTION.
228 virtual void OnProtocolExecution(CefRefPtr<CefBrowser> browser,
229 const CefString& url,
230 bool& allow_os_execution) {}
233 // Called on the UI thread to handle requests for URLs with an invalid
234 // SSL certificate. Return true and call CefRequestCallback::Continue() either
235 // in this method or at a later time to continue or cancel the request. Return
236 // false to cancel the request immediately. If |callback| is empty the error
237 // cannot be recovered from and the request will be canceled automatically.
238 // If CefSettings.ignore_certificate_errors is set all invalid certificates
239 // will be accepted without calling this method.
242 virtual bool OnCertificateError(
243 CefRefPtr<CefBrowser> browser,
244 cef_errorcode_t cert_error,
245 const CefString& request_url,
246 CefRefPtr<CefSSLInfo> ssl_info,
247 CefRefPtr<CefRequestCallback> callback) {
252 // Called on the browser process IO thread before a plugin is loaded. Return
253 // true to block loading of the plugin.
255 /*--cef(optional_param=url,optional_param=policy_url)--*/
256 virtual bool OnBeforePluginLoad(CefRefPtr<CefBrowser> browser,
257 const CefString& url,
258 const CefString& policy_url,
259 CefRefPtr<CefWebPluginInfo> info) {
264 // Called on the browser process UI thread when a plugin has crashed.
265 // |plugin_path| is the path of the plugin that crashed.
268 virtual void OnPluginCrashed(CefRefPtr<CefBrowser> browser,
269 const CefString& plugin_path) {}
272 // Called on the browser process UI thread when the render view associated
273 // with |browser| is ready to receive/handle IPC messages in the render
277 virtual void OnRenderViewReady(CefRefPtr<CefBrowser> browser) {}
280 // Called on the browser process UI thread when the render process
281 // terminates unexpectedly. |status| indicates how the process
285 virtual void OnRenderProcessTerminated(CefRefPtr<CefBrowser> browser,
286 TerminationStatus status) {}
289 #endif // CEF_INCLUDE_CEF_REQUEST_HANDLER_H_