You are viewing the documentation for Deformable v0.8.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 an Application license, and the calls that refresh it, sign in to a subscription, and activate and deactivate a license.
On this page
- Deformable
License State - Deformable
License Status - Deformable
Sign In - deformable_
license_ status - deformable_
license_ refresh - deformable_
license_ start_ sign_ in - deformable_
license_ wait_ for_ sign_ in - deformable_
license_ take_ over - deformable_
license_ sign_ out - deformable_
license_ activate - deformable_
license_ deactivate - deformable_
license_ set_ online_ access
The license: its state, and the calls that refresh it, sign in to a subscription, and activate and deactivate a license. Nothing ever refuses to run: without a subscription or a license, Free runs, and a scene simulates at most 2,500 tetrahedrons. Three ways lift the limit: the Standalone subscription the person signs in to, the Standalone license of this device and user, and the Application license that a program activates for itself. A license failure’s message is written to show the user as it is, such as “Free: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”.
deformable_license_start_sign_in starts a sign-in to a Standalone subscription: it gives a DeformableSignIn whose code the person approves in their browser, and deformable_license_wait_for_sign_in waits for that approval, then takes this device’s seat. deformable_license_take_over moves the seat to this device from the one using it, and deformable_license_sign_out frees the seat and forgets the sign-in. deformable_license_activate takes both kinds of key. A Standalone key is activated online once and stays on the device; the library keeps one Standalone state per device and user, shared by every program that loads it: the plugins and the SDKs. An Application 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. deformable_license_status never contacts the licensing service and is cheap enough to call on every redraw. The other calls 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
typedef int32_t DeformableLicenseState;The license state of this program, as DeformableLicenseStatus reports it in state: its Application license, or
else the Standalone subscription, the Standalone license or Free of this device and user, which every program that
loads the library shares.
Values
DEFORMABLE_LICENSE_STATE_FREE(0)No license key and no sign-in: Free, at mosttetrahedron_limit(2,500) tetrahedrons per scene.DEFORMABLE_LICENSE_STATE_STANDALONE_SUBSCRIPTION(1)Signed in to a Standalone subscription, and this device holds a seat whose lease licenses it; no limit.DEFORMABLE_LICENSE_STATE_SUBSCRIPTION_NEEDS_ONLINE(2)Signed in, but no subscription lease licenses this device now: it lapsed, this device’s clock leaves it untrusted, or the first seat could not be taken. Free runs until the next renewal online.DEFORMABLE_LICENSE_STATE_SUBSCRIPTION_NO_SEAT(3)Signed in, but this device holds no seat: another device took it over, it was removed, or every seat is in use. Free runs; a host offers to use the subscription here instead (deformable_license_take_over).DEFORMABLE_LICENSE_STATE_NO_SUBSCRIPTION(4)Signed in, but the account has no active Standalone subscription: Free runs.DEFORMABLE_LICENSE_STATE_SIGN_IN_ENDED(5)The licensing service no longer accepts the stored sign-in: Free runs until the person signs in again.DEFORMABLE_LICENSE_STATE_STANDALONE_LICENSE(6)A Standalone license key with a lease that licenses this device; no limit.DEFORMABLE_LICENSE_STATE_LICENSE_NEEDS_ONLINE(7)A Standalone license key whose lease ran out, or that this device’s clock leaves untrusted: Free runs until the next renewal online.DEFORMABLE_LICENSE_STATE_DEVELOPMENT(8)A development build of the library: licensing is off, no limit, and nothing contacts the licensing service. It is not the Application license.DEFORMABLE_LICENSE_STATE_APPLICATION_TRIAL(9)An Application trial key runs in this program: no limit, until the key ends.DEFORMABLE_LICENSE_STATE_APPLICATION_TRIAL_ENDED(10)The Application trial key of this program ended: Free runs.DEFORMABLE_LICENSE_STATE_APPLICATION_LICENSE(11)A full Application license key runs in this program; no limit.
See also Guide: License · Rust LicenseState · Python LicenseState
DeformableLicenseStatus
Struct · deformable.h
typedef struct DeformableLicenseStatus {
DeformableLicenseState state;
uint32_t days_left;
uint32_t tetrahedron_limit;
uint8_t has_license_key;
uint8_t signed_in;
char message[128];
char account[256];
} 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)InDEFORMABLE_LICENSE_STATE_APPLICATION_TRIAL, the whole days until the trial key ends counting the current day; 0 in any other state.tetrahedron_limit(uint32_t)The most tetrahedrons one scene simulates: 2,500 under Free and every state that falls back to it, 0 when there is no limit.has_license_key(uint8_t)1 when a Standalone license key is stored on this device, so a host offers Deactivate rather than Activate; 0 under an Application license.signed_in(uint8_t)1 when a Standalone subscription sign-in is stored on this device, so a host offers Sign Out; inDEFORMABLE_LICENSE_STATE_SIGN_IN_ENDEDit offers Sign In again too. 0 under an Application license.message(char[128])The status line, NUL-terminated UTF-8: “Free: up to 2,500 tetrahedrons per scene”, “Standalone subscription”, “Standalone license”, “Application license: Acme Inc.”, … A device or company name in it is cut to fit.account(char[256])The email of the signed-in account, NUL-terminated UTF-8, or empty.
See also Guide: License · Rust LicenseStatus · Python LicenseStatus
DeformableSignIn
Struct · deformable.h
typedef struct DeformableSignIn {
char user_code[16];
char verification_url[256];
uint32_t expires_in_seconds;
} DeformableSignIn;A sign-in to a Standalone subscription in progress, as deformable_license_start_sign_in writes it.
Fields
user_code(char[16])The code to approve in the browser, NUL-terminated, such as"ABCD-EFGH".verification_url(char[256])The page that approves it, NUL-terminated UTF-8; the host opens it in the browser.expires_in_seconds(uint32_t)How long the code lasts from now, in seconds.
See also Guide: License · Rust SignIn · Python SignIn
deformable_license_status
Function · deformable.h
DeformableStatus deformable_license_status(
DeformableLicenseStatus *status);Writes the license state of this program to status: its Application license, or else the Standalone subscription, the
Standalone license or Free 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.
Parameters
status(DeformableLicenseStatus *)Out. Receives the license state.
Errors
- Only the statuses every call can give, which the conventions describe.
Example
DeformableLicenseStatus status;
CHECK(deformable_license_status(&status));
if (status.tetrahedron_limit)
printf("%s (%u per scene)\n", status.message,
(unsigned)status.tetrahedron_limit);See also Guide: License · Rust status · Python license.status
deformable_license_refresh
Function · deformable.h
DeformableStatus deformable_license_refresh(
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Renews the stored Standalone 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_milliseconds. With a Standalone
subscription instead, renews its lease when no contact ran in the last 5 minutes, so a seat taken over or removed, or
a subscription that ended, shows at once; without a current lease or a seat, renews it or takes a free seat whatever
the last contact was, never one another device holds. Under Free, after the sign-in ended, and under an Application
license, nothing is sent and it gives the state as it is. The engine renews a lease on its own while it 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_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 aDEFORMABLE_STATUS_LICENSE_*failure, so a host shows the state after a failure too. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTtimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not answer, its answer did not verify or this device’s clock contradicts it, ordeformable_license_set_online_accessforbade every contact. The lease is kept until it runs out.DEFORMABLE_STATUS_LICENSE_KEY_REJECTEDThe service no longer accepts the key: it was revoked or refunded, or this device was removed. The license is then forgotten at once and Free runs.DEFORMABLE_STATUS_LICENSE_SIGN_IN_FAILEDThe service could not read the request. A subscription that gives this device no seat is no failure: the state says it.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store could not be written; the message names its folder.
Example
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_start_sign_in
Function · deformable.h
DeformableStatus deformable_license_start_sign_in(
uint32_t timeout_milliseconds,
DeformableSignIn *sign_in);Starts a sign-in to a Standalone subscription in the browser, waiting at most timeout_milliseconds for the licensing
service: the host shows sign_in->user_code and opens sign_in->verification_url, where the person approves it, then
calls deformable_license_wait_for_sign_in until it reports the approval. Starting again replaces the sign-in this
process started before. It waits on the network, so a host with an interface calls it off its interface thread. A
development build of the library has licensing off and gives DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLE.
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.sign_in(DeformableSignIn *)Out. Receives the code and the page to approve it on.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTA Standalone key is stored (“Deactivate the current license first”), a sign-in is stored, except inDEFORMABLE_LICENSE_STATE_SIGN_IN_ENDED(“Sign out of the Standalone subscription first”), the program uses an Application license, ortimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SIGN_IN_FAILEDThis version of the library may not sign in, or the service could not read the request.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not answer,deformable_license_set_online_accessforbade every contact, or licensing is off in a development build.
Example
DeformableSignIn sign_in;
if (deformable_license_start_sign_in(15000, &sign_in))
puts(deformable_last_error_message());
else
printf("Open %s and approve the code %s\n",
sign_in.verification_url, sign_in.user_code);See also Guide: License · Rust start_sign_in · Python license.start_sign_in
deformable_license_wait_for_sign_in
Function · deformable.h
DeformableStatus deformable_license_wait_for_sign_in(
uint32_t timeout_milliseconds,
uint8_t *approved,
DeformableLicenseStatus *status);Waits at most timeout_milliseconds for the person to approve the sign-in deformable_license_start_sign_in started,
polling the licensing service as often as it allows, then takes this device a free seat of the subscription. It
writes 1 to approved once approved, status then holding the state after the seat
(DEFORMABLE_LICENSE_STATE_STANDALONE_SUBSCRIPTION when a seat was free), or 0 while not yet, status holding the
state now. It never returns before its timeout without an answer, so a host loop of short waits does not spin, and
it may return up to 25 s after it: a poll already sent is given 10 s to answer, and once approved, the seat is given
15 s of its own. A host runs it off its interface thread. A development build of the library has licensing off and
reports approved 1 and DEFORMABLE_LICENSE_STATE_DEVELOPMENT at once.
Parameters
timeout_milliseconds(uint32_t)How long to wait for the approval, in milliseconds: at least 1; above 60,000 counts as 60,000. 5,000 (5 s) suits a host loop that also watches for its user cancelling.approved(uint8_t *)Out. Receives 1 once the account approved the sign-in, 0 while not yet.status(DeformableLicenseStatus *)Out. Receives the license state, on success and on aDEFORMABLE_STATUS_LICENSE_*failure. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTNo sign-in was started in this process (“Sign in first”), the program uses an Application license, ortimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SIGN_IN_FAILEDThe sign-in was denied, its code is no longer valid, this version of the library may not sign in, or the service could not read the request: the sign-in is forgotten, and a new one starts withdeformable_license_start_sign_in.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEdeformable_license_set_online_accessforbade every contact.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe sign-in could not be stored; the message names the folder.
Example
uint8_t approved = 0;
DeformableLicenseStatus status;
while (!approved) {
if (deformable_license_wait_for_sign_in(5000, &approved,
&status)) {
puts(deformable_last_error_message());
break;
}
}
if (approved)
puts(status.message);See also Guide: License · Rust wait_for_sign_in · Python license.wait_for_sign_in
deformable_license_take_over
Function · deformable.h
DeformableStatus deformable_license_take_over(
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Uses the signed-in Standalone subscription on this device instead of another, waiting at most timeout_milliseconds:
takes a free seat, or else the seat refreshed longest ago, whose device stops at its next check-in. A host offers it
in DEFORMABLE_LICENSE_STATE_SUBSCRIPTION_NO_SEAT. 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 aDEFORMABLE_STATUS_LICENSE_*failure. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTNo sign-in is stored, or the stored sign-in ended (“Sign in first”), a Standalone key is stored, the program uses an Application license, ortimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not answer, its answer did not verify or this device’s clock contradicts it, ordeformable_license_set_online_accessforbade every contact.DEFORMABLE_STATUS_LICENSE_SIGN_IN_FAILEDThe service could not read the request.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store could not be written; the message names its folder.
Example
DeformableLicenseStatus status;
CHECK(deformable_license_status(&status));
if (status.state == DEFORMABLE_LICENSE_STATE_SUBSCRIPTION_NO_SEAT &&
deformable_license_take_over(15000, &status))
puts(deformable_last_error_message());See also Guide: License · Rust take_over · Python license.take_over
deformable_license_sign_out
Function · deformable.h
DeformableStatus deformable_license_sign_out(
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Signs out of the Standalone subscription on this device at once, even offline, so Free runs; then frees this
device’s seat and ends its session with the licensing service, waiting at most timeout_milliseconds. Without a
sign-in, or under an Application 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 aDEFORMABLE_STATUS_LICENSE_*failure. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTtimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe seat could not be freed: the service could not be reached, ordeformable_license_set_online_accessforbade every contact. The sign-in is forgotten here all the same, and the seat frees itself within a day.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store could not be changed; the message names its folder.
Example
DeformableLicenseStatus status;
CHECK(deformable_license_sign_out(15000, &status));
// signed_in is 0 now: the host offers Sign In again.
puts(status.message);See also Guide: License · Rust sign_out · Python license.sign_out
deformable_license_activate
Function · deformable.h
DeformableStatus deformable_license_activate(
const char *license_key,
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Activates license_key, a Standalone or an Application license key, told apart by their shape: a Standalone key is
tgdfp-xxxxx-xxxxx-xxxxx-xxxxx, an Application key tgdfp-<payload hex>-<signature hex>.
A Standalone key is activated on this device with the licensing service, waiting at most timeout_milliseconds; the
state is then DEFORMABLE_LICENSE_STATE_STANDALONE_LICENSE. 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.
An Application 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_APPLICATION_LICENSE, or DEFORMABLE_LICENSE_STATE_APPLICATION_TRIAL 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. 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, where letter case does not matter and spaces and line breaks are removed.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. An Application key never waits.status(DeformableLicenseStatus *)Out. Receives the license state after the call, on success and on aDEFORMABLE_STATUS_LICENSE_*failure, so a host shows the state after a failure too, except after a refused Application key in a program that has neither set an Application license nor read its license state yet, so a refused key leaves nothing on the device. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTlicense_keyis not UTF-8 or no license key (“This is not a license key”), an Application key that does not verify (“This license key is not valid”), another Standalone key while one is stored on this device (“Deactivate the current license first”), a Standalone key while a Standalone subscription is signed in (“Sign out of the Standalone subscription first”), another Application key once one is set (“Another Application license key is already set in this program”), or a Standalone key in a program on an Application license (“This program uses an Application license”); ortimeout_millisecondsis 0. Nothing changes then.DEFORMABLE_STATUS_LICENSE_KEY_REJECTEDThe service refused the Standalone key: it does not exist, was revoked or refunded, is not for Deformable, or every seat of the license is in use. Or the Application key was revoked (“This Application license key was revoked”), is a trial key that ended (“Application trial ended — Buy license”), covers only versions released before this one, or was given inside a plugin host, where it does not work.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not answer, its answer did not verify or this device’s clock contradicts it, ordeformable_license_set_online_accessforbade every contact.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store could not be written; the message names its folder.
Example
DeformableLicenseStatus status;
const char *key = "tgdfp-xxxxx-xxxxx-xxxxx-xxxxx";
if (deformable_license_activate(key, 15000, &status))
puts(deformable_last_error_message());
else
puts(status.message);
// An app on an Application license activates its key, exactly as
// copied from the Licenses page, first thing at every start.
// This one is shaped like an Application key but signed by
// nobody, so it is refused.
const char *application_key =
"tgdfp-7b2276657273696f6e223a317d-"
"0000000000000000000000000000000000000000000000000000000000000000"
"0000000000000000000000000000000000000000000000000000000000000000";
if (deformable_license_activate(application_key, 15000, &status))
puts(deformable_last_error_message());See also Guide: License · Rust activate · Python license.activate
deformable_license_deactivate
Function · deformable.h
DeformableStatus deformable_license_deactivate(
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Forgets the Standalone license on this device at once, even offline, so Free runs; then frees its seat
with the licensing service, waiting at most timeout_milliseconds, 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 an
Application 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 aDEFORMABLE_STATUS_LICENSE_*failure, so a host shows the state after a failure too. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTtimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe seat could not be freed: the service could not be reached, ordeformable_license_set_online_accessforbade every contact. The license is forgotten here all the same.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store could not be changed; the message names its folder.
Example
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
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_start_sign_in, deformable_license_wait_for_sign_in, deformable_license_take_over and
deformable_license_activate give DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLE and change nothing,
deformable_license_sign_out and deformable_license_deactivate forget the sign-in or license without freeing its seat,
and the engine never renews a lease on its own, so it runs out as it would offline. An Application key is checked
offline and is not affected. 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
// 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