C++ APISession methods

link_license

Links a license to the current authorized account context.

link_license(std::string license) links a license to the currently authorized account and returns blaze::status.

Function variants

blaze::status link_license(std::string license);
blaze::status link_license(std::string license, std::error_code& ec) noexcept;
void async_link_license(std::string license, std::function<void(std::error_code, blaze::status)> callback);
blaze::coro::awaitable_result<blaze::status> co_link_license(std::string license);

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
}

Behavior notes

  • Call link_license only after successful connect and initialize.
  • link_license requires an already authorized account context from authorize(credentials).
  • License-only authorization is not enough for this operation.
  • License length is validated locally before the request is sent. On local validation failure, transport error is empty and the returned blaze::status contains the length status.
  • On success, the server links the license to the current account and activates it.

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");
  const std::string login = read_line("Login");
  const std::string password = read_line("Password");
  const std::string license_to_link = read_line("License to link");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  credentials.type = blaze::credentials_type::login_password;

  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::account account = session.authorize(credentials);
    if (!account.good()) {
      print_status("Authorize returned status", account.status);
      return 1;
    }

    const blaze::status link_status = session.link_license(license_to_link);
    if (link_status != blaze::status::ok) {
      print_status("Link-license returned status", link_status);
      return 1;
    }

    std::cout << "License linked successfully\n";
    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Link-license 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");
  const std::string login = read_line("Login");
  const std::string password = read_line("Password");
  const std::string license_to_link = read_line("License to link");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  credentials.type = blaze::credentials_type::login_password;

  blaze::session session;

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

  session.async_connect(
    [&session, &completion, websocket_api_key, client_id, credentials, license_to_link](std::error_code connect_ec, blaze::api_server server) mutable {
      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, credentials, license_to_link](std::error_code init_ec, blaze::application app) mutable {
          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_authorize(std::move(credentials),
            [&session, &completion, license_to_link](std::error_code auth_ec, blaze::account account) {
              if (auth_ec) {
                print_error_code("Authorize failed", auth_ec);
                completion.set_value(1);
                return;
              }

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

              session.async_link_license(license_to_link,
                [&session, &completion](std::error_code link_ec, blaze::status link_status) {
                  if (link_ec) {
                    print_error_code("Link-license failed", link_ec);
                    completion.set_value(1);
                    return;
                  }

                  if (link_status != blaze::status::ok) {
                    print_status("Link-license returned status", link_status);
                    completion.set_value(1);
                    return;
                  }

                  std::cout << "License linked successfully\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,
  blaze::account_credentials credentials,
  const std::string& license_to_link
) {
  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 [auth_ec, account] = co_await session.co_authorize(std::move(credentials));
  if (auth_ec) {
    co_return auth_ec;
  }

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

  const auto [link_ec, link_status] = co_await session.co_link_license(license_to_link);
  if (link_ec) {
    co_return link_ec;
  }

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

  std::cout << "License linked successfully\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");
  const std::string login = read_line("Login");
  const std::string password = read_line("Password");
  const std::string license_to_link = read_line("License to link");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  credentials.type = blaze::credentials_type::login_password;

  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, credentials = std::move(credentials), license_to_link]() mutable
      -> blaze::coro::task<void> {
      const std::error_code ec =
        co_await run_example(session, websocket_api_key, client_id, std::move(credentials), license_to_link);
      completion.set_value(ec);
      co_return;
    }());

  const std::error_code ec = result.get();
  if (ec) {
    print_error_code("Link-license 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
ValueStatusReturned when
1okLicense was linked successfully.
3not_authorizedSession does not have an authorized account context.
6internal_server_errorServer could not complete link-license because of an internal error.
100license_not_foundLicense does not exist in the current application.
101license_too_shortlicense is shorter than 6 characters. This is rejected locally before the request is sent.
102license_too_longlicense is longer than 64 characters. This is rejected locally before the request is sent.
106license_already_linkedLicense is already linked to an account.
107license_already_activatedLicense is already activated.

Connection-level shutdowns

Normal link-license results are returned as blaze::status. The websocket may still be closed by session-level guards:

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

authorize(credentials)

Authorizes the current initialized session using account credentials.

logout

Clears the current authorization context while keeping the session connected.

On this page

Function variantsParametersResultBehavior notesExampleLink-license statusesConnection-level shutdownsRelated pages