get_online_users

get_online_users_count() returns blaze::online_users_count for the current initialized application.

Function variants

blaze::online_users_count get_online_users_count();
blaze::online_users_count get_online_users_count(std::error_code& ec) noexcept;
void async_get_online_users_count(std::function<void(std::error_code, blaze::online_users_count)> callback);
blaze::coro::awaitable_result<blaze::online_users_count> co_get_online_users_count();

Status vs error

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

Result

struct online_users_count {
  std::uint32_t users;
  blaze::status status;
};

Prop

Type

Checking returned fields

If the server omits count data, the library returns a default value instead of std::optional, because it targets C++14 compatibility.

Field	Practical check
`result.users`	Check `result.status == blaze::status::ok` before using it. `0` is valid on success and is also the default when the count is omitted on non-success statuses.

Behavior notes

Call get_online_users_count only after successful connect and initialize.
This operation does not require an authorized license or account context.
On success, users == 0 means the application currently has no connected sessions.
On non-success statuses, users falls back to 0, so do not use it as an error check by itself.

Example

Compilation note

Synchronous and Asynchronous examples compile 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";
}

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;

  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::online_users_count result = session.get_online_users_count();
    if (result.status != blaze::status::ok) {
      print_status("Get-online-users-count returned status", result.status);
      return 1;
    }

    std::cout << "Online users: " << result.users << '\n';
    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Get-online-users-count failed", e.code());
    return 1;
  }

  return 0;
}

#include "blazeauth/api/api.hpp"

#include <future>
#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;

  std::promise<int> completion;
  std::future<int> result = completion.get_future();

  session.async_connect(
    [&session, &completion, websocket_api_key, client_id](std::error_code connect_ec, blaze::api_server server) {
      if (connect_ec) {
        print_error_code("Connect failed", connect_ec);
        completion.set_value(1);
        return;
      }

      std::cout << "Connected to server location: " << server.location << '\n';

      session.async_initialize(websocket_api_key, client_id,
        [&session, &completion](std::error_code init_ec, blaze::application app) {
          if (init_ec) {
            print_error_code("Initialize failed", init_ec);
            completion.set_value(1);
            return;
          }

          if (!app.good()) {
            print_status("Initialize returned status", app.status);
            completion.set_value(1);
            return;
          }

          session.async_get_online_users_count(
            [&session, &completion](std::error_code count_ec, blaze::online_users_count result) {
              if (count_ec) {
                print_error_code("Get-online-users-count failed", count_ec);
                completion.set_value(1);
                return;
              }

              if (result.status != blaze::status::ok) {
                print_status("Get-online-users-count returned status", result.status);
                completion.set_value(1);
                return;
              }

              std::cout << "Online users: " << result.users << '\n';

              session.async_shutdown([&completion](std::error_code shutdown_ec) {
                if (shutdown_ec) {
                  print_error_code("Shutdown failed", shutdown_ec);
                  completion.set_value(1);
                  return;
                }

                completion.set_value(0);
              });
            });
        });
    });

  return result.get();
}

Project must be built with C++20 support and with coroutine support available both in the language mode and in the standard library implementation for this example to compile correctly.

#include "blazeauth/api/api.hpp"

#include <future>
#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;
}

#if BLAZEAUTH_HAS_COROUTINES

blaze::coro::task<std::error_code> run_example(
  blaze::session& session,
  const std::string& websocket_api_key,
  const std::string& client_id
) {
  const auto [connect_ec, server] = co_await session.co_connect();
  if (connect_ec) {
    co_return connect_ec;
  }

  std::cout << "Connected to server location: " << server.location << '\n';

  const auto [init_ec, app] = co_await session.co_initialize(websocket_api_key, client_id);
  if (init_ec) {
    co_return init_ec;
  }

  if (!app.good()) {
    co_return blaze::make_error_code(app.status);
  }

  const auto [count_ec, result] = co_await session.co_get_online_users_count();
  if (count_ec) {
    co_return count_ec;
  }

  if (result.status != blaze::status::ok) {
    co_return blaze::make_error_code(result.status);
  }

  std::cout << "Online users: " << result.users << '\n';

  const auto [shutdown_ec] = co_await session.co_shutdown();
  co_return shutdown_ec;
}

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;

  std::promise<std::error_code> completion;
  std::future<std::error_code> result = completion.get_future();

  blaze::coro::co_spawn([&session, &completion, websocket_api_key, client_id]() -> blaze::coro::task<void> {
    const std::error_code ec = co_await run_example(session, websocket_api_key, client_id);
    completion.set_value(ec);
    co_return;
  }());

  const std::error_code ec = result.get();
  if (ec) {
    print_error_code("Get-online-users-count failed", ec);
    return 1;
  }

  return 0;
}

#else

int main() {
  std::cout << "This example requires coroutine support in the Blazeauth library build.\n";
  return 0;
}

#endif

Get-online-users-count statuses

Value	Status	Returned when
`1`	`ok`	Current online users count was returned successfully.
`6`	`internal_server_error`	Server could not read the current online users count because of an internal error.

Connection-level shutdowns

Normal get-online-users-count results are returned in result.status. The websocket may still be closed by session-level guards:

Close code	Meaning	When it can happen
`4200`	`not_initialized`	`get_online_users_count` was called before a successful `initialize`.
`4201`	`rate_limited`	Session or IP rate limiting closed the websocket around this operation.

get_online_users_count

On this page