Skip to content

RequestHandler.md

Latest commit

 

History

History
295 lines (227 loc) · 10.2 KB

RequestHandler.md

File metadata and controls

295 lines (227 loc) · 10.2 KB
Raw

API categories | API index

RequestHandler (interface)

Implement this interface to handle events related to browser requests. The methods of this class will be called on the thread indicated.

The callbacks called on the IO thread may receive a frame that is already detached or gets detached while the callback runs, e.g. an iframe removed while its requests are in progress. frame.IsValid() may then return False. frame.GetBrowser() and frame.GetParent() keep working while the browser is open. Other frame methods, except GetIdentifier(), GetBrowserIdentifier() and IsValid(), raise an exception once cefpython has released the frame, which it does when the frame's JavaScript context is released and which can happen during the callback.

For requests without a browser or frame (e.g. from service workers or CefURLRequest), CefPython doesn't call OnBeforeResourceLoad, GetResourceHandler, OnResourceRedirect, CanSendCookie and CanSaveCookie. This is a limitation of CefPython's callback dispatch, not of CEF. The request then continues with default handling and an unchanged redirect, and CefPython doesn't block the cookie.

Related code snippets:

Available in upstream CEF, but not yet exposed to CEF Python:

  • OnOpenURLFromTab
  • OnSelectClientCertificate

Table of contents:

Callbacks

CanSendCookie

Parameter Type
browser Browser
frame Frame
request Request
cookie Cookie
Return bool

Called on the IO thread before a cookie is sent with a network request. Return True to allow the cookie or False to block it.

Not called for requests without a browser or frame, for which CefPython doesn't block the cookie; see the introduction above.

CanSaveCookie

Parameter Type
browser Browser
frame Frame
request Request
response Response
cookie Cookie
Return bool

Called on the IO thread before a cookie received from a network response is saved. Return True to allow the cookie or False to block it.

Not called for requests without a browser or frame, for which CefPython doesn't block the cookie; see the introduction above.

GetAuthCredentials

Parameter Type
browser Browser
origin_url string
is_proxy bool
host string
port int
realm string
scheme string
callback AuthCallback
Return bool

Called on the IO thread when the browser needs credentials from the user. |origin_url| is the origin making the authentication request. |is_proxy| 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 empty. |scheme| is the authentication scheme used, such as "basic" or "digest". Return true to continue the request and call CefAuthCallback::Continue() either in this method or at a later time when the authentication information is available. Return false to cancel the request immediately.

Pass disable-chrome-login-prompt in the switches dictionary to cef.Initialize() to route authentication challenges to this callback instead of Chromium's built-in login prompt.

The AuthCallback object methods:

  • void Continue(string username, string password)
  • void Cancel()

Example implementations:

  • Using Kivy framework: see this commit in the garden.cefpython project.
  • For Windows using WinAPI and C++. This is deprecated code from CEF Python 1: [1], [2], [3].

GetResourceHandler

Parameter Type
browser Browser
frame Frame
request Request
Return ResourceHandler

Called on the IO thread before a resource is loaded. To allow the resource to load normally return None. To specify a handler for the resource return a ResourceHandler object. The |request| object should not be modified in this callback.

The ResourceHandler object is a python class that implements the ResourceHandler callbacks. Remember to keep a strong reference to this object while resource is being loaded.

The GetResourceHandler example can be found in the old v31 "wxpython-response.py" script on Linux.

OnBeforeBrowse

Parameter Type
browser Browser
frame Frame
request Request
user_gesture bool
is_redirect bool
Return bool

Description from upstream CEF:

Called on the UI thread before browser navigation. Return true to cancel the navigation or false to allow the navigation to proceed. The |request| object cannot be modified in this callback. CefLoadHandler::OnLoadingStateChange will be called twice in all cases. If the navigation is allowed CefLoadHandler::OnLoadStart and CefLoadHandler::OnLoadEnd will be called. If the navigation is canceled CefLoadHandler::OnLoadError will be called with an |errorCode| value of ERR_ABORTED. The |user_gesture| value will be true if the browser navigated via explicit user gesture (e.g. clicking a link) or false if it navigated automatically (e.g. via the DomContentLoaded event).

OnBeforeResourceLoad

Parameter Type
browser Browser
frame Frame
request Request
Return bool

Called on the IO thread before a resource request is loaded. The |request| object may be modified. To cancel the request return true otherwise return false.

_OnCertificateError

Parameter Type
cert_error NetworkError
request_url string
callback RequestCallback
Return bool

This callback is not associated with any specific browser, thus you must call cefpython.SetGlobalClientCallback() to use it. The callback name was prefixed with "_" to distinguish this special behavior.

Called on the UI thread to handle requests for URLs with an invalid SSL certificate. Return true and call CefRequestCallback::Continue() either in this method or at a later time to continue or cancel the request. Return false to cancel the request immediately.

The RequestCallback object methods:

  • void Continue(bool allow)
  • void Cancel()

OnResourceRedirect

Parameter Type
browser Browser
frame Frame
old_url string
new_url_out list[string]
request Request
response Response
Return void

Description from upstream CEF:

Called on the IO thread when a resource load is redirected. The |request| parameter will contain the old URL and other request-related information. The |response| parameter will contain the response that resulted in the redirect. The |new_url| parameter will contain the new URL and can be changed if desired. The |request| object cannot be modified in this callback.

OnResourceResponse
Return void

Available in upstream CEF, but not yet exposed to CEF Python. See Issue #229.

You can implement this functionality by using ResourceHandler and WebRequest / WebRequestClient. For an example see the _OnResourceResponse() method in the old v31 [wxpython-response.py] example.

OnProtocolExecution

Parameter Type
browser Browser
url string
allow_execution_out list[bool]
Return void

Called on the IO thread to handle requests for URLs with an unknown protocol component. Set |allow_execution_out[0]| to True to attempt execution via the registered OS protocol handler, if any.

SECURITY NOTE: You should use this callback to enforce restrictions based on scheme, host or other url analysis before allowing OS execution.

There's no default implementation for OnProtocolExecution on Linux, you have to make OS system call on your own. You probably also need to use LoadHandler::OnLoadError() when implementing this on Linux.

OnRendererProcessTerminated

Parameter Type
browser Browser
status TerminationStatus
error_code int
error_string str
Return void

Called 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 non-normal process exit codes and platform-specific crash values (for example, a Posix signal or Windows hardware exception).

TerminationStatus constants in the cefpython module:

  • TS_ABNORMAL_TERMINATION - Non-zero exit status.
  • TS_PROCESS_WAS_KILLED - SIGKILL or task manager kill.
  • TS_PROCESS_CRASHED - Segmentation fault.
  • TS_PROCESS_OOM - Out of memory. Some platforms may use TS_PROCESS_CRASHED instead.
  • TS_LAUNCH_FAILED - Child process never launched.
  • TS_INTEGRITY_FAILURE - On Windows, the OS terminated the process due to code integrity failure.