Callbacks and hooks
Session-level configuration hooks for resumption, exceptions, shutdown, reconnect, and panel events.
These methods configure session-level behavior around the websocket lifecycle.
They all belong to blaze::session, but this page focuses on the overall model:
when callbacks fire, how they interact with connection resumption, and what
threading rules matter in user code.
Detailed method pages
This page explains the model. Full per-method reference lives under
Session methods -> Callbacks and hooks.
Callbacks run on the library I/O thread
Do not call synchronous blaze::session methods from these callbacks. Inside
callback code, continue with async API only, or hand work back to your own
thread/executor.
Common rules
- Register callbacks before
connectif you want to observe the whole lifecycle. - Passing
nullptror an emptystd::functionclears the previously registered callback. - Registering a new callback replaces the previous one.
- These methods are local configuration only. They do not return
blaze::statusand do not perform a network round trip. - Once registered, callbacks stay attached to the same
blaze::sessionobject until you replace or clear them.
Callback map
| Method | Role | Fires when |
|---|---|---|
set_session_resumption_enabled(bool) | Resumption policy toggle | Does not fire a callback by itself; it enables or disables automatic session resumption after connection loss. |
on_exception(...) | Exceptional receive-path failure hook | Library encounters a receive-path failure that becomes an exception, for example invalid protocol/message data. |
on_shutdown(...) | Connection-end hook | Current connection lifecycle ends: explicit shutdown, server close, failed resumption, or final connection-loss shutdown. |
on_connection_resumed(...) | Successful resumption hook | Automatic session resumption succeeds after unexpected connection loss. |
on_panel_event(...) | Server-event hook | Server sends a valid panel-event packet with an event type known to the current library build and event subscription is enabled. |
Lifecycle model
Register callbacks before connect if you want to observe the whole session lifecycle.
During normal request/response operation, callbacks stay idle unless a relevant lifecycle event happens.
On unexpected connection loss, the library either attempts session resumption or proceeds to shutdown, depending on set_session_resumption_enabled(...).
If resumption succeeds, on_connection_resumed(...) runs. If it fails, on_shutdown(...) runs when the lifecycle ends.
If the library hits an exceptional receive-path failure, on_exception(...) runs and the session then shuts down.
Minimal setup example
Compilation note
This example compiles in the same form from C++17 to C++26.
#include "blazeauth/api/api.hpp"
#include <exception>
#include <iostream>
#include <string>
#include <system_error>
int main() {
blaze::session session;
session.set_session_resumption_enabled(true);
session.on_exception([](std::exception_ptr eptr) {
if (!eptr) {
return;
}
try {
std::rethrow_exception(eptr);
} catch (const std::system_error& e) {
std::cout << "Exception callback: " << e.code().message() << '\n';
} catch (const std::exception& e) {
std::cout << "Exception callback: " << e.what() << '\n';
}
});
session.on_shutdown([](std::error_code ec, blaze::close_message message) {
std::cout << "Shutdown callback: " << ec.message() << '\n';
if (message.code != blaze::close_code::none) {
std::cout << "Close code: " << static_cast<unsigned int>(message.code) << '\n';
}
if (message.reason.has_value() && !message.reason->empty()) {
std::cout << "Close reason: " << *message.reason << '\n';
}
});
session.on_connection_resumed([]() {
std::cout << "Session was resumed\n";
});
session.on_panel_event([](blaze::panel_event event) {
std::cout << "Panel event type: " << static_cast<unsigned int>(event.type) << '\n';
});
return 0;
}