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

C API Reference

License

The license state of this device, or of this program under a Developer license, and the calls that refresh, activate and deactivate it.

On this page

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 DeformableStatus; 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”.

deformable_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. deformable_license_status never contacts the licensing service and is cheap enough to call on every redraw. deformable_license_refresh, deformable_license_activate and deformable_license_deactivate wait on the network for at most their timeout, so a host with an interface calls them off its interface thread. deformable_license_set_online_access keeps a process off the network when its user asked for that.

DeformableLicenseState

Enum · deformable.h

c
typedef int32_t DeformableLicenseState;

The license state of this program, as DeformableLicenseStatus reports it in state: its Developer license, or else the Standard license of this device and user, which every program that loads the library shares.

Values

  • DEFORMABLE_LICENSE_STATE_NOT_STARTED (0)No Standard trial or license yet: the next deformable_license_refresh, or the first engine call, starts the Standard trial online.
  • DEFORMABLE_LICENSE_STATE_STANDARD_TRIAL (1)The Standard trial runs: every feature, at most tetrahedron_limit (2,500) tetrahedrons per scene.
  • DEFORMABLE_LICENSE_STATE_STANDARD_TRIAL_ENDED (2)The Standard trial ended, or this device cannot have one; engine calls give DEFORMABLE_STATUS_LICENSE_REQUIRED until a license is activated.
  • DEFORMABLE_LICENSE_STATE_STANDARD_LICENSE (3)A Standard license is active on this device; no limit.
  • DEFORMABLE_LICENSE_STATE_NEEDS_ONLINE (4)A Standard license (or the Standard trial) needs one online check before engine calls work again.
  • DEFORMABLE_LICENSE_STATE_DEVELOPMENT (5)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.
  • DEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL (6)A Developer trial key runs in this program: every feature and no limit, until the key ends.
  • DEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL_ENDED (7)The Developer trial key of this program ended; engine calls give DEFORMABLE_STATUS_LICENSE_REQUIRED.
  • DEFORMABLE_LICENSE_STATE_DEVELOPER_LICENSE (8)A Developer license key runs in this program; no limit and no end.

See also Guide: License · Rust LicenseState · Python LicenseState

DeformableLicenseStatus

Struct · deformable.h

c
typedef struct DeformableLicenseStatus {
    DeformableLicenseState state;
    uint32_t days_left;
    uint32_t tetrahedron_limit;
    uint8_t usable;
    uint8_t needs_online;
    uint8_t has_license_key;
    char message[64];
} DeformableLicenseStatus;

The license state as a status line shows it.

Fields

  • state (DeformableLicenseState)Which license state the program is in; the other fields detail it.
  • days_left (uint32_t)The whole days left counting the current day: in DEFORMABLE_LICENSE_STATE_STANDARD_TRIAL 7 down to 1, in DEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL the days until the trial key ends; 0 in any other state.
  • tetrahedron_limit (uint32_t)The most tetrahedrons one scene may hold: 2,500 in DEFORMABLE_LICENSE_STATE_STANDARD_TRIAL; 0 when there is no limit.
  • usable (uint8_t)1 when engine calls work (a trial, a license, or a development build).
  • needs_online (uint8_t)1 when the state changes only after an online check (not started, or needs online).
  • has_license_key (uint8_t)1 when a Standard license key is stored on this device, so a host offers Deactivate rather than Activate; 0 under a Developer license.
  • message (char[64])The status line, NUL-terminated UTF-8: “Standard trial: 7 days left”, “Standard license”, “Developer license: Acme Inc.”, … The company of a Developer license is cut to fit.

See also Guide: License · Rust LicenseStatus · Python LicenseStatus

deformable_license_status

Function · deformable.h

c
DeformableStatus deformable_license_status(
    DeformableLicenseStatus *status);

Writes the license state of this program to status: 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.

Parameters

Errors

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

Example

c
DeformableLicenseStatus status;
CHECK(deformable_license_status(&status));
if (!status.usable)
    puts(status.message);

See also Guide: License · Rust status · Python license.status

deformable_license_refresh

Function · deformable.h

c
DeformableStatus deformable_license_refresh(
    uint32_t timeout_milliseconds,
    DeformableLicenseStatus *status);

Brings the license up to date with the licensing service when a contact is due, waiting at most timeout_milliseconds. 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_milliseconds (uint32_t)How long to wait for the service, in milliseconds: at least 1; above 60,000 counts as 60,000. 15,000 (15 s) suits a host with no reason to choose otherwise.
  • status (DeformableLicenseStatus *)Out. Receives the license state after the call, on success and on a DEFORMABLE_STATUS_LICENSE_* failure, so a host shows the state after a failure too. May be NULL.

