TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class LicenceDomain in Tinman.Core.Licensing

The LicenceDomain class represents the client-side functionality of a licence domain.

sealed class LicenceDomain  

Public / Attributes

AllowUnlockByEnvironment

Allow licence domain to be unlocked via licence key found in environment variable?

public property AllowUnlockByEnvironment { get set }
type bool
value true to allow environment variable licence key, false to disable it.

Remarks:

After the licence domain has been unlocked, setting this property has no longer any effect.

Defaults to true.

See also:

IsUnlockedByEnvironment

IsUnlocked

Has this licence domain been unlocked?

[ThreadSafe]
public property IsUnlocked { get }
type bool
value true if this licence domain is unlocked, false if not.

IsUnlockedByApplication

Is this licence domain being activated from one of the licence keys that have been specified via LicenceKey?

public property IsUnlockedByApplication { get }
type bool
value true if this licence domain has been activated from one of the licence keys that have been specified via LicenceKey, false otherwise.

Remarks:

The TryUnlock method is called each time this property is get.

IsUnlockedByEnvironment

Is this licence domain being activated from the licence key that has been specified in the environment variable (see LicenceKey)?

public property IsUnlockedByEnvironment { get }
type bool
value true if this licence domain has been activated from the licence key that has been specified in the environment variable, false otherwise.

Remarks:

The TryUnlock method is called each time this property is get.

Name

Machine-readable name of this licence domain.

public property Name { get }
type string
value [not-empty] Licence domain name.

Tinman

The licence domain of the Tinman 3D SDK (tinman_3d).

public static property Tinman { get }
type LicenceDomain
value [not-null] The licence domain.

Remarks:

To obtain a new licence manually, you can use the Request and Request methods in your application to generate a licence request. Include the licence request file in your email to sales@tinman3d.com and we will be happy to complete your licence request. If you have any other questions, please send an email to: info@tinman3d.com.

According to LicenceKey, the environment variable for the Tinman 3D SDK is this:

TINMAN_3D_LICENCEKEY = ...

Public / Constructors

LicenceDomain

Creates a new instance of LicenceDomain.

public constructor LicenceDomain (string name, string comment, Domain domain)
params name [not-empty] The machine-readable domain name (see Name).
  comment The human-readable domain comment to put into licence requests.
  domain [not-null] The licence domain worker object.

Public / Methods

GenerateLicenceKeySetup

Generates a source code fragment for C# resp. C++ which reconstructs a licence key string using some pseudo-random arithmetic.

[Pure]
public static method GenerateLicenceKeySetup (bool cpp, string licenceKey, string variableName = "licenceKey")
type string
params cpp Generate C++ source code (true), or C# source code (false)?
  licenceKey [not-empty] The Tinman 3D licence key string.
  variableName [not-empty] Name of the variable which the reconstructed licence key string will be assigned to. Defaults to 'licenceKey'.
returns [not-null] The code fragment.

Remarks:

You can use the source code fragment if you do not want to embed the licence key as a string literal into your binary.

The C# code fragment looks like this:

// Tinman 3D licence key:
// CIk!6Dh6Ui;lSE+Z{{jx7$Y~8,#TSt~o%CK#(e,F#O9.d;fGc+bU35%HVl;[.+s#@h.bo1~{riL.4|UreHfeuac}5ZV~DBocxU}@
{
  sbyte[] licenceKeyData;

  licenceKeyData = new sbyte[N+1];
  licenceKeyData[0] = ?;
  licenceKeyData[1] = (sbyte) (licenceKeyData[0] op ?);
  ...
  licenceKeyData[N] = (sbyte) (licenceKeyData[N-1] op ?);

  licenceKey = global::Tinman.Core.StringUtil.BinaryDecode(licenceKeyData);
}
The C++ code fragment looks like this:
// Tinman 3D licence key:
// CIk!6Dh6Ui;lSE+Z{{jx7$Y~8,#TSt~o%CK#(e,F#O9.d;fGc+bU35%HVl;[.+s#@h.bo1~{riL.4|UreHfeuac}5ZV~DBocxU}@
{
  CodeX::Array<int8> licenceKeyData(N+1);

  licenceKeyData[0] = ?;
  licenceKeyData[1] = static_cast<CodeX::int8> (licenceKeyData[0] op ?);
  ...
  licenceKeyData[N] = static_cast<CodeX::int8> (licenceKeyData[N-1] op ?);

  licenceKey = ::Tinman::Core::StringUtil::BinaryDecode(licenceKeyData);
}
where 'licenceKey' is the variable name that has been specified via the variableName parameter, N+1 is the buffer length and op and ? perform pseudo-random arithmetic operations.

LicenceKey

Specifies a licence key that shall be used to unlock this licence domain.

