cef/include/capi/cef_request_handler_capi.h

288 lines
13 KiB
C
Raw Normal View History

// Copyright (c) 2024 Marshall A. Greenblatt. 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 name Chromium Embedded
// Framework nor the names of its contributors may be used to endorse
// or promote products derived from this software without specific prior
// written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// ---------------------------------------------------------------------------
//
// This file was generated by the CEF translator tool and should not edited
// by hand. See the translator.README.txt file in the tools directory for
// more information.
//
// $hash=2e8b5c5107f61e3d4c333dc02c76a9f30cd0cf83$
//
#ifndef CEF_INCLUDE_CAPI_CEF_REQUEST_HANDLER_CAPI_H_
#define CEF_INCLUDE_CAPI_CEF_REQUEST_HANDLER_CAPI_H_
#pragma once
#include "include/capi/cef_auth_callback_capi.h"
#include "include/capi/cef_base_capi.h"
#include "include/capi/cef_browser_capi.h"
#include "include/capi/cef_callback_capi.h"
#include "include/capi/cef_frame_capi.h"
#include "include/capi/cef_request_capi.h"
Implement NetworkService request interception/handling (see issue #2622). Implementation notes: - Chromium change: CookieMonster::SetCookieableSchemes needs to be called immediately after the CookieMonster is created in NetworkContext:: ApplyContextParamsToBuilder. Add a Profile::GetCookieableSchemes method and NetworkContextParams.cookieable_schemes member (set from ProfileNetworkContextService::CreateNetworkContextParams) to support that. - Chromium change: Add a ContentBrowserClient::HandleExternalProtocol variant that exposes additional NetworkService request information. - GetResourceResponseFilter is not yet implemented. API changes: - Resource-related callbacks have been moved from CefRequestHandler to a new CefResourceRequestHandler interface which is returned via the GetResourceRequestHandler method. If the CefRequestHandler declines to handle a resource it can optionally be handled by the CefRequestContextHandler, if any, associated with the loading context. - The OnProtocolExecution callback has been moved from CefRequestHandler to CefResourceRequestHandler and will be called if a custom scheme request is unhandled. - Cookie send/save permission callbacks have been moved from CefRequestHandler and CefResourceHandler to CefResourceRequestHandler. - New methods added to CefResourceHandler that better match NetworkService execution sequence expectations. The old methods are now deprecated. - New methods added to CefRequest and CefResponse. Known behavior changes with the NetworkService implementation: - Modifying the |new_url| parameter in OnResourceRedirect will no longer result in the method being called an additional time (likely a bug in the old implementation). - Modifying the request URL in OnResourceResponse would previously cause a redirect. This behavior is now deprecated because the NetworkService does not support this functionality when using default network loaders. Temporary support has been added in combination with CefResourceHandler usage only. - Other changes to the request object in OnResourceResponse will now cause the request to be restarted. This means that OnBeforeResourceLoad, etc, will be called an additional time with the new request information. - CefResponse::GetMimeType will now be empty for non-200 responses. - Requests using custom schemes can now be handled via CefResourceRequestHandler with the same callback behavior as builtin schemes. - Redirects of custom scheme requests will now be followed as expected. - Default handling of builtin schemes can now be disabled by setting |disable_default_handling| to true in GetResourceRequestHandler. - Unhandled requests (custom scheme or builtin scheme with default handling disabled) will fail with an CefResponse::GetError value of ERR_UNKNOWN_URL_SCHEME. - The CefSchemeHandlerFactory::Create callback will now include cookie headers. To test: - Run `cefclient --enable-network-service`. All resources should load successfully (this tests the transparent proxy capability). - All tests pass with NetworkService disabled. - The following tests pass with NetworkService enabled: - CookieTest.* - FrameTest.* (excluding .*Nav) - NavigationTest.* (excluding .Redirect*) - RequestHandlerTest.* - RequestContextTest.Basic* - RequestContextTest.Popup* - RequestTest.* - ResourceManagerTest.* - ResourceRequestHandlerTest.* (excluding .Filter*) - SchemeHandlerTest.* - StreamResourceHandlerTest.*
2019-04-24 04:50:25 +02:00
#include "include/capi/cef_resource_request_handler_capi.h"
#include "include/capi/cef_ssl_info_capi.h"
#include "include/capi/cef_unresponsive_process_callback_capi.h"
#include "include/capi/cef_x509_certificate_capi.h"
#ifdef __cplusplus
extern "C" {
#endif
///
/// Callback structure used to select a client certificate for authentication.
///
typedef struct _cef_select_client_certificate_callback_t {
///
/// Base structure.
///
cef_base_ref_counted_t base;
///
/// Chooses the specified certificate for client certificate authentication.
/// NULL value means that no client certificate should be used.
///
void(CEF_CALLBACK* select)(
struct _cef_select_client_certificate_callback_t* self,
struct _cef_x509certificate_t* cert);
} cef_select_client_certificate_callback_t;
///
/// Implement this structure to handle events related to browser requests. The
/// functions of this structure will be called on the thread indicated.
///
typedef struct _cef_request_handler_t {
///
/// Base structure.
///
cef_base_ref_counted_t base;
///
/// Called on the UI thread before browser navigation. Return true (1) to
/// cancel the navigation or false (0) to allow the navigation to proceed. The
/// |request| object cannot be modified in this callback.
/// cef_load_handler_t::OnLoadingStateChange will be called twice in all
/// cases. If the navigation is allowed cef_load_handler_t::OnLoadStart and
/// cef_load_handler_t::OnLoadEnd will be called. If the navigation is
/// canceled cef_load_handler_t::OnLoadError will be called with an
/// |errorCode| value of ERR_ABORTED. The |user_gesture| value will be true
/// (1) if the browser navigated via explicit user gesture (e.g. clicking a
/// link) or false (0) if it navigated automatically (e.g. via the
/// DomContentLoaded event).
///
int(CEF_CALLBACK* on_before_browse)(struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
struct _cef_frame_t* frame,
struct _cef_request_t* request,
int user_gesture,
int is_redirect);
///
/// Called on the UI thread before OnBeforeBrowse in certain limited cases
/// where navigating a new or different browser might be desirable. This
/// includes user-initiated navigation that might open in a special way (e.g.
/// links clicked via middle-click or ctrl + left-click) and certain types of
/// cross-origin navigation initiated from the renderer process (e.g.
/// navigating the top-level frame to/from a file URL). The |browser| and
/// |frame| values represent the source of the navigation. The
/// |target_disposition| value indicates where the user intended to navigate
/// the browser based on standard Chromium behaviors (e.g. current tab, new
/// tab, etc). The |user_gesture| value will be true (1) if the browser
/// navigated via explicit user gesture (e.g. clicking a link) or false (0) if
/// it navigated automatically (e.g. via the DomContentLoaded event). Return
/// true (1) to cancel the navigation or false (0) to allow the navigation to
/// proceed in the source browser's top-level frame.
///
int(CEF_CALLBACK* on_open_urlfrom_tab)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
struct _cef_frame_t* frame,
const cef_string_t* target_url,
cef_window_open_disposition_t target_disposition,
int user_gesture);
///
/// Called on the browser process IO thread before a resource request is
/// initiated. The |browser| and |frame| values represent the source of the
/// request. |request| represents the request contents and cannot be modified
/// in this callback. |is_navigation| will be true (1) if the resource request
/// is a navigation. |is_download| will be true (1) if the resource request is
/// a download. |request_initiator| is the origin (scheme + domain) of the
/// page that initiated the request. Set |disable_default_handling| to true
/// (1) to disable default handling of the request, in which case it will need
/// to be handled via cef_resource_request_handler_t::GetResourceHandler or it
/// will be canceled. To allow the resource load to proceed with default
/// handling return NULL. To specify a handler for the resource return a
/// cef_resource_request_handler_t object. If this callback returns NULL the
/// same function will be called on the associated
/// cef_request_context_handler_t, if any.
Implement NetworkService request interception/handling (see issue #2622). Implementation notes: - Chromium change: CookieMonster::SetCookieableSchemes needs to be called immediately after the CookieMonster is created in NetworkContext:: ApplyContextParamsToBuilder. Add a Profile::GetCookieableSchemes method and NetworkContextParams.cookieable_schemes member (set from ProfileNetworkContextService::CreateNetworkContextParams) to support that. - Chromium change: Add a ContentBrowserClient::HandleExternalProtocol variant that exposes additional NetworkService request information. - GetResourceResponseFilter is not yet implemented. API changes: - Resource-related callbacks have been moved from CefRequestHandler to a new CefResourceRequestHandler interface which is returned via the GetResourceRequestHandler method. If the CefRequestHandler declines to handle a resource it can optionally be handled by the CefRequestContextHandler, if any, associated with the loading context. - The OnProtocolExecution callback has been moved from CefRequestHandler to CefResourceRequestHandler and will be called if a custom scheme request is unhandled. - Cookie send/save permission callbacks have been moved from CefRequestHandler and CefResourceHandler to CefResourceRequestHandler. - New methods added to CefResourceHandler that better match NetworkService execution sequence expectations. The old methods are now deprecated. - New methods added to CefRequest and CefResponse. Known behavior changes with the NetworkService implementation: - Modifying the |new_url| parameter in OnResourceRedirect will no longer result in the method being called an additional time (likely a bug in the old implementation). - Modifying the request URL in OnResourceResponse would previously cause a redirect. This behavior is now deprecated because the NetworkService does not support this functionality when using default network loaders. Temporary support has been added in combination with CefResourceHandler usage only. - Other changes to the request object in OnResourceResponse will now cause the request to be restarted. This means that OnBeforeResourceLoad, etc, will be called an additional time with the new request information. - CefResponse::GetMimeType will now be empty for non-200 responses. - Requests using custom schemes can now be handled via CefResourceRequestHandler with the same callback behavior as builtin schemes. - Redirects of custom scheme requests will now be followed as expected. - Default handling of builtin schemes can now be disabled by setting |disable_default_handling| to true in GetResourceRequestHandler. - Unhandled requests (custom scheme or builtin scheme with default handling disabled) will fail with an CefResponse::GetError value of ERR_UNKNOWN_URL_SCHEME. - The CefSchemeHandlerFactory::Create callback will now include cookie headers. To test: - Run `cefclient --enable-network-service`. All resources should load successfully (this tests the transparent proxy capability). - All tests pass with NetworkService disabled. - The following tests pass with NetworkService enabled: - CookieTest.* - FrameTest.* (excluding .*Nav) - NavigationTest.* (excluding .Redirect*) - RequestHandlerTest.* - RequestContextTest.Basic* - RequestContextTest.Popup* - RequestTest.* - ResourceManagerTest.* - ResourceRequestHandlerTest.* (excluding .Filter*) - SchemeHandlerTest.* - StreamResourceHandlerTest.*
2019-04-24 04:50:25 +02:00
///
struct _cef_resource_request_handler_t*(
CEF_CALLBACK* get_resource_request_handler)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
struct _cef_frame_t* frame,
struct _cef_request_t* request,
Implement NetworkService request interception/handling (see issue #2622). Implementation notes: - Chromium change: CookieMonster::SetCookieableSchemes needs to be called immediately after the CookieMonster is created in NetworkContext:: ApplyContextParamsToBuilder. Add a Profile::GetCookieableSchemes method and NetworkContextParams.cookieable_schemes member (set from ProfileNetworkContextService::CreateNetworkContextParams) to support that. - Chromium change: Add a ContentBrowserClient::HandleExternalProtocol variant that exposes additional NetworkService request information. - GetResourceResponseFilter is not yet implemented. API changes: - Resource-related callbacks have been moved from CefRequestHandler to a new CefResourceRequestHandler interface which is returned via the GetResourceRequestHandler method. If the CefRequestHandler declines to handle a resource it can optionally be handled by the CefRequestContextHandler, if any, associated with the loading context. - The OnProtocolExecution callback has been moved from CefRequestHandler to CefResourceRequestHandler and will be called if a custom scheme request is unhandled. - Cookie send/save permission callbacks have been moved from CefRequestHandler and CefResourceHandler to CefResourceRequestHandler. - New methods added to CefResourceHandler that better match NetworkService execution sequence expectations. The old methods are now deprecated. - New methods added to CefRequest and CefResponse. Known behavior changes with the NetworkService implementation: - Modifying the |new_url| parameter in OnResourceRedirect will no longer result in the method being called an additional time (likely a bug in the old implementation). - Modifying the request URL in OnResourceResponse would previously cause a redirect. This behavior is now deprecated because the NetworkService does not support this functionality when using default network loaders. Temporary support has been added in combination with CefResourceHandler usage only. - Other changes to the request object in OnResourceResponse will now cause the request to be restarted. This means that OnBeforeResourceLoad, etc, will be called an additional time with the new request information. - CefResponse::GetMimeType will now be empty for non-200 responses. - Requests using custom schemes can now be handled via CefResourceRequestHandler with the same callback behavior as builtin schemes. - Redirects of custom scheme requests will now be followed as expected. - Default handling of builtin schemes can now be disabled by setting |disable_default_handling| to true in GetResourceRequestHandler. - Unhandled requests (custom scheme or builtin scheme with default handling disabled) will fail with an CefResponse::GetError value of ERR_UNKNOWN_URL_SCHEME. - The CefSchemeHandlerFactory::Create callback will now include cookie headers. To test: - Run `cefclient --enable-network-service`. All resources should load successfully (this tests the transparent proxy capability). - All tests pass with NetworkService disabled. - The following tests pass with NetworkService enabled: - CookieTest.* - FrameTest.* (excluding .*Nav) - NavigationTest.* (excluding .Redirect*) - RequestHandlerTest.* - RequestContextTest.Basic* - RequestContextTest.Popup* - RequestTest.* - ResourceManagerTest.* - ResourceRequestHandlerTest.* (excluding .Filter*) - SchemeHandlerTest.* - StreamResourceHandlerTest.*
2019-04-24 04:50:25 +02:00
int is_navigation,
int is_download,
const cef_string_t* request_initiator,
int* disable_default_handling);
///
/// Called on the IO thread when the browser needs credentials from the user.
/// |origin_url| is the origin making this authentication request. |isProxy|
/// indicates whether the host is a proxy server. |host| contains the hostname
/// and |port| contains the port number. |realm| is the realm of the challenge
/// and may be NULL. |scheme| is the authentication scheme used, such as
/// "basic" or "digest", and will be NULL if the source of the request is an
/// FTP server. Return true (1) to continue the request and call
/// cef_auth_callback_t::cont() either in this function or at a later time
/// when the authentication information is available. Return false (0) to
/// cancel the request immediately.
///
int(CEF_CALLBACK* get_auth_credentials)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
const cef_string_t* origin_url,
int isProxy,
const cef_string_t* host,
int port,
const cef_string_t* realm,
const cef_string_t* scheme,
struct _cef_auth_callback_t* callback);
///
/// Called on the UI thread to handle requests for URLs with an invalid SSL
/// certificate. Return true (1) and call cef_callback_t functions either in
/// this function or at a later time to continue or cancel the request. Return
/// false (0) to cancel the request immediately. If
/// cef_settings_t.ignore_certificate_errors is set all invalid certificates
/// will be accepted without calling this function.
///
int(CEF_CALLBACK* on_certificate_error)(struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
cef_errorcode_t cert_error,
const cef_string_t* request_url,
struct _cef_sslinfo_t* ssl_info,
struct _cef_callback_t* callback);
///
/// Called on the UI thread when a client certificate is being requested for
/// authentication. Return false (0) to use the default behavior and
/// automatically select the first certificate available. Return true (1) and
/// call cef_select_client_certificate_callback_t::Select either in this
/// function or at a later time to select a certificate. Do not call Select or
/// call it with NULL to continue without using any certificate. |isProxy|
/// indicates whether the host is an HTTPS proxy or the origin server. |host|
/// and |port| contains the hostname and port of the SSL server.
/// |certificates| is the list of certificates to choose from; this list has
/// already been pruned by Chromium so that it only contains certificates from
/// issuers that the server trusts.
///
int(CEF_CALLBACK* on_select_client_certificate)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
int isProxy,
const cef_string_t* host,
int port,
size_t certificatesCount,
struct _cef_x509certificate_t* const* certificates,
struct _cef_select_client_certificate_callback_t* callback);
///
/// Called on the browser process UI thread when the render view associated
/// with |browser| is ready to receive/handle IPC messages in the render
/// process.
///
void(CEF_CALLBACK* on_render_view_ready)(struct _cef_request_handler_t* self,
struct _cef_browser_t* browser);
///
/// Called on the browser process UI thread when the render process is
/// unresponsive as indicated by a lack of input event processing for at least
/// 15 seconds. Return false (0) for the default behavior which is an
/// indefinite wait with the Alloy runtime or display of the "Page
/// unresponsive" dialog with the Chrome runtime. Return true (1) and don't
/// execute the callback for an indefinite wait without display of the Chrome
/// runtime dialog. Return true (1) and call
/// cef_unresponsive_process_callback_t::Wait either in this function or at a
/// later time to reset the wait timer, potentially triggering another call to
/// this function if the process remains unresponsive. Return true (1) and
/// call cef_unresponsive_process_callback_t:: Terminate either in this
/// function or at a later time to terminate the unresponsive process,
/// resulting in a call to OnRenderProcessTerminated.
/// OnRenderProcessResponsive will be called if the process becomes responsive
/// after this function is called. This functionality depends on the hang
/// monitor which can be disabled by passing the `--disable-hang-monitor`
/// command-line flag.
///
int(CEF_CALLBACK* on_render_process_unresponsive)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
struct _cef_unresponsive_process_callback_t* callback);
///
/// Called on the browser process UI thread when the render process becomes
/// responsive after previously being unresponsive. See documentation on
/// OnRenderProcessUnresponsive.
///
void(CEF_CALLBACK* on_render_process_responsive)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser);
///
/// Called on the browser process UI thread when the render process terminates
/// unexpectedly. |status| indicates how the process terminated. |error_code|
/// and |error_string| represent the error that would be displayed in Chrome's
/// "Aw, Snap!" view. Possible |error_code| values include cef_resultcode_t
/// non-normal exit values and platform-specific crash values (for example, a
/// Posix signal or Windows hardware exception).
///
void(CEF_CALLBACK* on_render_process_terminated)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
cef_termination_status_t status,
int error_code,
const cef_string_t* error_string);
Add support for direct DevTools protocol messaging (fixes issue #2961). This change allows the client to directly send and receive DevTools protocol messages (send method calls, and receive method results and events) without requiring a DevTools front-end or remote-debugging session. This change includes additional supporting changes: - Add a new CefRequestHandler::OnDocumentAvailableInMainFrame callback (see issue #1454). - Add a CefParseJSON variant that accepts a UTF8-encoded buffer. - Add a `--devtools-protocol-log-file=<path>` command-line flag for logging protocol messages sent to/from the DevTools front-end while it is displayed. This is useful for understanding existing DevTools protocol usage. - Add a new "libcef_static_unittests" executable target to support light-weight unit tests of libcef_static internals (e.g. without requiring exposure via the CEF API). Files to be unittested are placed in the new "libcef_static_unittested" source_set which is then included by both the existing libcef_static library and the new unittests executable target. - Linux: Remove use_bundled_fontconfig=false, which is no longer required and causes unittest build errors (see issue #2424). This change also adds a cefclient demo for configuring offline mode using the DevTools protocol (fixes issue #245). This is controlled by the "Offline mode" context menu option and the `--offline` command-line switch which will launch cefclient in offline mode. When cefclient is offline all network requests will fail with ERR_INTERNET_DISCONNECTED and navigator.onLine will return false when called from JavaScript in any frame. This mode is per-browser so newly created browser windows will have the default mode. Note that configuring offline mode in this way will not update the Network tab UI ("Throtting" option) in a displayed DevTools front-end instance.
2020-06-13 02:54:08 +02:00
///
/// Called on the browser process UI thread when the window.document object of
/// the main frame has been created.
Add support for direct DevTools protocol messaging (fixes issue #2961). This change allows the client to directly send and receive DevTools protocol messages (send method calls, and receive method results and events) without requiring a DevTools front-end or remote-debugging session. This change includes additional supporting changes: - Add a new CefRequestHandler::OnDocumentAvailableInMainFrame callback (see issue #1454). - Add a CefParseJSON variant that accepts a UTF8-encoded buffer. - Add a `--devtools-protocol-log-file=<path>` command-line flag for logging protocol messages sent to/from the DevTools front-end while it is displayed. This is useful for understanding existing DevTools protocol usage. - Add a new "libcef_static_unittests" executable target to support light-weight unit tests of libcef_static internals (e.g. without requiring exposure via the CEF API). Files to be unittested are placed in the new "libcef_static_unittested" source_set which is then included by both the existing libcef_static library and the new unittests executable target. - Linux: Remove use_bundled_fontconfig=false, which is no longer required and causes unittest build errors (see issue #2424). This change also adds a cefclient demo for configuring offline mode using the DevTools protocol (fixes issue #245). This is controlled by the "Offline mode" context menu option and the `--offline` command-line switch which will launch cefclient in offline mode. When cefclient is offline all network requests will fail with ERR_INTERNET_DISCONNECTED and navigator.onLine will return false when called from JavaScript in any frame. This mode is per-browser so newly created browser windows will have the default mode. Note that configuring offline mode in this way will not update the Network tab UI ("Throtting" option) in a displayed DevTools front-end instance.
2020-06-13 02:54:08 +02:00
///
void(CEF_CALLBACK* on_document_available_in_main_frame)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser);
} cef_request_handler_t;
#ifdef __cplusplus
}
#endif
#endif // CEF_INCLUDE_CAPI_CEF_REQUEST_HANDLER_CAPI_H_