Skip to content

api/license.h

Namespaces

Name
cvedia
cvedia::rt
API for controlling the server and lifecycle management of runtime instances.
cvedia::rt::api
cvedia::rt::api::license
License management API for CVEDIA-RT system.

Classes

Name
struct cvedia::rt::api::license::LicenseInfo
Comprehensive information about a license.

Functions

Name
void to_json(nlohmann::json & obj, LicenseInfo const & licenseInfo)
void from_json(nlohmann::json const & j, LicenseInfo & licenseInfo)
expected< std::string > pathToLicensesDirectory()
Retrieves the filesystem path to the licenses directory.
expected< std::vector< std::string > > getCurrentLicenseKeys()
Retrieves all currently installed license keys.
expected< std::vector< LicenseInfo > > getCurrentLicenseInfo()
Retrieves detailed information about all currently installed licenses.
expected< FeatureInfo > getCurrentFeatureInfo()
Retrieves aggregated information about all available features.
expected< LicenseInfo > getLicenseInfo(std::string const & key)
Retrieves detailed information for a specific license by key.
expected< std::map< LicenseTag, LicenseLedgerState > > getLedgerInfo()
Retrieves the current state of the license ledger.
expected< LicenseLedgerInfoForInstance > getLedgerInfoForInstance(Uuid const & instanceId)
Retrieves license information for a specific instance.
expected< void > updateLicenseKey(std::string const & key)
Updates an existing license key from the license server.
expected< void > addLicenseKey(std::string const & key)
Adds a new license key to the system.
expected< void > removeLicenseKey(std::string const & key, bool force =false)
Removes a license key from the system.
expected< void > loadLicenses()
Loads or reloads all licenses from the licenses directory.
expected< void > unloadLicenses()
Unloads all currently loaded licenses from the system.
expected< bool > activateTrialLicense()
Activates a trial license for the current machine.
expected< std::string > activateAndRetrieveTrialLicense()
Activates a trial license and returns the trial license key.
expected< IntentResponse > inform(LicenseTag const licenseTag, Intent const intent, Uuid const & instanceId, bool keepDemand =true, pCValue const & context =nullptr)
Informs the license enforcement system about feature usage intent.
expected< IntentResponse > informLabel(Intent const intent, Uuid const & instanceId, std::string const & label)
Informs the license system using a string label instead of LicenseTag enum.

Functions Documentation

function to_json

inline void to_json(
    nlohmann::json & obj,
    LicenseInfo const & licenseInfo
)

function from_json

inline void from_json(
    nlohmann::json const & j,
    LicenseInfo & licenseInfo
)

function pathToLicensesDirectory

expected< std::string > pathToLicensesDirectory()

Retrieves the filesystem path to the licenses directory.

Return: Expected containing the absolute path to the licenses directory, or error on failure

function getCurrentLicenseKeys

expected< std::vector< std::string > > getCurrentLicenseKeys()

Retrieves all currently installed license keys.

Return: Expected containing a vector of license key strings, or RTErrc::NoLicensesFound if none installed

Note: Used to list all installed licenses for display in admin interfaces or verification

function getCurrentLicenseInfo

expected< std::vector< LicenseInfo > > getCurrentLicenseInfo()

Retrieves detailed information about all currently installed licenses.

Returns:

  • RTErrc::NoLicensesFound No licenses are installed
  • RTErrc::NotInitialized API has not been initialized

Return: Expected containing LicenseInfo for all licenses, or error if none found or API not initialized

Note: Provides comprehensive license details including expiration dates, stream limits, and feature allowances

function getCurrentFeatureInfo

expected< FeatureInfo > getCurrentFeatureInfo()

Retrieves aggregated information about all available features.

Return: Expected containing FeatureInfo with combined allowances, or error if system not initialized

Note: Useful for determining overall system capacity (total streams, enabled analytics features)

Combines allowances from all installed licenses to provide total system capabilities.

function getLicenseInfo

expected< LicenseInfo > getLicenseInfo(
    std::string const & key
)

Retrieves detailed information for a specific license by key.

Parameters:

  • key The license key string to query

Returns:

  • RTErrc::LicenseDoesNotExists The specified key is not found
  • RTErrc::NotInitialized API has not been initialized

