C++ APISession methods

enable_panel_events

Enables or disables server-sent panel events for the current initialized session.

enable_panel_events(bool enable) toggles whether the current session receives server-sent panel events. Event delivery itself happens through on_panel_event(...).

Function variants

blaze::status enable_panel_events(bool enable);
blaze::status enable_panel_events(bool enable, std::error_code& ec) noexcept;
void async_enable_panel_events(bool enable, std::function<void(std::error_code, blaze::status)> callback);
blaze::coro::awaitable_result<blaze::status> co_enable_panel_events(bool enable);

Status vs error

The returned blaze::status is the API result. std::error_code and std::system_error are used for transport/runtime failures only.

Parameters

Prop

Type

Result

blaze::status

Use direct comparison, for example:

if (status == blaze::status::ok) {
  // success
}

Connect the session and complete initialize.

Register on_panel_event(...) before enabling delivery, so the first event is not missed.

Call enable_panel_events(true).

Handle incoming blaze::panel_event objects in your callback.

Call enable_panel_events(false) when you no longer want server-sent events.

Behavior notes

  • enable_panel_events requires a connected and initialized session.
  • Authorization is not required. Panel events can be enabled before or after authorization.
  • enable = true starts panel-event delivery for the current session.
  • enable = false stops panel-event delivery for the current session.
  • The operation is idempotent. Repeating the same target state is valid.
  • If you do not set on_panel_event(...), subscription can still succeed, but incoming panel events are ignored by the library.
  • Subscription state is preserved across valid session resumption. A brand-new session still starts with panel events disabled.
  • Event payload contracts are documented in Panel events overview and Event types.
  • Sync overloads use the session timeout configured in the constructor or via with_timeout(...).
  • Coroutine overloads are available only when the library is built with coroutine support.

Example

Compilation note

Synchronous and Asynchronous examples compile in the same form from C++17 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";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

void print_status(const std::string& context, blaze::status status) {
  std::cout << context << ": "
            << static_cast<unsigned int>(status)
            << " (" << blaze::to_string(status) << ")\n";
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");

  blaze::session session;
  session.on_panel_event([](blaze::panel_event event) {
    std::cout << "Received panel event type: "
              << static_cast<unsigned int>(event.type) << '\n';
  });

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

    const blaze::application app = session.initialize(websocket_api_key, client_id);
    if (!app.good()) {
      print_status("Initialize returned status", app.status);
      return 1;
    }

    const blaze::status enable_status = session.enable_panel_events(true);
    if (enable_status != blaze::status::ok) {
      print_status("Enable-panel-events returned status", enable_status);
      return 1;
    }

    std::cout << "Panel events enabled\n";

    const blaze::status disable_status = session.enable_panel_events(false);
    if (disable_status != blaze::status::ok) {
      print_status("Disable-panel-events returned status", disable_status);
      return 1;
    }

    std::cout << "Panel events disabled\n";
    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Enable-panel-events failed", e.code());
    return 1;
  }

  return 0;
}

Enable-panel-events statuses

ValueStatusReturned when
1okSubscription state was updated successfully.

Connection-level shutdowns

Normal enable-panel-events results are returned as blaze::status. The websocket may still be closed by session-level guards around this operation:

Close codeMeaningWhen it can happen
4200not_initializedenable_panel_events was called before a successful initialize.
4201rate_limitedSession or IP rate limiting closed the websocket around this operation.

On this page