C++ APISession methods
get_variable
Returns application variable content by name for the current initialized session.
get_variable(std::string name) returns blaze::variable for the requested
application variable.
Function variants
blaze::variable get_variable(std::string name);
blaze::variable get_variable(std::string name, std::error_code& ec) noexcept;
void async_get_variable(std::string name, std::function<void(std::error_code, blaze::variable)> callback);
blaze::coro::awaitable_result<blaze::variable> co_get_variable(std::string name);Status vs error
variable.status is the API result. std::error_code and
std::system_error are used for transport/runtime failures only.
Parameters
Prop
Type
Result
struct variable {
std::string content;
blaze::status status;
bool good() const noexcept;
};Prop
Type
Checking returned fields
If the server omits variable content, the library returns a default value.
| Field | Practical check |
|---|---|
result.content | Use result.good() or result.status == blaze::status::ok before using it. result.content.empty() is not a reliable failure check because an empty string can be valid content and is also the default on non-success statuses. |
Behavior notes
- Call
get_variableonly after successfulconnectandinitialize. - Variable access strategy is defined by the application configuration:
- Public variables can be read by any initialized session.
- Protected variables require an authorized session and return
blaze::status::not_authorizedotherwise.
- On non-success statuses,
contentdefaults to an empty string.
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");
const std::string variable_name = read_line("Variable name");
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::variable result = session.get_variable(variable_name);
if (!result.good()) {
print_status("Get-variable returned status", result.status);
return 1;
}
std::cout << "Variable content: " << result.content << '\n';
session.shutdown();
} catch (const std::system_error& e) {
print_error_code("Get-variable failed", e.code());
return 1;
}
return 0;
}Get-variable statuses
| Value | Status | Returned when |
|---|---|---|
1 | ok | Variable content was returned successfully. |
3 | not_authorized | Variable is protected and the current session is not authorized. |
400 | variable_not_found | Variable does not exist in the current application. |
401 | variable_invalid_name | name is shorter than the minimum allowed length. |
Connection-level shutdowns
Normal get-variable 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_variable was called before a successful initialize. |
4201 | rate_limited | Session or IP rate limiting closed the websocket around this operation. |