Return: Expected containing LicenseInfo for the specified license

function getLedgerInfo

expected< std::map< LicenseTag, LicenseLedgerState > > getLedgerInfo()

Retrieves the current state of the license ledger.

See: getLedgerInfoForInstance() for instance-specific ledger information

Return: Expected containing a map of LicenseTag to LicenseLedgerState showing current usage

Shows which instances have been granted or are demanding each licensed feature.

function getLedgerInfoForInstance

expected< LicenseLedgerInfoForInstance > getLedgerInfoForInstance(
    Uuid const & instanceId
)

Retrieves license information for a specific instance.

Parameters:

  • instanceId The UUID of the instance to query

Return: Expected containing the features granted and demanded by the instance

function updateLicenseKey

expected< void > updateLicenseKey(
    std::string const & key
)

Updates an existing license key from the license server.

Parameters:

  • key The license key string to update

Returns:

  • RTErrc::NotInitialized API has not been initialized
  • RTErrc::LicenseDoesNotExists License is not currently installed

Return: Expected void on success, or error on failure

Note: Maintains machine activation status and reloads licenses after successful update

Retrieves the latest certificate from the license server for an already installed license. Useful when license allowances have been modified server-side or after renewal.

function addLicenseKey

expected< void > addLicenseKey(
    std::string const & key
)

Adds a new license key to the system.

Parameters:

  • key The license key string to add

Returns:

  • RTErrc::NotInitialized API has not been initialized
  • RTErrc::LicenseAlreadyExists License is already installed

Return: Expected void on success, or error on failure

Note: Requires network connectivity to contact the license server

Retrieves the license certificate from the license server, installs it, and activates the license for the current machine if needed. Automatically reloads licenses after installation.

auto result = cvedia::rt::api::license::addLicenseKey("XXXX-XXXX-XXXX-XXXX");
if (!result) {
    std::cerr << "Failed to add license: " << result.error().message() << std::endl;
}

function removeLicenseKey

expected< void > removeLicenseKey(
    std::string const & key,
    bool force =false
)

Removes a license key from the system.

Parameters:

  • key The license key string to remove
  • force If true, removes the license even if deactivation fails (default: false)

Returns:

  • RTErrc::NotInitialized API has not been initialized
  • RTErrc::LicenseDoesNotExists License key is not found
  • RTErrc::LicenseDeactivationError Deactivation failed and force is false

Return: Expected void on success, or error on failure

Note:

  • If force=false (safe mode), removal only succeeds if deactivation works or machine is not activated
  • If force=true, deletes certificate files regardless of deactivation status

Warning: Using force=true when deactivation fails may leave the machine activated server-side, consuming a machine slot

Attempts to deactivate the machine from the license server (if activated) and removes the license certificate files. The force parameter allows removal even if deactivation fails.

// Safe removal (only succeeds if deactivation works)
auto result = cvedia::rt::api::license::removeLicenseKey("XXXX-XXXX-XXXX-XXXX");

// Force removal (removes files even if deactivation fails)
auto forced = cvedia::rt::api::license::removeLicenseKey("XXXX-XXXX-XXXX-XXXX", true);

function loadLicenses

expected< void > loadLicenses()

Loads or reloads all licenses from the licenses directory.

Returns:

  • RTErrc::NotInitialized API has not been initialized

Return: Expected void on success, or error on failure

Note: Useful to refresh licenses after manual installation of license files without restarting

Scans the licenses directory for certificate files and updates the license enforcement system. Automatically called during system initialization but can be called manually to refresh licenses.

function unloadLicenses

expected< void > unloadLicenses()

Unloads all currently loaded licenses from the system.

Returns:

  • RTErrc::NotInitialized API has not been initialized

Return: Expected void on success, or error on failure

Note: Intended for shutdown scenarios or when preparing to load a different set of licenses

Warning: This will revoke all feature access and may cause running instances to fail

Removes all licenses from memory and revokes all feature access.

function activateTrialLicense

expected< bool > activateTrialLicense()

Activates a trial license for the current machine.

Returns:

  • RTErrc::NotInitialized API has not been initialized

