You are viewing the documentation for Deformable v0.1.0, an older version. Read the latest, v0.9.0

Rust API Reference

License

The license state of this device, and the calls that refresh, activate and deactivate it.

On this page

The license of this device and user: its state, and the calls that refresh, activate and deactivate it. Every engine call checks the license first, and a call the license refuses fails with a license ErrorKind; the error’s message is written to show the user as it is, such as “Trial ended — Buy license” or “Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”.

The library keeps one license state per device and user, shared by every program that loads it: the plugins and the SDKs. status never contacts the licensing service and is cheap enough to call on every redraw. refresh, activate and deactivate wait on the network for at most their timeout, so a host with an interface calls them off its interface thread. set_online_access keeps a process off the network when its user asked for that.

ErrorKind::is_license tells the error of a call the trial or license does not allow, such as ErrorKind::TrialLimitExceeded or ErrorKind::LicenseRequired, from the others.

LicenseState

Enum · deformable::license::LicenseState

rust
pub enum LicenseState {
    NotStarted,
    Trial,
    TrialEnded,
    Licensed,
    NeedsOnline,
    Development,
    Unrecognized(i32),
}

The license state of this device and user, as LicenseStatus::state reports it. Every program that loads the library shares it.

Values

  • NotStartedNo trial or license yet: the next refresh, or the first engine call, starts the trial online.
  • TrialThe trial runs: every feature, at most LicenseStatus::tetrahedron_limit (2,500) tetrahedrons per scene.
  • TrialEndedThe trial ended, or this device cannot have one; engine calls fail with ErrorKind::LicenseRequired until a license is activated.
  • LicensedA license is active on this device; no limit.
  • NeedsOnlineA license (or the trial) needs one online check before engine calls work again.
  • DevelopmentA development build of the library: licensing is off, engine calls always work and nothing contacts the licensing service.
  • Unrecognized (i32)A state this crate does not know, from a newer library.

Implements Clone · Copy · Debug · Eq · Hash · PartialEq · Send · Sync

See also Guide: License · C DeformableLicenseState · Python LicenseState

LicenseStatus

Struct · deformable::license::LicenseStatus

rust
pub struct LicenseStatus {
    pub state: LicenseState,
    pub days_left: u32,
    pub tetrahedron_limit: Option<u32>,
    pub usable: bool,
    pub needs_online: bool,
    pub has_license_key: bool,
    pub message: String,
}

The license state as a status line shows it.

Fields

  • state (LicenseState)Which license state the device is in; the other fields detail it.
  • days_left (u32)In LicenseState::Trial, the whole days left, 7 down to 1, counting the current day; 0 in any other state.
  • tetrahedron_limit (Option<u32>)The most tetrahedrons one scene may hold: 2,500 in LicenseState::Trial; None when there is no limit.
  • usable (bool)Engine calls work (trial, licensed or development).
  • needs_online (bool)The state changes only after an online check (not started, or needs online).
  • has_license_key (bool)A license key is stored on this device, so a host offers Deactivate rather than Activate.
  • message (String)The status line: “Trial: 7 days left”, “Trial ended — Buy license”, “Licensed”, …

Implements Clone · Debug · Eq · PartialEq · Send · Sync

See also Guide: License · C DeformableLicenseStatus · Python LicenseStatus

status

Function · deformable::license::status

rust
pub fn status() -> Result<LicenseStatus, Error>

The license state of this device and user. It never contacts the licensing service and never waits on the network: it reads the per-user license state at most once every 2 seconds, so it is cheap enough to call on every redraw.

Errors

  • Only the failures every call can give, which the conventions describe.

Example

rust
let status = deformable::license::status()?;
if !status.usable {
    println!("{}", status.message);
}

See also Guide: License · C deformable_license_status · Python license.status

DEFAULT_TIMEOUT

Constant · deformable::license::DEFAULT_TIMEOUT

rust
pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(15);

How long refresh, activate and deactivate wait for the licensing service when the host has no reason to choose otherwise: 15 seconds. The library counts anything above 60 seconds as 60 seconds.

See also Guide: License · Python license.DEFAULT_TIMEOUT

refresh

Function · deformable::license::refresh

rust
pub fn refresh(timeout: Duration) -> Result<LicenseStatus, Error>

Brings the license up to date with the licensing service when a contact is due, waiting at most timeout. A device that never started its trial starts it; a trial reports itself once a day and keeps the earliest start the service remembers for this device, so a reinstall does not restart it; a stored license renews when its last renewal is 6 hours old or it needs online. Otherwise nothing is sent.