Errors

Example

c
DeformableLicenseStatus status;
if (deformable_license_refresh(15000, &status))
    puts(deformable_last_error_message());
else
    puts(status.message);

See also Guide: License · Rust refresh · Python license.refresh

deformable_license_activate

Function · deformable.h

c
DeformableStatus deformable_license_activate(
    const char *license_key,
    uint32_t timeout_milliseconds,
    DeformableLicenseStatus *status);

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_milliseconds; the state is then DEFORMABLE_LICENSE_STATE_STANDARD_LICENSE. 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 activates it at every start, as its first Deformable call, before status and refresh. The state is then DEFORMABLE_LICENSE_STATE_DEVELOPER_LICENSE, or DEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL for a trial key. The same key again changes nothing. A development build of the library checks the key the same way but stays DEFORMABLE_LICENSE_STATE_DEVELOPMENT.

On failure, deformable_last_error_message says why the key was not activated, written to show the user as it is.

Parameters

  • license_key (const char *)The license key, NUL-terminated UTF-8: 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_milliseconds (uint32_t)How long to wait for the service, in milliseconds: at least 1; above 60,000 counts as 60,000. 15,000 (15 s) suits a host with no reason to choose otherwise. A Developer key never waits.
  • status (DeformableLicenseStatus *)Out. Receives the license state after the call, on success and on a DEFORMABLE_STATUS_LICENSE_* failure, so a host shows the state after a failure too, except after a refused Developer key in a program that has neither set a Developer license nor read its license state yet, so a refused key leaves nothing on the computer. May be NULL.

Errors

  • DEFORMABLE_STATUS_INVALID_ARGUMENTlicense_key is not UTF-8 or no license key, a Developer key that does not verify, another Standard key while one is stored on this device (“Deactivate the current license first”), another Developer key once one is set (“Another Developer license key is already set in this program”), or a Standard key in a program on a Developer license (“This program uses a Developer license”); or timeout_milliseconds is 0. Nothing changes then.
  • DEFORMABLE_STATUS_LICENSE_KEY_REJECTEDThe 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 (“This Developer license key was revoked”), is a trial key that ended (“Developer trial ended — Contact us”), or was given inside a plugin host, where only a Standard license works.
  • DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached, refused this copy of the library, or gave an answer that did not verify, or deformable_license_set_online_access forbade every contact.
  • DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license state could not be written; the message names its folder.

Example

c
DeformableLicenseStatus status;
const char *key = "TGDF-XXXX-XXXX-XXXX";
if (deformable_license_activate(key, 15000, &status))
    puts(deformable_last_error_message());
else
    puts(status.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.
const char *developer_key = "TGDF-eyJ2ZXJzaW9uIjoxfQ.c2lnbmF0dXJl";
if (deformable_license_activate(developer_key, 15000, &status))
    puts(deformable_last_error_message());

See also Guide: License · Rust activate · Python license.activate

deformable_license_deactivate

Function · deformable.h

c
DeformableStatus deformable_license_deactivate(
    uint32_t timeout_milliseconds,
    DeformableLicenseStatus *status);

Frees this device’s seat with the licensing service, then forgets the key, waiting at most timeout_milliseconds, 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_milliseconds (uint32_t)How long to wait for the service, in milliseconds: at least 1; above 60,000 counts as 60,000. 15,000 (15 s) suits a host with no reason to choose otherwise.
  • status (DeformableLicenseStatus *)Out. Receives the license state after the call, on success and on a DEFORMABLE_STATUS_LICENSE_* failure, so a host shows the state after a failure too. May be NULL.

Errors

Example

c
DeformableLicenseStatus status;
CHECK(deformable_license_deactivate(15000, &status));
// has_license_key is 0 now: the host offers Activate again.
puts(status.message);

See also Guide: License · Rust deactivate · Python license.deactivate

deformable_license_set_online_access

Function · deformable.h

c
DeformableStatus deformable_license_set_online_access(uint8_t allowed);

Allows (allowed not 0, the default) or forbids (allowed 0) every contact with the licensing service from this process, for a host whose user turned online access off. Forbidden, nothing is sent: deformable_license_refresh, deformable_license_activate and deformable_license_deactivate give DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLE 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 deformable_license_refresh and deformable_license_deactivate contact nothing and succeed. It grants nothing and reads no license state, and it fails only when the library fails inside.

Parameters

  • allowed (uint8_t)Not 0 allows every contact, 0 forbids them.

Errors

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

Example

c
// The user turned online access off in the host's settings.
CHECK(deformable_license_set_online_access(0));

See also Guide: License · Rust set_online_access · Python license.set_online_access