CefURLRequest

Header: cef_urlrequest.h
Interfaces: CefURLRequest, CefURLRequestClient
Category: System Utilities

Overview

Tasks, threads, parsers, streams, cookies, URL requests, scheme registration, and constant tables.

CefURLRequest

Source File: include/cef_urlrequest.h

Process / Thread Context: Browser Process or Render Process — URL requests can be created on any valid CEF thread in either the browser or render process. Once created, the methods of the URL request object must be accessed on the same thread that created it.

Purpose: Class used to make a URL request. URL requests are not associated with a browser instance so no CefClient callbacks will be executed. Used for standalone HTTP/HTTPS/network requests that bypass browser-level callbacks.

Methods

static CefRefPtr<CefURLRequest> Create(CefRefPtr<CefRequest> request, CefRefPtr<CefURLRequestClient> client, CefRefPtr<CefRequestContext> request_context)

Parameters:

• request: The CefRequest describing the URL, method, headers and optional POST data.
• client: A CefURLRequestClient implementation that receives progress, completion, and download callbacks.
• request_context: Optional request context. If empty the global request context is used.

Return Value: Returns the new CefURLRequest instance. The request object passed in is marked as read-only after this call.

Usage Instruction: Use to issue ad-hoc HTTP requests from any CEF thread. A request created with this method may only originate from the browser process; for an in-renderer request that should be associated with a frame, use CefFrame::CreateURLRequest instead. POST data may only contain a single element of type PDE_TYPE_FILE or PDE_TYPE_BYTES. The request may be intercepted by CefResourceRequestHandler or CefSchemeHandlerFactory.

Threading Constraint: Once created, the methods of the URL request object must be accessed on the same thread that created it.

virtual CefRefPtr<CefRequest> GetRequest()

Parameters:

• None.

Return Value: Returns the request object used to create this URL request. The returned object is read-only and should not be modified.

Usage Instruction: Use to inspect the originating request (URL, method, headers, POST data).

Threading Constraint: Same thread that created the request.

virtual CefRefPtr<CefURLRequestClient> GetClient()

Parameters:

• None.

Return Value: Returns the request error if status is UR_CANCELED or UR_FAILED, or 0 (ERR_NONE) otherwise.

Usage Instruction: Call from OnRequestComplete when status is UR_CANCELED/UR_FAILED to retrieve the network error code.

Threading Constraint: Same thread that created the request.

virtual CefRefPtr<CefResponse> GetResponse()

Parameters:

• None.

Return Value: Returns the response, or NULL if no response information is available. Response information will only be available after the upload has completed. The returned object is read-only.

Usage Instruction: Call from OnRequestComplete (or in OnDownloadData) to read response headers, status code and mime type.

Threading Constraint: Same thread that created the request.

virtual bool ResponseWasCached()

Parameters:

• None.

Return Value: Returns true if the response body was served from the cache, including responses for which revalidation was required.

Usage Instruction: Use to decide whether to refresh, log, or skip work based on whether the resource came from cache.

Threading Constraint: Same thread that created the request.

virtual void Cancel()

Parameters:

• None.

Return Value: Returns void. Cancels the in-flight request; the eventual OnRequestComplete will report UR_CANCELED.

Usage Instruction: Call from any thread to abort the request. After Cancel() returns, do not issue further work on the request.

Threading Constraint: Same thread that created the request.

Usage Example

class MyClient : public CefURLRequestClient {
 public:
  CefRefPtr<CefURLRequest> request_;
  std::string body_;

  void Start() {
    CefRefPtr<CefRequest> req = CefRequest::Create();
    req->SetURL("https://example.com/api");
    req->SetMethod("GET");
    req->SetFlags(UR_FLAG_NO_RETRY_URL);
    // Browser-process only — render process must use CefFrame::CreateURLRequest.
    request_ = CefURLRequest::Create(req, this, nullptr);
  }

