set_shutdown_callback

set_shutdown_callback installs a hook that runs when the current connection lifecycle ends.

Function variants

void set_shutdown_callback(std::function<void(std::error_code, blaze::close_message)> callback);

Runs on the library I/O thread

Do not call synchronous blaze::session methods from this callback. If you need to continue work from here, stay on async API or hand control back to your own thread/executor.

Callback signature

void(std::error_code ec, blaze::close_message message)

Callback arguments

Prop

Type

close_message

struct close_message {
  blaze::close_code code;
  std::string reason;
};

Prop

Type

Behavior notes

The callback runs for explicit local shutdown(), server-initiated close, failed session resumption, and connection-loss shutdown paths.
It is the main hook for observing why a connection ended.
When shutdown was initiated locally, message.code is usually blaze::close_code::none and message.reason is empty.
When the server sends a close frame, message.code and message.reason carry the close details.
The callback stays registered on the blaze::session object until you replace or clear it.
Pass nullptr or an empty std::function to clear the callback.

Example

Compilation note

This example compiles in the same form from C++14 to C++26.

#include "blazeauth/api/api.hpp"

#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

int main() {
  blaze::session session;

  session.set_shutdown_callback([](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.empty()) {
      std::cout << "Close reason: " << message.reason << '\n';
    }
  });

  try {
    const blaze::api_server server = session.connect();
    std::cout << "Connected to server location: " << server.location << '\n';

    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Connect or shutdown failed", e.code());
    return 1;
  }

  return 0;
}