﻿---
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.3.0/api-references/rust/license/
---

# License – Rust API Reference – Deformable v0.3.0

The license: its state, and the calls that refresh, activate and deactivate it. Nothing ever refuses to run: without a license the Free license runs, and a scene simulates at most 2,500 tetrahedrons. Two licenses lift the limit: the Standard license of this device and user, and the Developer license that a program activates for itself. A license failure's message is written to show the user as it is, such as "Free license: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene".

[`activate`](https://help.tangerina.io/deformable/v0.3.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 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.3.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.3.0/api-references/rust/license/#refresh), [`activate`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#activate) and [`deactivate`](https://help.tangerina.io/deformable/v0.3.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.3.0/api-references/rust/license/#set_online_access) keeps a process off the network when its user asked for that.

- The Standard license runs on 1 device per seat. Its key and the lease our licensing service signs for this
  device belong to this device and user, and every program that loads the library shares them; [`activate`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#activate),
  [`refresh`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#refresh) and [`deactivate`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#deactivate) activate, renew and deactivate it. The lease renews on its own while the engine
  runs, and a device may stay offline up to 14 days.
- 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 device, 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.3.0/api-references/rust/errors/#errorkind-is_license) tells a license failure, such as [`ErrorKind::TetrahedronLimitExceeded`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-tetrahedronlimitexceeded) or
[`ErrorKind::LicenseKeyRejected`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licensekeyrejected), from the others.

## LicenseState

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

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

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

**Values**

- `FreeLicense`: No license key: the Free license, at most [`LicenseStatus::tetrahedron_limit`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#licensestatus) (2,500) tetrahedrons per scene.
- `StandardLicense`: A Standard license key with a lease that licenses this device; no limit.
- `NeedsOnline`: A Standard license key whose lease ran out, or that this device's clock leaves untrusted: the Free license runs
  until the next renewal online.
- `Development`: A development build of the library: licensing is off, no limit, and nothing contacts the licensing service. It
  is not the Developer license.
- `DeveloperTrial`: A Developer trial key runs in this program: no limit, until the key ends.
- `DeveloperTrialEnded`: The Developer trial key of this program ended: the Free license runs.
- `DeveloperLicense`: A full Developer license key runs in this program; no limit.
- `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.3.0/user-guides/rust/getting-started/#license) · [C `DeformableLicenseState`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/license/#deformablelicensestate) · [Python `LicenseState`](https://help.tangerina.io/deformable/v0.3.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 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.3.0/api-references/rust/license/#licensestate)): Which license state the program is in; the other fields detail it.
- `days_left` (`u32`): In [`LicenseState::DeveloperTrial`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#licensestate-developertrial), the whole days until the trial key ends counting the current day, 30 down
  to 1 for a 30-day key; 0 in any other state.
- `tetrahedron_limit` (`Option<u32>`): The most tetrahedrons one scene simulates: 2,500 under the Free license and every state that falls back to it;
  `None` when there is no limit.
- `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: "Free license: up to 2,500 tetrahedrons per scene — Buy license", "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.3.0/user-guides/rust/getting-started/#license) · [C `DeformableLicenseStatus`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/license/#deformablelicensestatus) · [Python `LicenseStatus`](https://help.tangerina.io/deformable/v0.3.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 Free or 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 store
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.3.0/api-references/rust/overview/#conventions) describe.

**Example**

```rust
let status = deformable::license::status()?;
if let Some(limit) = status.tetrahedron_limit {
    println!("{} ({limit} per scene)", status.message);
}
```

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.3.0/user-guides/rust/getting-started/#license) · [C `deformable_license_status`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/license/#deformable_license_status) · [Python `license.status`](https://help.tangerina.io/deformable/v0.3.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.3.0/api-references/rust/license/#refresh), [`activate`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#activate) and [`deactivate`](https://help.tangerina.io/deformable/v0.3.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.3.0/user-guides/rust/getting-started/#license) · [Python `license.DEFAULT_TIMEOUT`](https://help.tangerina.io/deformable/v0.3.0/api-references/python/license/#license-default_timeout)

## refresh

**Function** · `deformable::license::refresh`

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

Renews the stored Standard key's lease when it no longer licenses this device, or when it is 6 hours old or ends
within a day and no contact ran in the last 5 minutes, waiting at most `timeout`. Without a key, and under a
Developer license, nothing is sent and it gives the state as it is. The library renews the lease on its own while
the engine runs, so a host calls this when the program starts and when its user asks.

It waits on the network, so a host with an interface calls it off its interface thread. 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.3.0/api-references/rust/license/#licensestatus): The license state after the call. After a failure, [`status`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#status) gives the state to show.

**Errors**

- [`LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licenseserviceunavailable): The service could not be reached or did not answer, its answer did
  not verify or this device's clock contradicts it, or [`set_online_access`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#set_online_access) forbade every contact. The lease is
  kept until it runs out.
- [`LicenseKeyRejected`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licensekeyrejected): The service no longer accepts the key: it was revoked or refunded, or this
  device was removed. The license is then forgotten at once and the Free license runs.
- [`LicenseStorageFailed`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licensestoragefailed): The per-user license store 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.3.0/user-guides/rust/getting-started/#license) · [C `deformable_license_refresh`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/license/#deformable_license_refresh) · [Python `license.refresh`](https://help.tangerina.io/deformable/v0.3.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, told apart by their shape: a Standard key is
`tgdfp-xxxxx-xxxxx-xxxxx-xxxxx`, a Developer key `tgdfp-<payload hex>-<signature hex>`.

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.3.0/api-references/rust/license/#licensestate-standardlicense). The key already stored here renews its lease 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.3.0/api-references/rust/license/#licensestate-developerlicense), or [`LicenseState::DeveloperTrial`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#licensestate-developertrial) for a trial key. The same
key again changes nothing. A full key covers the versions of the library released until its updates end, and keeps
working in them forever. 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.3.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, where letter case does not matter and spaces and line breaks are removed.
- `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.3.0/api-references/rust/license/#licensestatus): The license state after the activation. After a license failure, [`status`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#status) gives the state to show.

**Errors**

- [`InvalidArgument`](https://help.tangerina.io/deformable/v0.3.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.3.0/api-references/rust/errors/#errorkind-licensekeyrejected): The service refused the Standard key: it does not exist, was revoked or
  refunded, is not for Deformable, or every seat of the license is in use. Or the Developer key was revoked, is a
  trial key that ended, covers only versions released before this one, or was given inside a plugin host.
- [`LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licenseserviceunavailable): The service could not be reached or did not answer, its answer did
  not verify or this device's clock contradicts it, or [`set_online_access`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#set_online_access) forbade every contact.
- [`LicenseStorageFailed`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licensestoragefailed): The per-user license store could not be written; the message names its
  folder.

**Example**

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

let key = "tgdfp-xxxxx-xxxxx-xxxxx-xxxxx";
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, exactly as
// copied from the Licenses page, first thing at every start.
// This one is shaped like a Developer key but signed by
// nobody, so it is refused.
let payload = "7b2276657273696f6e223a317d";
let developer_key = format!("tgdfp-{payload}-{}", "0".repeat(128));
if let Err(error) = license::activate(&developer_key, DEFAULT_TIMEOUT) {
    eprintln!("{}", error.message());
}
```

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

## deactivate

**Function** · `deformable::license::deactivate`

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

Forgets the Standard license on this device at once, even offline, so the Free license runs; then frees its seat
with the licensing service, waiting at most `timeout`, so the key can be activated on another device. When the seat
cannot be freed, the customer removes this device on the Licenses page. 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.3.0/api-references/rust/license/#licensestatus): The license state after the deactivation. After a failure, [`status`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#status) gives the state to show.

**Errors**

- [`LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licenseserviceunavailable): The seat could not be freed: the service could not be reached, or
  [`set_online_access`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#set_online_access) forbade every contact. The license is forgotten here all the same.
- [`LicenseStorageFailed`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licensestoragefailed): The per-user license store could not be changed; 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.3.0/user-guides/rust/getting-started/#license) · [C `deformable_license_deactivate`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/license/#deformable_license_deactivate) · [Python `license.deactivate`](https://help.tangerina.io/deformable/v0.3.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.3.0/api-references/rust/license/#refresh) and [`activate`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#activate) fail with
[`ErrorKind::LicenseServiceUnavailable`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licenseserviceunavailable) and change nothing, [`deactivate`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/license/#deactivate) forgets the license without freeing its
seat, and the library never renews the lease on its own, so it runs out as it would offline. A Developer key is
checked offline and is not affected. 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.3.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.3.0/user-guides/rust/getting-started/#license) · [C `deformable_license_set_online_access`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/license/#deformable_license_set_online_access) · [Python `license.set_online_access`](https://help.tangerina.io/deformable/v0.3.0/api-references/python/license/#license-set_online_access)
