LicenceDomain

Description

sealed class Tinman.Core.Licensing.LicenceDomain

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

Public / Constructors

Licence​Domain

public constructor LicenceDomain → (3)

name in : string

[not-empty]
The machine-readable domain name (see Name).

comment in : string

The human-readable domain comment to put into licence requests.

domain in : IDomain

[not-null]
The licence domain worker object.

Creates a new instance of LicenceDomain.

Public / Methods

Generate​Licence​Key​Setup

[Pure]
public static method GenerateLicenceKeySetup → (3)

cpp in : bool

Generate C++ source code (true), or C# source code (false)?

licenceKey in : string

[not-empty]
The Tinman 3D licence key string.

variableName opt : string = "licenceKey"

[not-empty]
Name of the variable which the reconstructed licence key string will be assigned to.

returns → string

The code fragment.

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

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 opt parameter, N+1 is the buffer length and op and ? perform pseudo-random arithmetic operations.

Licence​Key

[ThreadSafe]
public method LicenceKey → (1)

licenceKey in : string

The licence key (will be normalized if necessary, see LicenceKeyNormalize).

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

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, see LicenceKeyNormalize for additional information. 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.

Licence​Key​Escape

[Constant]
public static method LicenceKeyEscape → (1)

useDoubleQuotes in : bool

Use the double-quote escaping rule (true) or the single-quote escaping rule ( false)?

returns → StringEscape

The StringEscape object.

Returns a StringEscape object that can be used to create modified licence keys, as described by see LicenceKeyNormalize.

Licence​Key​Normalize

public static method LicenceKeyNormalize → (1)

licenceKey in : string

The licence key string.

returns → string

The normalized licence key string, containing exactly 100 base-85 characters, or null.

Normalizes the given licence key string.

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 or ~/.profile 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.

    • Avoid wrong interpretation of …​$abc…​ as a variable.

  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.

See also

LicenceDomain.LicenceKeyEscape

Request

2 overloads

public method Request1 → (2)

metadata in : LicenceMetadata

[not-null]
User licence metadata for the licence key.

path opt : Path = null

Optional directory for licence request file. If null, the file will be stored in the current users home directory.

returns → Path

Path to licence request file.

Formulates a licence request for this licence domain.

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

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

IOException

If an I/O error has occurred.

public method Request2 → (2)

flags in : LicenceFlags

The licence type to request.

path opt : Path = null

Optional directory for licence request file. If null, the file will be stored in the current users home directory.

returns → Path

Path to licence request file.

Formulates a licence request for this licence domain.

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

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

IOException

If an I/O error has occurred.

Try​Unlock

[ThreadSafe]
public method TryUnlock → ()

returns → bool

true if unlocked, false when still locked.

Checks if this licence domain has been unlocked.

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

[ThreadSafe]
public method Unlock → ()

Checks if this licence domain has been unlocked.

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.

LicenceException

If this licence domain is still locked.

Unlock​Content

public static method UnlockContent → (2)

content in : Path

[not-null]
Path to the protected content file.

licenceKey in : string

[not-null]
The licence key to use.

returns → Path

The canonical path to the unlocked content file or null if licenceKey in cannot be used to unlock content in.

Unlocks a protected content file.

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

IOException

If an I/O error has occurred.

Unlock​Int32s

[ThreadSafe]
public method UnlockInt32s → (1)

locked in : int32

The identifier of the locked data item.

returns → int32 [ ]

The unlocked integer array.

Unlocks a protected integer array.

LicenceException

If this licence domain is still locked.

Unlock​Int8s

[ThreadSafe]
public method UnlockInt8s → (1)

locked in : int32

The identifier of the locked data item.

returns → int8 [ ]

The unlocked byte array.

Unlocks a protected byte array.

LicenceException

If this licence domain is still locked.

Unlock​String

[ThreadSafe]
public method UnlockString → (1)

locked in : int32

The identifier of the locked data item.

returns → string

The unlocked string value.

Unlocks a protected string value.

LicenceException

If this licence domain is still locked.

Public / Attributes

Allow​Unlock​By​Environment

public attribute AllowUnlockByEnvironment → (get,set)

value : bool

true to allow environment variable licence key, false to disable it.

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

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

Defaults to true.

See also

LicenceDomain.IsUnlockedByEnvironment

Is​Unlocked

[ThreadSafe]
public attribute IsUnlocked → (get)

value : bool

true if this licence domain is unlocked, false if not.

Has this licence domain been unlocked?

Is​Unlocked​By​Application

public attribute IsUnlockedByApplication → (get)

value : bool

true if this licence domain has been activated from one of the licence keys that have been specified via LicenceKey, false otherwise.

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

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

Is​Unlocked​By​Environment

public attribute IsUnlockedByEnvironment → (get)

value : bool

true if this licence domain has been activated from the licence key that has been specified in the environment variable, false otherwise.

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

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

Name

public attribute Name → (get)

value : string

[not-empty]
Licence domain name.

Machine-readable name of this licence domain.

Tinman

public static attribute Tinman → (get)

value : LicenceDomain

[not-null]
The licence domain.

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

To obtain a new licence manually, you can use the Request2 and Request1 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 = ...

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.