  void OnRequestComplete(CefRefPtr<CefURLRequest> req) override {
    auto status = req->GetRequestStatus();
    auto err    = req->GetRequestError();
    auto resp   = req->GetResponse();
    LOG(INFO) << "status=" << status << " err=" << err
              << " code=" << (resp ? resp->GetStatus() : 0)
              << " cached=" << req->ResponseWasCached();
    LOG(INFO) << "body=" << body_;
  }
  void OnUploadProgress(CefRefPtr<CefURLRequest>, int64_t, int64_t) override {}
  void OnDownloadProgress(CefRefPtr<CefURLRequest>, int64_t cur, int64_t tot) override {
    LOG(INFO) << "download " << cur << "/" << tot;
  }
  void OnDownloadData(CefRefPtr<CefURLRequest>, const void* data,
                     size_t n) override {
    body_.append(static_cast<const char*>(data), n);
  }
  bool GetAuthCredentials(bool, const CefString&, int, const CefString&,
                           const CefString&, CefRefPtr<CefAuthCallback>) override {
    return false;  // No credentials — let CEF cancel the request.
  }
  IMPLEMENT_REFCOUNTING(MyClient);
};

CefURLRequestClient

Source File: include/cef_urlrequest.h

Process / Thread Context: Browser Process / Render Process on the same thread that created the request — except GetAuthCredentials which is documented as called on the IO thread (browser process only).

Purpose: Interface that should be implemented by the CefURLRequest client. The methods are called on the same thread that created the request unless otherwise documented.

Methods

void OnRequestComplete(CefRefPtr<CefURLRequest> request)

Parameters:

• request: The CefURLRequest that has now completed (success, failure, or cancellation).

Return Value: Returns void.

Usage Instruction: Read request->GetRequestStatus(), GetRequestError(), GetResponse() and ResponseWasCached() here to determine the outcome. This is the terminal callback for a URL request.

Threading Constraint: Same thread that created the request.

void OnUploadProgress(CefRefPtr<CefURLRequest> request, int64_t current, int64_t total)

Parameters:

• request: The originating CefURLRequest.
• current: Number of bytes sent so far.
• total: Total size of uploading data, or -1 if chunked upload is enabled.

Return Value: Returns void.

Usage Instruction: Only called if the UR_FLAG_REPORT_UPLOAD_PROGRESS flag is set on the request. Use to render upload progress UI.

Threading Constraint: Same thread that created the request.

void OnDownloadProgress(CefRefPtr<CefURLRequest> request, int64_t current, int64_t total)

Parameters:

• request: The originating CefURLRequest.
• current: Bytes received up to the call.
• total: Expected total size of the response, or -1 if not determined.

Return Value: Returns void.

Usage Instruction: Use to render download progress UI or to throttle downstream processing.

Threading Constraint: Same thread that created the request.

void OnDownloadData(CefRefPtr<CefURLRequest> request, const void* data, size_t data_length)

Parameters:

• request: The originating CefURLRequest.
• data: Pointer to the current chunk of bytes received since the last call. Do not retain this pointer past the method.
• data_length: Number of valid bytes at data.

Return Value: Returns void.

Usage Instruction: Append data to your own buffer for the response body. Not called if UR_FLAG_NO_DOWNLOAD_DATA is set on the request.

Threading Constraint: Same thread that created the request.

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

Parameters:

• isProxy: true if the host is a proxy server.
• host: Hostname requiring authentication.
• port: Port number.
• realm: Optional authentication realm (may be empty).
• scheme: Authentication scheme name (e.g. "Basic", "Digest").
• callback: CefAuthCallback to invoke asynchronously with credentials or to cancel.

Return Value: Return true to continue the request and call CefAuthCallback::Continue() when the authentication information is available. If the request has an associated browser/frame then returning false will result in a call to GetAuthCredentials on the CefRequestHandler associated with that browser, if any. Otherwise, returning false will cancel the request immediately.

Usage Instruction: Only called for requests initiated from the browser process. Implement to handle proxy/server auth challenges asynchronously without blocking the IO thread.

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

Usage Example

class MiniClient : public CefURLRequestClient {
 public:
  void OnRequestComplete(CefRefPtr<CefURLRequest> req) override {
    LOG(INFO) << "done status=" << req->GetRequestStatus();
  }
  void OnUploadProgress(CefRefPtr<CefURLRequest>, int64_t, int64_t) override {}
  void OnDownloadProgress(CefRefPtr<CefURLRequest>, int64_t, int64_t) override {}
  void OnDownloadData(CefRefPtr<CefURLRequest>, const void*, size_t) override {}
  bool GetAuthCredentials(bool isProxy, const CefString& host, int port,
                           const CefString& realm, const CefString& scheme,
                           CefRefPtr<CefAuthCallback> cb) override {
    // Returning false here, with no associated browser, cancels the request.
    cb->Continue(/*username=*/"user", /*password=*/"pass");
    return true;
  }
  IMPLEMENT_REFCOUNTING(MiniClient);
};