CefRequestHandler

Header: cef_request_handler.h
Interfaces: CefSelectClientCertificateCallback, CefRequestHandler
Category: Browser Handlers

Overview

User-implemented handler interfaces returned from CefClient and registered with CefBrowserHost.

CefSelectClientCertificateCallback

Source File: include/cef_request_handler.h

Process / Thread Context: Browser Process / UI Thread (called from CefRequestHandler::OnSelectClientCertificate, which is documented as UI thread).

Purpose: Callback interface used to select a client certificate for authentication. It is a USER-CALLED interface (source=library): CEF creates and passes it to CefRequestHandler::OnSelectClientCertificate, and the application invokes Select() when it has chosen a certificate (or none).

Methods

void Select(CefRefPtr<CefX509Certificate> cert)

Parameters:

• cert: The X.509 certificate to use for client authentication. Pass NULL (or do not call Select) to continue without using any certificate.

Return Value: No return value. Calling with NULL means "no client certificate should be used."

Usage Instruction: Call exactly once, either synchronously from inside OnSelectClientCertificate or asynchronously after the application has chosen a cert from its own UI. Selecting NULL is valid and means continue without sending a client cert.

Threading Constraint: Header does not explicitly state which thread Select must be called on; the originating handler method is UI thread, so it is implied to be UI thread.

Usage Example

// From inside a CefRequestHandler implementation:
bool MyRequestHandler::OnSelectClientCertificate(
    CefRefPtr<CefBrowser> browser,
    bool isProxy,
    const CefString& host,
    int port,
    const X509CertificateList& certificates,
    CefRefPtr<CefSelectClientCertificateCallback> callback) {
  // Show custom picker; on completion:
  if (!certificates.empty())
    callback->Select(certificates.front());
  else
    callback->Select(nullptr);  // No client cert
  return true;
}

CefRequestHandler

Source File: include/cef_request_handler.h

Process / Thread Context: Browser process — mixed UI thread and IO thread (each method documents its own thread). USER-IMPLEMENTED (source=client); returned from CefClient::GetRequestHandler().

Purpose: Handle events related to browser-level requests: pre-navigation gating, resource-request-handler selection, HTTP authentication, certificate errors, client-certificate selection, render-process lifecycle (ready/unresponsive/responsive/terminated), and main-frame document availability.

Methods

bool OnBeforeBrowse(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, CefRefPtr<CefRequest> request, bool user_gesture, bool is_redirect)

Parameters:

• browser: The browser instance performing the navigation.
• frame: The frame being navigated.
• request: The request about to be sent; cannot be modified in this callback.
• user_gesture: true if the navigation was triggered by an explicit user gesture (e.g. link click); false if automatic (e.g. DomContentLoaded).
• is_redirect: true if this is a redirected navigation.

Return Value: true cancels the navigation; false allows it. Cancellation results in CefLoadHandler::OnLoadError with ERR_ABORTED.

Usage Instruction: Inspect or block navigations before they start. CefLoadHandler::OnLoadingStateChange is called twice in all cases.

Threading Constraint: "Called on the UI thread before browser navigation."

bool OnOpenURLFromTab(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, const CefString& target_url, WindowOpenDisposition target_disposition, bool user_gesture)

Parameters:

• target_url: The URL the user wants to open.
• target_disposition: A cef_window_open_disposition_t indicating intended target (current tab, new tab, new window, etc.).
• user_gesture: true if user-initiated.

Return Value: true cancels the navigation; false allows it to proceed in the source browser's top-level frame.

Usage Instruction: Called before OnBeforeBrowse in special cases such as middle-click / Ctrl+click links and certain cross-origin navigations to/from file URLs.

Threading Constraint: "Called on the UI thread before OnBeforeBrowse in certain limited cases."

CefRefPtr<CefResourceRequestHandler> GetResourceRequestHandler(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, CefRefPtr<CefRequest> request, bool is_navigation, bool is_download, const CefString& request_initiator, bool& disable_default_handling)

Parameters:

• request: The request contents; cannot be modified here.
• is_navigation: true if the resource request is itself a navigation.
• is_download: true if the resource request is a download.
• request_initiator: Origin (scheme + domain) of the page that initiated the request; may be empty.

Return Value: Return NULL to allow default handling; return a CefResourceRequestHandler to specify custom handling. Returning NULL also causes the same method to be called on the associated CefRequestContextHandler, if any.

Usage Instruction: Provide per-request (or per-context) interception of resource loads. This is the entry point into the entire CefResourceRequestHandler pipeline.

Threading Constraint: "Called on the browser process IO thread before a resource request is initiated."

bool GetAuthCredentials(CefRefPtr<CefBrowser> browser, const CefString& origin_url, bool isProxy, const CefString& host, int port, const CefString& realm, const CefString& scheme, CefRefPtr<CefAuthCallback> callback)

Parameters:

• browser: The browser.
• origin_url: Origin making the authentication request.
• isProxy: true if the host being authenticated against is a proxy.
• host: Hostname.
• port: Port number.
• realm: Realm of the challenge; may be empty.
• scheme: Auth scheme ("basic", "digest", …); empty for FTP source.
• callback: Call CefAuthCallback::Continue() or Cancel() to resolve.

