Skip to content
Saucer v7.x

Schemes

This page documents how custom schemes work

Saucer has built-in support for custom url schemes. In fact, embedding is built on top of this feature.

Registration

Section titled “Registration”

Before getting started, you will have to register the scheme. This has to be done before any webview is created.

Example: Scheme Registration
int main()
{
    saucer::webview::register_scheme("name");
    return saucer::application::create({.id = "hello-world"})->run(start);
}

Handler

Section titled “Handler”

After registering the scheme, you can register a handler on a specific webview instance that is invoked each time a request is sent to the custom-scheme.

The handler works similar to that of exposed functions (in regards to coroutine support, executors, …) with the only difference being that it has to return a saucer::scheme::response.

Example: Scheme Handler
webview->handle("name", [](const saucer::scheme::request& req)
{
    return saucer::scheme::response{
        .data   = saucer::stash<>::from_str(std::format("Hello: {}", req.url().string())),
        .mime   = "text/plain",
        .status = 200,
    };
});

Requesting a resource from the custom-scheme via e.g. await fetch("name://root/content") would now return the response defined above.

The passed request contains information on the requested url, as well as:

  • The reqeust method
  • The request content (i.e. the request body)
  • The request headers

The response should at least contain the response data, mime-type and the status-code. You can also specify the response-headers.