Return: Expected bool where true indicates a new trial was activated, false indicates trial already exists

Note:

  • Only one trial can be activated per machine
  • Requires network connectivity to the license server

Contacts the license server to activate a trial license if one is not already active. Trial licenses typically have time limits and reduced feature allowances.

function activateAndRetrieveTrialLicense

expected< std::string > activateAndRetrieveTrialLicense()

Activates a trial license and returns the trial license key.

Returns:

  • RTErrc::NotInitialized API has not been initialized

Return: Expected string containing the trial license key

Note: Useful when the trial key needs to be displayed or logged after activation

Combines trial activation and key retrieval in one operation. Returns the trial key even if the trial was previously activated.

function inform

expected< IntentResponse > inform(
    LicenseTag const licenseTag,
    Intent const intent,
    Uuid const & instanceId,
    bool keepDemand =true,
    pCValue const & context =nullptr
)

Informs the license enforcement system about feature usage intent.

Parameters:

  • licenseTag The feature being requested or released (e.g., LicenseTag::Streams)
  • intent Either Intent::Demand (request access) or Intent::Release (release access)
  • instanceId UUID of the instance making the request
  • keepDemand If true, maintains demand even after grant (persistent demand); default: true

Returns:

  • IntentResponse::DemandGranted Access granted to the feature
  • IntentResponse::DemandNotGranted Access denied (license limit reached)
  • IntentResponse::DemandAlreadyGranted Feature already granted to this instance
  • IntentResponse::DemandReduced Feature access successfully released
  • IntentResponse::DemandAcknowledgedNotGranted Demand recorded but not granted

See: informLabel() for string-based license tag specification

Return: Expected IntentResponse indicating the outcome:

Note:

  • keepDemand=true maintains persistent demand, useful for features that should remain allocated
  • keepDemand=false removes demand once granted (one-time grant)
  • Always check return value before using licensed features
  • The optional context identifies an independent holder of the demand within the instance (e.g. an entity or feature id) when a single license tag covers multiple features. Demands are idempotent per context and the grant is only fully released once the last context releases. When null, a reserved default context is used, which keeps the single-shot idempotent inform/release behavior.

Implements the intent-based license enforcement model. Call with Intent::Demand to request access to a licensed feature before using it, and Intent::Release when finished to free up the license allowance for other instances.

// Request stream allocation
auto response = cvedia::rt::api::license::inform(
    LicenseTag::Streams,
    Intent::Demand,
    instanceId,
    true  // Keep demand after grant
);

if (response && response.value() == IntentResponse::DemandGranted) {
    // Use the stream
    std::cout << "Stream allocated successfully" << std::endl;
}

// Release stream when done
cvedia::rt::api::license::inform(
    LicenseTag::Streams,
    Intent::Release,
    instanceId
);

function informLabel

expected< IntentResponse > informLabel(
    Intent const intent,
    Uuid const & instanceId,
    std::string const & label
)

Informs the license system using a string label instead of LicenseTag enum.

Parameters:

  • intent Either Intent::Demand or Intent::Release
  • instanceId UUID of the instance making the request
  • label String representation of the license tag

Returns:

  • RTErrc::InvalidArgument Label is not recognized as a valid license tag

See: inform() for the enum-based version with keepDemand parameter

Return: Expected IntentResponse with same outcomes as inform()

Note:

  • Accepted labels (case-sensitive):

  • "streams", "max_streams", "MaxStreams"

  • "standard_analytics", "StandardAnalytics"
  • "armed_person_analytics", "ArmedPersonAnalytics"
  • "fallen_person_analytics", "FallenPersonAnalytics"
  • "license_plate_analytics", "LicensePlateAnalytics"
  • "smoke_and_fire_detection", "SmokeAndFireDetection"
  • legacy beta aliases "scene_wide_smoke_or_fire", "SceneWideSmokeOrFire"
  • "ppe_analytics", "PpeAnalytics"
  • Useful when license tags come from configuration files or REST APIs

Convenience function for feature intent operations when license tags are specified as strings. Internally converts the label to a LicenseTag and calls inform().

auto response = cvedia::rt::api::license::informLabel(
    Intent::Demand,
    instanceId,
    "armed_person_analytics"
);