It waits on the network, so a host with an interface calls it off its interface thread, such as when the program starts. Contacts run one at a time per process: a second caller waits for the first.

Parameters

  • timeout (Duration)How long to wait for the service, rounded up to whole milliseconds and at least 1 millisecond. The library counts anything above 60 seconds as 60 seconds.

Returns

LicenseStatus: The license state after the call. After a failure, status gives the state to show.

Errors

  • LicenseServiceUnavailableThe service could not be reached, refused this copy of the library, or gave an answer that did not verify, or set_online_access forbade every contact.
  • LicenseKeyRejectedThe service no longer accepts the stored license: it was revoked, this device was removed, or it is not a Deformable license. The license is then forgotten.
  • LicenseStorageFailedThe per-user license state could not be written; the message names its folder.

Example

rust
use deformable::license::{self, DEFAULT_TIMEOUT};

let status = license::refresh(DEFAULT_TIMEOUT)?;
println!("{}", status.message);

See also Guide: License · C deformable_license_refresh · Python license.refresh

activate

Function · deformable::license::activate

rust
pub fn activate(
    license_key: &str,
    timeout: Duration,
) -> Result<LicenseStatus, Error>

Activates license_key on this device with the licensing service, waiting at most timeout; the state is then LicenseState::Licensed. A key already active here is renewed instead. It waits on the network, so a host with an interface calls it off its interface thread.

The error’s message says why the key was not activated, written to show the user as it is.

Parameters

  • license_key (&str)The license key, such as TGDF-XXXX-XXXX-XXXX; letter case, spaces and dashes do not matter.
  • timeout (Duration)How long to wait for the service, rounded up to whole milliseconds and at least 1 millisecond. The library counts anything above 60 seconds as 60 seconds.

Returns

LicenseStatus: The license state after the activation. After a license failure, status gives the state to show.

Errors

  • InvalidArgumentlicense_key is no license key, or another key is stored on this device: deactivate it first. Nothing changes then.
  • LicenseKeyRejectedThe service refused the key: it does not exist, was revoked or expired, is not a Deformable license, or its seat is in use on another device; or the service takes no more devices.
  • LicenseServiceUnavailableThe service could not be reached, refused this copy of the library, or gave an answer that did not verify, or set_online_access forbade every contact.
  • LicenseStorageFailedThe per-user license state could not be written; the message names its folder.

Example

rust
use deformable::license::{self, DEFAULT_TIMEOUT};

let key = "TGDF-XXXX-XXXX-XXXX";
match license::activate(key, DEFAULT_TIMEOUT) {
    Ok(status) => println!("{}", status.message),
    Err(error) => println!("{}", error.message()),
}

See also Guide: License · C deformable_license_activate · Python license.activate

deactivate

Function · deformable::license::deactivate

rust
pub fn deactivate(timeout: Duration) -> Result<LicenseStatus, Error>

Frees this device’s seat with the licensing service, then forgets the key, waiting at most timeout, so the license can be activated on another computer. The key is forgotten only once the service confirms, or says the seat is already gone. With no key stored it does nothing and succeeds. It waits on the network, so a host with an interface calls it off its interface thread.

Parameters

  • timeout (Duration)How long to wait for the service, rounded up to whole milliseconds and at least 1 millisecond. The library counts anything above 60 seconds as 60 seconds.

Returns

LicenseStatus: The license state after the deactivation. After a failure, status gives the state to show.

Errors

Example

rust
use deformable::license::{self, DEFAULT_TIMEOUT};

let status = license::deactivate(DEFAULT_TIMEOUT)?;
assert!(!status.has_license_key);

See also Guide: License · C deformable_license_deactivate · Python license.deactivate

set_online_access

Function · deformable::license::set_online_access

rust
pub fn set_online_access(allowed: bool) -> Result<(), Error>

Allows (the default) or forbids every contact with the licensing service from this process, for a host whose user turned online access off. Forbidden, nothing is sent: refresh, activate and deactivate fail with ErrorKind::LicenseServiceUnavailable and change nothing, and engine calls neither start the trial nor renew the license on their own, so a state that needs the service stays as it is and a lease runs out as it would offline. It grants nothing, and it fails only when the library fails inside.

Parameters

  • allowed (bool)true allows every contact, false forbids them.

Errors

  • Only the failures every call can give, which the conventions describe.

Example

rust
// The user turned online access off in the host's settings.
deformable::license::set_online_access(false)?;

See also Guide: License · C deformable_license_set_online_access · Python license.set_online_access