Return Value: true to continue the request and (synchronously or later) call callback; false to cancel immediately.

Usage Instruction: Implement to provide credentials for HTTP/FTP authentication.

Threading Constraint: "Called on the IO thread when the browser needs credentials from the user."

bool OnCertificateError(CefRefPtr<CefBrowser> browser, cef_errorcode_t cert_error, const CefString& request_url, CefRefPtr<CefSSLInfo> ssl_info, CefRefPtr<CefCallback> callback)

Parameters:

• browser: The browser.
• cert_error: The certificate error code.
• request_url: The URL with the invalid certificate.
• ssl_info: SSL info for the connection.
• callback: Use Continue() / Cancel() to resolve.

Return Value: true to handle asynchronously (call callback); false to cancel immediately.

Usage Instruction: If cef_settings_t.ignore_certificate_errors is set, this method is bypassed and all invalid certs are accepted.

Threading Constraint: "Called on the UI thread to handle requests for URLs with an invalid SSL certificate."

bool OnSelectClientCertificate(CefRefPtr<CefBrowser> browser, bool isProxy, const CefString& host, int port, const X509CertificateList& certificates, CefRefPtr<CefSelectClientCertificateCallback> callback)

Parameters:

• browser: The browser.
• isProxy: true if the host is an HTTPS proxy (vs origin server).
• certificates: Pre-pruned list of certs the server will trust; may be empty.
• callback: Call Select(cert) to choose; Select(NULL) or no call continues without a cert.

Return Value: false = use default behavior (show picker if list non-empty; continue without cert if empty). true = application will call Select itself.

Usage Instruction: Provide a custom client-certificate picker UI.

Threading Constraint: "Called on the UI thread when a client certificate is being requested for authentication."

void OnRenderViewReady(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: The browser whose render view is ready.

Return Value: None.

Usage Instruction: Use to send IPC messages to a freshly ready render view.

Threading Constraint: "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."

bool OnRenderProcessUnresponsive(CefRefPtr<CefBrowser> browser, CefRefPtr<CefUnresponsiveProcessCallback> callback)

Parameters:

• browser: Browser whose render process is unresponsive.
• callback: Use Wait() to reset the timer, or Terminate() to kill the process.

Return Value: false = default behavior (Alloy: continue waiting; Chrome: show "Page unresponsive" dialog). true = application handles; either don't call the callback (continue waiting silently), or call Wait() (reset timer) or Terminate() (kill the process).

Usage Instruction: Fired after the render process is unresponsive for at least 15 seconds. Depends on the hang monitor (disabled by --disable-hang-monitor).

Threading Constraint: "Called on the browser process UI thread when the render process is unresponsive."

void OnRenderProcessResponsive(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: Browser whose process became responsive again.

Return Value: None.

Usage Instruction: Pair with OnRenderProcessUnresponsive to track recovery.

Threading Constraint: "Called on the browser process UI thread when the render process becomes responsive."

void OnRenderProcessTerminated(CefRefPtr<CefBrowser> browser, TerminationStatus status, int error_code, const CefString& error_string)

Parameters:

• browser: The browser.
• status: cef_termination_status_t describing how the process ended.
• error_code: Non-normal exit code (e.g. cef_resultcode_t or platform-specific signal/exception code).
• error_string: Chrome "Aw, Snap!" style error string.

Return Value: None.

Usage Instruction: Clean up or recover state when a render process crashes.

Threading Constraint: "Called on the browser process UI thread when the render process terminates unexpectedly."

void OnDocumentAvailableInMainFrame(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: The browser.

Return Value: None.

Usage Instruction: Called when the main frame's window.document object has been created.

Threading Constraint: "Called on the browser process UI thread when the window.document object of the main frame has been created."

Usage Example

class MyClient : public CefClient, public CefRequestHandler {
 public:
  CefRefPtr<CefRequestHandler> GetRequestHandler() override { return this; }

  bool OnBeforeBrowse(CefRefPtr<CefBrowser> browser,
                      CefRefPtr<CefFrame> frame,
                      CefRefPtr<CefRequest> request,
                      bool user_gesture,
                      bool is_redirect) override {
    // Block navigations to known-bad domains
    if (request->GetURL().ToString().find("malicious.example") != std::string::npos)
      return true;
    return false;
  }

  CefRefPtr<CefResourceRequestHandler> GetResourceRequestHandler(
      CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame,
      CefRefPtr<CefRequest> request, bool is_navigation, bool is_download,
      const CefString& request_initiator, bool& disable_default_handling) override {
    return new MyResourceRequestHandler();  // see file 2
  }

  bool GetAuthCredentials(CefRefPtr<CefBrowser>, const CefString&, bool,
                          const CefString&, int, const CefString&,
                          const CefString&, CefRefPtr<CefAuthCallback> cb) override {
    cb->Continue("user", "pass");
    return true;
  }

  // ... OnCertificateError, OnSelectClientCertificate, OnRenderViewReady,
  // OnRenderProcessUnresponsive, OnRenderProcessResponsive,
  // OnRenderProcessTerminated, OnDocumentAvailableInMainFrame, OnOpenURLFromTab
  IMPLEMENT_REFCOUNTING(MyClient);
};