﻿---
title: License
description: The license state of this device, or of this program under a Developer license, and the calls that refresh, activate and deactivate it.
url: https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/
---

# License – Rust API Reference – Deformable v0.2.0

The license: its state, and the calls that refresh, activate and deactivate it. There are two kinds: the Standard license of this device and user, and the Developer license that a program activates for itself. Every engine call checks the license first, and a call the license refuses fails with a license [`ErrorKind`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind); the error's message is written to show the user as it is, such as "Standard trial ended — Buy license" or "Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500".

[`activate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#activate) takes both kinds of key. A Standard key is activated online once and stays on the device; the library keeps one Standard state per device and user, shared by every program that loads it: the plugins and the SDKs. A Developer key holds a ".", is checked offline and holds for the process only, so a program activates it at every start, before any other engine call; with it, the other calls contact nothing, and a plugin host refuses it. [`status`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#status) never contacts the licensing service and is cheap enough to call on every redraw. [`refresh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#refresh), [`activate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#activate) and [`deactivate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#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`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#set_online_access) keeps a process off the network when its user asked for that.

- The Standard license is one person's on one computer. It and its free trial belong to this device and user, and
  every program that loads the library shares them; [`refresh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#refresh), [`activate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#activate) and [`deactivate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#deactivate) start, renew,
  activate and deactivate it with our licensing service.
- The Developer license is a company's, for one app it ships. Its key is checked offline and licenses the program
  that activates it, on any computer, for as long as it runs: nothing is stored or sent, so the app activates its
  key at every start, as its first Deformable call, before status and refresh, and its users need nothing. The
  plugins refuse a Developer key.

[`ErrorKind::is_license`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-is_license) tells the error of a call the trial or license does not allow, such as
[`ErrorKind::TrialLimitExceeded`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-triallimitexceeded) or [`ErrorKind::LicenseRequired`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licenserequired), from the others.

## LicenseState

**Enum** · `deformable::license::LicenseState`

```rust
pub enum LicenseState {
    NotStarted,
    StandardTrial,
    StandardTrialEnded,
    StandardLicense,
    NeedsOnline,
    Development,
    DeveloperTrial,
    DeveloperTrialEnded,
    DeveloperLicense,
    Unrecognized(i32),
}
```

The license state of this program, as [`LicenseStatus::state`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestatus) reports it: its Developer license, or else the
Standard license of this device and user, which every program that loads the library shares.

**Values**

- `NotStarted`: No Standard trial or license yet: the next [`refresh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#refresh), or the first engine call, starts the Standard trial
  online.
- `StandardTrial`: The Standard trial runs: every feature, at most [`LicenseStatus::tetrahedron_limit`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestatus) (2,500) tetrahedrons per
  scene.
- `StandardTrialEnded`: The Standard trial ended, or this device cannot have one; engine calls fail with [`ErrorKind::LicenseRequired`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licenserequired)
  until a license is activated.
- `StandardLicense`: A Standard license is active on this device; no limit.
- `NeedsOnline`: A Standard license (or the Standard trial) needs one online check before engine calls work again.
- `Development`: A development build of the library: licensing is off, engine calls always work and nothing contacts the
  licensing service. It is not the Developer license.
- `DeveloperTrial`: A Developer trial key runs in this program: every feature and no limit, until the key ends.
- `DeveloperTrialEnded`: The Developer trial key of this program ended; engine calls fail with [`ErrorKind::LicenseRequired`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licenserequired).
- `DeveloperLicense`: A Developer license key runs in this program; no limit and no end.
- `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](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [C `DeformableLicenseState`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/license/#deformablelicensestate) · [Python `LicenseState`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#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`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate)): Which license state the program is in; the other fields detail it.
- `days_left` (`u32`): The whole days left counting the current day: in [`LicenseState::StandardTrial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate-standardtrial) 7 down to 1, in
  [`LicenseState::DeveloperTrial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate-developertrial) the days until the trial key ends, 30 down to 1 for a 30-day key; 0 in any
  other state.
- `tetrahedron_limit` (`Option<u32>`): The most tetrahedrons one scene may hold: 2,500 in [`LicenseState::StandardTrial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate-standardtrial); `None` when there is no
  limit.
- `usable` (`bool`): Engine calls work (a trial, a license, or a development build).
- `needs_online` (`bool`): The state changes only after an online check (not started, or needs online).
- `has_license_key` (`bool`): A Standard license key is stored on this device, so a host offers Deactivate rather than Activate; never under
  a Developer license.
- `message` (`String`): The status line: "Standard trial: 7 days left", "Standard license", "Developer trial: 30 days left",
  "Developer license: Acme Inc.", ... The company of a Developer license is cut to fit.

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

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [C `DeformableLicenseStatus`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/license/#deformablelicensestatus) · [Python `LicenseStatus`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#licensestatus)

## status

**Function** · `deformable::license::status`

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

The license state of this program: its Developer license, or else the Standard license 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](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/overview/#conventions) describe.

**Example**

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

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [C `deformable_license_status`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/license/#deformable_license_status) · [Python `license.status`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#license-status)

## DEFAULT_TIMEOUT

**Constant** · `deformable::license::DEFAULT_TIMEOUT`

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

How long [`refresh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#refresh), [`activate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#activate) and [`deactivate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#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](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [Python `license.DEFAULT_TIMEOUT`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#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. Under a Developer license nothing is ever sent and it
gives the Developer state.

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`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestatus): The license state after the call. After a failure, [`status`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#status) gives the state to show.

**Errors**

- [`LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licenseserviceunavailable): The service could not be reached, refused this copy of the library,
  or gave an answer that did not verify, or [`set_online_access`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#set_online_access) forbade every contact.
- [`LicenseKeyRejected`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licensekeyrejected): The 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.
- [`LicenseStorageFailed`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licensestoragefailed): The 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](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [C `deformable_license_refresh`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/license/#deformable_license_refresh) · [Python `license.refresh`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#license-refresh)

## activate

**Function** · `deformable::license::activate`

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

Activates `license_key`, a Standard or a Developer license key: only a Developer key holds a `.`.

A Standard key is activated on this device with the licensing service, waiting at most `timeout`; the state is then
[`LicenseState::StandardLicense`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate-standardlicense). 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.

A Developer key is checked offline, without waiting, and licenses this program for as long as it runs: nothing is
stored or sent, so the program calls this at every start, as its first Deformable call, before status and refresh.
The state is then [`LicenseState::DeveloperLicense`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate-developerlicense), or [`LicenseState::DeveloperTrial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate-developertrial) for a trial key. The same
key again changes nothing. The plugins refuse a Developer key. A development build of the library checks the key the
same way but stays [`LicenseState::Development`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestate-development).

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: a Standard key such as `TGDF-XXXX-XXXX-XXXX`, where letter case, spaces and
  dashes do not matter, or a Developer key as it was sent, spaces around it aside.
- `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. A Developer key never waits.

**Returns**

[`LicenseStatus`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestatus): The license state after the activation. After a license failure, [`status`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#status) gives the state to show.

**Errors**

- [`InvalidArgument`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-invalidargument): `license_key` is no license key or a Developer key that does not verify; another
  Standard key is stored on this device: deactivate it first; another Developer key is already set in this
  program; or it is a Standard key in a program on a Developer license. Nothing changes then.
- [`LicenseKeyRejected`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licensekeyrejected): The service refused the Standard 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. Or the Developer key was revoked, is a trial key that ended, or was given inside a plugin host, where
  only a Standard license works.
- [`LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licenseserviceunavailable): The service could not be reached, refused this copy of the library,
  or gave an answer that did not verify, or [`set_online_access`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#set_online_access) forbade every contact.
- [`LicenseStorageFailed`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licensestoragefailed): The 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()),
}

// An app on a Developer license activates its key, as it was
// sent, first thing at every start. This one is a stand-in,
// refused as not valid.
let developer_key = "TGDF-eyJ2ZXJzaW9uIjoxfQ.c2lnbmF0dXJl";
if let Err(error) = license::activate(developer_key, DEFAULT_TIMEOUT) {
    eprintln!("{}", error.message());
}
```

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [C `deformable_license_activate`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/license/#deformable_license_activate) · [Python `license.activate`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#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, or under a Developer license, 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`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#licensestatus): The license state after the deactivation. After a failure, [`status`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#status) gives the state to show.

**Errors**

- [`LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licenseserviceunavailable): The service could not be reached or did not confirm, or
  [`set_online_access`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#set_online_access) forbade every contact. Nothing changes then; the device can also be removed in the license
  portal.
- [`LicenseStorageFailed`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-licensestoragefailed): The per-user license state could not be written; the message names its
  folder.

**Example**

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

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

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [C `deformable_license_deactivate`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/license/#deformable_license_deactivate) · [Python `license.deactivate`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#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`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#refresh), [`activate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#activate) and [`deactivate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#deactivate) fail with
[`ErrorKind::LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#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.
A Developer key is checked offline and is not affected, and under a Developer license [`refresh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#refresh) and
[`deactivate`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/license/#deactivate) contact nothing and succeed. 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](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/overview/#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](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/getting-started/#license) · [C `deformable_license_set_online_access`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/license/#deformable_license_set_online_access) · [Python `license.set_online_access`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/license/#license-set_online_access)
