CefSchemeRegistrar

Header: cef_scheme.h
Interfaces: CefRegisterSchemeHandlerFactory, CefClearSchemeHandlerFactories, CefSchemeRegistrar, CefSchemeHandlerFactory
Category: System Utilities

Overview

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

CefRegisterSchemeHandlerFactory (free function)

Source File: include/cef_scheme.h

Process / Thread Context: Browser Process. The header states: "This function may be called on any thread in the browser process."

Purpose: Register a scheme handler factory with the global request context. The factory produces CefResourceHandler instances to handle requests for a given scheme (and optionally a domain). Equivalent to CefRequestContext::GetGlobalContext()->RegisterSchemeHandlerFactory().

Methods

bool CefRegisterSchemeHandlerFactory(const CefString& scheme_name, const CefString& domain_name, CefRefPtr<CefSchemeHandlerFactory> factory)

Parameters:

• scheme_name: The scheme to match (e.g. "https" or a custom scheme). An empty domain_name for a standard scheme causes the factory to match all domain names; domain_name is ignored for non-standard schemes.
• domain_name: Optional domain filter (see above).
• factory: The CefSchemeHandlerFactory implementation. May be NULL to remove a previously-registered factory matching scheme_name/domain_name.

Return Value: Returns false if an error occurs; true on success.

Usage Instruction: If scheme_name is a built-in scheme and no handler is returned by factory then the built-in scheme handler factory will be called. If scheme_name is a custom scheme then you must also implement the CefApp::OnRegisterCustomSchemes() method in all processes. This function may be called multiple times to change or remove the factory that matches the specified scheme_name and optional domain_name.

Threading Constraint: Any thread in the browser process.

CefClearSchemeHandlerFactories (free function)

Source File: include/cef_scheme.h

Process / Thread Context: Browser Process (any thread).

Purpose: Clear all scheme handler factories registered with the global request context. Equivalent to CefRequestContext::GetGlobalContext()->ClearSchemeHandlerFactories().

Methods

bool CefClearSchemeHandlerFactories()

Parameters:

• None.

Return Value: Returns false on error; true on success.

Usage Instruction: Use to tear down all custom scheme handlers, e.g. during reconfiguration. After this call only the built-in scheme handlers remain.

Threading Constraint: Any thread in the browser process.

Usage Example

// === Register and clear a scheme handler factory ===

class MySchemeHandler : public CefResourceHandler {
  // ... implement ProcessRequest, GetResponseHeaders, ReadResponse, etc. ...
};

class MyFactory : public CefSchemeHandlerFactory {
 public:
  CefRefPtr<CefResourceHandler> Create(
      CefRefPtr<CefBrowser> browser,
      CefRefPtr<CefFrame> frame,
      const CefString& scheme_name,
      CefRefPtr<CefRequest> request) override {
    if (scheme_name == "myapp")
      return new MySchemeHandler();
    return nullptr;  // fall back to default handling
  }
  IMPLEMENT_REFCOUNTING(MyFactory);
};

void RegisterMyScheme() {
  // Register a factory for the "myapp" scheme on all domains.
  CefRegisterSchemeHandlerFactory("myapp", "", new MyFactory());
}

void UnregisterMyScheme() {
  // Remove just our factory.
  CefRegisterSchemeHandlerFactory("myapp", "", nullptr);
  // Or remove every custom factory:
  CefClearSchemeHandlerFactories();
}

CefSchemeRegistrar

Source File: include/cef_scheme.h

Process / Thread Context: Browser Process. The header states: "This function may be called on any thread." The class itself is a scoped object (CefBaseScoped) handed to the embedder from CefApp::OnRegisterCustomSchemes().

Purpose: Class that manages custom scheme registrations. It is passed to CefApp::OnRegisterCustomSchemes(CefRefPtr<CefSchemeRegistrar> registrar) so the embedder can declare custom scheme options (e.g. standard, local, display-isolated, secure, cors-enabled, fetch enabled).

Methods

bool AddCustomScheme(const CefString& scheme_name, int options)

Parameters:

• scheme_name: The scheme name to register. Should not be one of the built-in HTTP, HTTPS, FILE, FTP, ABOUT or DATA schemes.
• options: Bitmask of cef_scheme_options_t values (e.g. CEF_SCHEME_OPTION_STANDARD, CEF_SCHEME_OPTION_LOCAL, CEF_SCHEME_OPTION_DISPLAY_ISOLATED, CEF_SCHEME_OPTION_SECURE, CEF_SCHEME_OPTION_CORS_ENABLED, CEF_SCHEME_OPTION_CSP_BYPASSING, CEF_SCHEME_OPTION_FETCH_ENABLED).

