API reference

Everything is in namespace eonauth, declared in eonauth.h and eonauth_status.h. Every function is thread-safe.

Types

struct Result {
    Status status = Status::Ok;
    std::string message;                          // safe to show users
    long long retryAfterSeconds = 0;              // with Status::RateLimited
    std::map<std::string, std::string> details;   // extra server fields
    bool ok() const;
    explicit operator bool() const;
};

struct Subscription {
    std::string tier;         // e.g. "Pro"
    int level = 0;
    long long expiresAt = 0;  // unix seconds; 0 = lifetime
};

struct Config;                // see Configuration

enum class Event { LoggedIn, LoggedOut, SessionLost, SubscriptionsChanged, ConnectionProblem, ConnectionRestored };
struct EventInfo { Event event; Result result; };   // result: reason for SessionLost / ConnectionProblem

struct AppStats { long long users; long long online; std::string latestVersion; std::string downloadUrl; };
struct FileInfo { std::string id; std::string name; long long size; std::string sha256; };

using ResultCallback   = std::function<void(const Result&)>;
using VariableCallback = std::function<void(const Result&, const std::string& value)>;
using StatsCallback    = std::function<void(const Result&, const AppStats&)>;
using FileCallback     = std::function<void(const Result&, const FileInfo&, const std::vector<std::uint8_t>& data)>;
using EventHandler     = std::function<void(const EventInfo&)>;
using Dispatcher       = std::function<void(std::function<void()> work)>;

enum class LogLevel { Debug, Info, Warn, Error };
struct CertificateInfo { std::string subject; std::string spkiPin; bool pinned; };

Config is described field by field in Configuration.

Lifecycle

Function	Notes
`Result Init(const Config&)`	Once per process. Validates the config before any connection
`void Shutdown(bool logout = false)`	Stops the worker thread; `true` also ends the server session
`bool IsInitialized()`

Threading, events and logging

Function	Notes
`void SetDispatcher(Dispatcher)`	Where callbacks and events run. Default: the SDK worker thread
`int AddEventHandler(EventHandler)`	Returns an ID. Handlers run through the dispatcher
`void RemoveEventHandler(int id)`
`void SetLogHandler(std::function<void(LogLevel, const std::string&)>)`	Lines are already scrubbed; `nullptr` restores stdout/stderr
`Dispatcher win32::WindowDispatcher(void* hwnd, unsigned message)`	Posts work to a window
`void win32::RunDispatched(std::intptr_t lParam)`	Call from that window’s message handler

State (never blocks)

Function	Returns
`bool IsLoggedIn()`
`std::string Username()`	Empty in free mode
`bool IsFree()`	Signed in with `LoginFree`
`std::vector<Subscription> Subscriptions()`	Active ones, highest level first
`bool HasTier(const std::string&)`
`std::optional<Subscription> FindTier(const std::string&)`
`int HighestLevel()`	`-1` with no subscriptions
`std::optional<std::string> Variable(const std::string& id)`	Last value fetched in this session
`std::string Hwid()`	This PC’s hardware ID for this app
`long long SessionExpiresAt()`	Server idle expiry, unix seconds
`std::string LatestVersion()`	From the last sign-in or heartbeat
`std::string DownloadUrl()`
`Result LastError()`	The most recent failure
`bool IsConnectionHealthy()`	False between `ConnectionProblem` and `ConnectionRestored`

Async calls

Queued in order on the worker thread; the callback runs through the dispatcher. Callbacks are optional where a default is shown.

Function	Notes
`RegisterAsync(username, password, licenseKey, done = nullptr)`	New password account
`LoginAsync(username, password, done = nullptr)`
`LoginWithKeyAsync(licenseKey, done = nullptr)`
`LoginWithKeyAsync(licenseKey, username, done = nullptr)`	Username needed on a key’s first use
`LoginFreeAsync(done = nullptr)`	Free mode
`ResumeSessionAsync(done = nullptr)`	Restores and re-validates the saved session
`RedeemAsync(licenseKey, done = nullptr)`	Signed in
`RedeemWithCredentialsAsync(username, password, licenseKey, done = nullptr)`	Renew an expired account
`FetchVariableAsync(id, VariableCallback done = nullptr)`	One variable by ID
`SetUserVariableAsync(name, value, done = nullptr)`	Up to 4 KB, 50 per user
`DeleteUserVariableAsync(name, done = nullptr)`
`GetUserVariableAsync(name, VariableCallback done = nullptr)`	`VariableNotFound` if unset
`ChangeUsernameAsync(username, done = nullptr)`
`FetchAppStatsAsync(StatsCallback done)`
`DownloadFileAsync(id, FileCallback done)`	Size and SHA-256 checked; up to 25 MB
`BanCurrentUserAsync(reason, blacklistHwid = false, done = nullptr)`	Raises `SessionLost` with `UserBanned`
`LogoutAsync(done = nullptr)`

Blocking calls

The same operations on the calling thread. Not on a UI thread.

Result Register(std::string username, std::string password, std::string licenseKey);
Result Login(std::string username, std::string password);
Result LoginWithKey(std::string licenseKey, const std::string& username = "");
Result LoginFree();
Result ResumeSession();
Result Redeem(std::string licenseKey);
Result RedeemWithCredentials(std::string username, std::string password, std::string licenseKey);
Result FetchVariable(const std::string& id, std::string* value = nullptr);
Result SetUserVariable(const std::string& name, const std::string& value);
Result DeleteUserVariable(const std::string& name);
Result GetUserVariable(const std::string& name, std::string* value);
Result ChangeUsername(const std::string& username);
Result FetchAppStats(AppStats* stats);
Result DownloadFile(const std::string& id, FileInfo* info, std::vector<std::uint8_t>* data);
Result BanCurrentUser(const std::string& reason, bool blacklistHwid = false);
Result Heartbeat();   // normally automatic
Result Logout();

Input checks and messages (local)

Function	Notes
`std::string NormalizeLicenseKey(const std::string&)`	Drops spaces, quotes and invisible characters, turns look-alike dashes into `-`, upper-cases
`std::string CheckLicenseKey(const std::string& normalizedKey)`	Empty if acceptable, else a message
`std::string CheckUsername(const std::string&)`	3 to 32 letters, digits, `_`, `.`, `-`
`std::string CheckPassword(const std::string&)`	8 to 128 characters
`std::string CheckVariableName(const std::string&)`	Per-user variable names
`std::string UserMessage(const Result&)`	What to show
`std::string UserHint(const Result&)`	Suggested next step, or empty

Status helpers

Function	Notes
`const char* ToString(Status)`	`"LICENSE_EXPIRED"` and so on
`bool IsTransient(Status)`	`NetworkError`, `RateLimited`, `ServerError`
`bool IsAccessDenied(Status)`	The server refused the account or session

See Errors and messages for every Status.

Helpers

Function	Notes
`void WipeSecrets(Config&)`	Clear your copy of the keys after `Init`
`std::vector<std::uint8_t> UnmaskSecret(const std::uint8_t* masked, const std::uint8_t* pad, std::size_t length)`	Rebuilds a key from `config.h`
`std::string ToUtf8(const std::wstring&)` / `std::wstring ToWide(const std::string&)`
`std::string FormatTime(long long unixSeconds)`	Local time, e.g. `2026-10-14 20:56`; `0` gives `never`
`std::vector<CertificateInfo> InspectCertificateChain(const std::wstring& host, const std::vector<std::string>& pins, Result&)`	Lists a host’s chain, leaf first
`std::vector<std::string> CloudflareCaPins()`	The default pin set