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 → (4)

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.

module in : TinmanModule

[not-null]
The owning module.

Creates a new instance of LicenceDomain.

Public / Methods

Allow​Unlock​By

public method AllowUnlockBy → (3)

application opt : bool = true

The value for AllowUnlockByApplication.

environment opt : bool = true

The value for AllowUnlockByEnvironment.

userKeyFile opt : bool = false

The value for AllowUnlockByUserKeyFile.

Helper for setting the AllowUnlockBy* properties with a single call.

Check

public method Check → ()

returns → bool

true if this domain has already been unlocked,
false if it is still unlocked.

This is a convenience method that generates a licence request and outputs some helpful log messages when this licence domain is still locked.

The following log messages are output to Logger when still locked:

If the licence domain is still locked, a licence request is generated in the user home directory with Request1.

See also

LicenceDomain.IsUnlocked

Generate​Licence​Key​Setup

[Pure]
public static method GenerateLicenceKeySetup → (6)

cpp in : bool

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

licenceKey in : string

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

linePrefix opt : string = ""

[not-null]
The line prefix to use.

comments opt : int32 = 2

[0..2]
Controls which line comments are output:
0 : no line comments are output,
1 : only the code generator demarcation line comments are output,
2 : all line comments are output.

lineEnding opt : LineEnding = LineEnding.CRLF

The line ending to use.

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:

// CODEX-GENERATOR-BEGIN(Tinman.Core.Licensing.LicenceDomain)
// 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);
}
// CODEX-GENERATOR-END(Tinman.Core.Licensing.LicenceDomain)

The C++ code fragment looks like this:

// CODEX-GENERATOR-BEGIN(Tinman.Core.Licensing.LicenceDomain)
// 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);
}
// CODEX-GENERATOR-END(Tinman.Core.Licensing.LicenceDomain)

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 method will output LogMessage_Licence_Success and the program will continue to execute normally. On failure, LogMessage_Licence_Invalid will be output for each licence key that failed to unlock this domain and 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​Application

public attribute AllowUnlockByApplication → (get,set)

value : bool

true to allow application licence keys, false to disallow.

Allow this licence domain to be unlocked via licence keys that are specified with LicenceKey?

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

Defaults to true.

See also

LicenceDomain.IsUnlockedByApplication

Allow​Unlock​By​Environment

public attribute AllowUnlockByEnvironment → (get,set)

value : bool

true to allow the environment variable licence key, false to disallow.

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

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

Defaults to true.

See also

LicenceDomain.NameEnvironment
LicenceDomain.IsUnlockedByEnvironment

Allow​Unlock​By​User​Key​File

public attribute AllowUnlockByUserKeyFile → (get,set)

value : bool

true to allow the user key file licence key, false to disallow.

Allow this licence domain to be unlocked via the licence key found in the user key file?

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

Defaults to false.

See also

LicenceDomain.NameUserKeyFile
LicenceDomain.IsUnlockedByUserKeyFile

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?

The TryUnlock method is not called when this property is get.

Is​Unlocked​By​Application

public attribute IsUnlockedByApplication → (get)

value : bool

true if this licence domain has been activated from one of the licence keys 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.

See also

LicenceDomain.AllowUnlockByApplication

Is​Unlocked​By​Environment

public attribute IsUnlockedByEnvironment → (get)

value : bool

true if this licence domain has been activated from the licence key 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 NameEnvironment)?

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

See also

LicenceDomain.AllowUnlockByEnvironment

Is​Unlocked​By​User​Key​File

public attribute IsUnlockedByUserKeyFile → (get)

value : bool

true if this licence domain has been activated from the licence key in the user key file, false otherwise.

Is this licence domain being activated from the licence key that has been specified in the user key file (see NameUserKeyFile)?

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

See also

LicenceDomain.AllowUnlockByUserKeyFile

Name

public attribute Name → (get)

value : string

[not-empty]
Licence domain name.

Machine-readable name of this licence domain.

Name​Environment

public attribute NameEnvironment → (get)

value : string

[not-empty]
The name of the environment variable.

Returns the name of the environment variable that can be used to specify a licence key for this domain.

See also

LicenceDomain.AllowUnlockByEnvironment

Name​User​Key​File

public attribute NameUserKeyFile → (get)

value : Path

[not-null]
The full path to the user key file or Path.Unknown if not available.

Returns the full path of the user key file that can be used to specify a licence key for this domain.

See also

LicenceDomain.AllowUnlockByUserKeyFile

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.

See also

LicenceDomain.LogMessage_Check_Environment
LicenceDomain.LogMessage_Check_UserKeyFile
LicenceDomain.LogMessage_Licence_Failure
LicenceDomain.LogMessage_Licence_Invalid
LicenceDomain.LogMessage_Licence_Success
LicenceDomain.LogMessage_Metadata
LicenceDomain.LogMessage_Metadata_Machine
LicenceDomain.LogMessage_Request

Log​Message_​Check_​Environment

public static readonly attribute LogMessage_Check_Environment → (ILogMessage)

Advises the user to check the licence key in environment variable.

Label parameters:

#0 :
Name of the environment variable, see NameEnvironment.

See also

LogVerbosity.Common

Log​Message_​Check_​User​Key​File

public static readonly attribute LogMessage_Check_UserKeyFile → (ILogMessage)

Advises the user to check the licence key in the user key file.

Label parameters:

#0 :
Path to the user key file, see NameUserKeyFile.

See also

LogVerbosity.Common

Log​Message_​Licence_​Failure

public static readonly attribute LogMessage_Licence_Failure → (ILogMessage)

The licence domain cannot be unlocked because there is no valid licence key.

Label parameters:

#0 :
Name of the licence domain, Name.

See also

LogVerbosity.Warning

Log​Message_​Licence_​Invalid

public static readonly attribute LogMessage_Licence_Invalid → (ILogMessage)

A well-formed licence key (according to LicenceKeyNormalize) has been specified which did not activate the licence domain.

Label parameters:

#0 :
The first 12 characters of the invalid licence key.

See also

LogVerbosity.Warning

Log​Message_​Licence_​Success

public static readonly attribute LogMessage_Licence_Success → (ILogMessage)

The licence domain has been unlocked from a licence key.

Label parameters:

#0 :
The source of the licence key (application, environment, user key file).

See also

LogVerbosity.Info

Log​Message_​Metadata

public static readonly attribute LogMessage_Metadata → (ILogMessage)

Outputs the current licence metadata.

Label parameters:

#0 : LicenceMetadata.LegalCompany
#1 : LicenceMetadata.LegalCopyright
#2 : LicenceMetadata.LegalProduct
#3 : LicenceMetadata.LegalTrademark
#4 : LicenceMetadata.MachineCode
#5 : LicenceMetadata.MachineDomain
#6 : LicenceMetadata.MachineUser
#7 : LicenceMetadata.ProgramFile
#8 : LicenceMetadata.ProgramHash
#9 : LicenceMetadata.ProgramTitle
#10 : LicenceMetadata.ProgramVersion

See also

LogVerbosity.Common

Log​Message_​Metadata_​Machine

public static readonly attribute LogMessage_Metadata_Machine → (ILogMessage)

Outputs the licence metadata.

Label parameters:

#4 : LicenceMetadata.MachineCode
#5 : LicenceMetadata.MachineDomain
#6 : LicenceMetadata.MachineUser

See also

LogVerbosity.Common

Log​Message_​Request

public static readonly attribute LogMessage_Request → (ILogMessage)

Outputs the file path to the generated licence request file.

Label parameters:

#0 :
Path to the licence request file, as returned by Request1.

See also

LogVerbosity.Common