Return Value: Returns false if scheme_name is already registered or if an error occurs; otherwise true.

Usage Instruction: Call once per unique scheme_name from CefApp::OnRegisterCustomSchemes(). Calling more than once for the same scheme returns false. The set of options chosen here determines how Chromium treats the scheme (origin, security, network stack integration, etc.).

Threading Constraint: Any thread, but typically called during OnRegisterCustomSchemes early in app startup.

Usage Example

class MyApp : public CefApp {
 public:
  void OnRegisterCustomSchemes(
      CefRefPtr<CefSchemeRegistrar> registrar) override {
    // Register "myapp" as a standard, secure, CORS-enabled scheme that
    // supports fetch and bypasses CSP. See cef_scheme_options_t in
    // cef_types.h for the full set of bit values.
    int opts = CEF_SCHEME_OPTION_STANDARD |
               CEF_SCHEME_OPTION_SECURE |
               CEF_SCHEME_OPTION_CORS_ENABLED |
               CEF_SCHEME_OPTION_FETCH_ENABLED;
    registrar->AddCustomScheme("myapp", opts);
  }
  IMPLEMENT_REFCOUNTING(MyApp);
};

CefSchemeHandlerFactory

Source File: include/cef_scheme.h

Process / Thread Context: Browser Process / IO Thread (header: "The methods of this class will always be called on the IO thread.").

Purpose: Class that creates CefResourceHandler instances for handling scheme requests. Registered with CefRegisterSchemeHandlerFactory() or CefRequestContext::RegisterSchemeHandlerFactory() to intercept URL loads for one or more schemes.

Methods

CefRefPtr<CefResourceHandler> Create(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, const CefString& scheme_name, CefRefPtr<CefRequest> request)

Parameters:

• browser: The browser window that originated the request, or NULL if the request did not originate from a browser window (for example, if it came from CefURLRequest).
• frame: The frame that originated the request, or NULL for non-browser origins (see browser).
• scheme_name: The scheme being handled (matches the scheme registered for this factory).
• request: The request object — cannot be modified. Read-only view of the URL, method, headers and POST data.

Return Value: Return a new CefResourceHandler instance to handle the request, or an empty reference (nullptr) to allow default handling of the request.

Usage Instruction: Construct a fresh CefResourceHandler per request — never reuse one across requests. Returning nullptr allows the built-in scheme handler (for built-in schemes) or no handler (for custom schemes that fall through) to run. The IO thread will then drive the returned handler via ProcessRequest/GetResponseHeaders/ReadResponse/Skip/Cancel etc.

Threading Constraint: Always called on the IO thread.

Usage Example

// Full integration: factory + handler + registration + custom scheme.
class AppSchemeHandler : public CefResourceHandler {
 public:
  AppSchemeHandler() {}
  bool ProcessRequest(CefRefPtr<CefRequest> req,
                      CefRefPtr<CefCallback> cb) override {
    req_ = req;
    body_ = "<html><body>Hello from myapp://</body></html>";
    cb->Continue();  // headers will be queried next
    return true;
  }
  void GetResponseHeaders(CefRefPtr<CefResponse> resp, int64_t& len,
                          CefString&) override {
    resp->SetMimeType("text/html");
    resp->SetStatus(200);
    len = static_cast<int64_t>(body_.size());
  }
  bool ReadResponse(void* out, int n, int& read,
                    CefRefPtr<CefCallback> cb) override {
    if (body_.empty()) { read = 0; return false; }
    read = std::min<int>(n, body_.size());
    memcpy(out, body_.data(), read);
    body_.erase(0, read);
    return true;
  }
  void Cancel() override {}
  IMPLEMENT_REFCOUNTING(AppSchemeHandler);
 private:
  CefRefPtr<CefRequest> req_;
  std::string body_;
};

class AppSchemeFactory : public CefSchemeHandlerFactory {
 public:
  CefRefPtr<CefResourceHandler> Create(
      CefRefPtr<CefBrowser>, CefRefPtr<CefFrame>,
      const CefString& scheme, CefRefPtr<CefRequest>) override {
    if (scheme == "myapp") return new AppSchemeHandler();
    return nullptr;
  }
  IMPLEMENT_REFCOUNTING(AppSchemeFactory);
};

// During browser-process startup:
//   CefRegisterSchemeHandlerFactory("myapp", "", new AppSchemeFactory());
// CefApp::OnRegisterCustomSchemes must also call
//   registrar->AddCustomScheme("myapp", opts);

See Also

• cef_resource_handler
• cef_urlrequest