[ThreadSafe]
public method LicenceKey (string licenceKey)
params licenceKey The licence key (will be normalized if necessary, see LicenceKeyNormalize.

Remarks:

Each licence key is a string of 100 characters, interpreted as a base-85 number using printable ASCII characters as digits (whitespaces are ignored). These characters will never be used in a licence key string:

"&'/<>\]`
This allows licence keys to be put into string literals or XML files. Here is an example key:
CIk!6Dh6Ui;lSE+Z{{jx7$Y~8,#TSt~o%CK#(e,F#O9.d;fGc+bU35%HVl;[.+s#@h.bo1~{riL.4|UreHfeuac}5ZV~DBocxU}@
Please note that the example key above is invalid. You must specify at least one valid one before using the Tinman 3D SDK.

An application can specify any number of licence keys. Upon first call to Unlock request, the licence domain is unlocked; for this at least one valid licence key must have been specified. All invalid licence keys are ignored silently.

A licence key can optionally be specified via a user environment variable named {NAME}_LICENCEKEY, where {NAME} is the value of Name, converted to uppercase. Licence keys specified via LicenceKey have precedence over the environment variable key.

LicenceKeyNormalize

Normalizes the given licence key string.

public static method LicenceKeyNormalize (string licenceKey)
type string
params licenceKey The licence key string.
returns The normalized licence key string, containing exactly 100 base-85 characters, or null.

Remarks:

A licence key is normalized like this:

  1. The following character substitutions are performed on the given licence key string:
    '&' => '#'
    '"' => '('
    This makes sure that a modified licence key string can be put into the /etc/environment file of a Unix/Linux system:
    • Avoid truncation of licence key after special comment character ('#').
    • Avoid breaking of command 'apt upgrade', because of unexpected '(' character.
  2. All invalid characters are discarded (i.e. all non-base-85 characters).
    This will remove all whitespaces resp. line-breaks (e.g. resulting from copy & paste).
  3. If the resulting string length is not 100, the entire string is discarded and set to null.

Request

Formulates a licence request for this licence domain.

public method Request (LicenceMetadata metadata, Path path = null)
type Path
params metadata [not-null] User licence metadata for the licence key.
  path Optional directory for licence request file. If null, the file will be stored in the current users home directory. Defaults to null.
returns [not-null] Path to licence request file.

Remarks:

The licence request is a human-readable JSON value (see From). The licence request file is a text file with UTF-8 encoding (see UTF_8) and leading byte-order marks.

When a licence key is granted for the returned request, it will allow the enclosing environment (see LicenceType) to activate this licence domain.

Exceptions:


Formulates a licence request for this licence domain.

public method Request (LicenceType type, Path path = null)
type Path
params type The licence type to request.
  path Optional directory for licence request file. If null, the file will be stored in the current users home directory. Defaults to null.
returns [not-null] Path to licence request file.

Remarks:

The licence request is a human-readable JSON value (see From). The licence request file is a text file with UTF-8 encoding (see UTF_8) and leading byte-order marks.

When a licence key is granted for the returned request, it will allow the enclosing environment (see LicenceType) to activate this licence domain.

Exceptions:

TryUnlock

Checks if this licence domain has been unlocked.

[ThreadSafe]
public method TryUnlock ()
type bool
returns true if unlocked, false when still locked.

Remarks:

When this licence domain is still unlocked, the method will try to unlock it using the set of specified licence keys (see LicenceKey). On success, the program will continue to execute normally. On failure, an exception will be thrown.

Unlock

Checks if this licence domain has been unlocked.

[ThreadSafe]
public method Unlock ()

Remarks:

When this licence domain is still unlocked, the method will try to unlock it using the set of specified licence keys (see LicenceKey). On success, the program will continue to execute normally. On failure, an exception will be thrown.

Exceptions:

UnlockContent

Unlocks a protected content file.

public static method UnlockContent (Path content, string licenceKey)
type Path
params content [not-null] Path to the protected content file.
  licenceKey [not-null] The licence key to use.
returns The canonical path to the unlocked content file or null if licenceKey cannot be used to unlock content.

Remarks:

The unlocked content will be written to a file having the same path as content, without the file suffix: '.lic'.

Exceptions:

UnlockInt8s

Unlocks a protected byte array.

[ThreadSafe]
public method UnlockInt8s (int32 locked)
type int8[]
params locked The identifier of the locked data item.
returns [not-null] The unlocked byte array.

Exceptions:

UnlockString

Unlocks a protected string value.

[ThreadSafe]
public method UnlockString (int32 locked)
type string
params locked The identifier of the locked data item.
returns [not-null] The unlocked string value.

Exceptions:

Logging

Logger

The logger object of this class.

public static readonly field Logger
type ILogger