Skip to content

Latest commit

 

History

History
961 lines (682 loc) · 39.9 KB

docs.md

File metadata and controls

961 lines (682 loc) · 39.9 KB
Raw

crdtes

Creative Developer Tools (CRDT) is a growing suite of tools aimed at script developers and plug-in developers for the Adobe Creative Cloud eco-system.

Currently, it is at an alpha stage: the feature set is not frozen, and new features are added regularly.

There are two different versions of CRDT: one for UXP/UXPScript and another for ExtendScript.

The software is functional and useful, but without a doubt, there will be bugs and dragons…

Features include:

  • Provides a unique machine GUID for each end-user computer
  • Provides a unique account GUID for each end user
  • Add licensing and activation features to your script
  • Protect sensitive source code and make it hard to reverse engineer
  • AES-256 encryption/decryption functions
  • Base64 encode and decode functions

More to come! You can contact us on dev@rorohiko.com with feature request

For downloading and installation info, visit

https://www.rorohiko.com/crdt

crdtes~TQL_SCOPE_NAME_DEFAULT : string

The Tightener daemon provides persistent named scopes (similar to persistent ExtendScript engines).

When executing multiple TQL scripts in succession a named scope will retain any globals that were defined by a previous script.

Kind: inner constant of crdtes

crdtes~LOG_LEVEL_OFF : number

Setting log level to LOG_LEVEL_OFF causes all log output to be suppressed.

Kind: inner constant of crdtes

crdtes~LOG_LEVEL_ERROR : number

Setting log level to LOG_LEVEL_ERROR causes all log output to be suppressed, except for errors.

Kind: inner constant of crdtes

crdtes~LOG_LEVEL_WARNING : number

Setting log level to LOG_LEVEL_WARNING causes all log output to be suppressed, except for errors and warnings.

Kind: inner constant of crdtes

crdtes~LOG_LEVEL_NOTE : number

Setting log level to LOG_LEVEL_NOTE causes all log output to be suppressed, except for errors, warnings and notes.

Kind: inner constant of crdtes

crdtes~LOG_LEVEL_TRACE : number

Setting log level to LOG_LEVEL_TRACE causes all log output to be output.

Kind: inner constant of crdtes

crdtes~DESKTOP_DIR : string

Pass DESKTOP_DIR into getDir() to get the path of the user's Desktop folder.

Kind: inner constant of crdtes

crdtes~DOCUMENTS_DIR : string

Pass DOCUMENTS_DIR into getDir() to get the path of the user's Documents folder.

Kind: inner constant of crdtes

crdtes~HOME_DIR : string

Pass HOME_DIR into getDir() to get the path of the user's home folder.

Kind: inner constant of crdtes

crdtes~LOG_DIR : string

Pass LOG_DIR into getDir() to get the path of the Tightener logging folder.

Kind: inner constant of crdtes

crdtes~SYSTEMDATA_DIR : string

Pass SYSTEMDATA_DIR into getDir() to get the path of the system data folder (%PROGRAMDATA% or /Library/Application Support).

Kind: inner constant of crdtes

crdtes~TMP_DIR : string

Pass TMP_DIR into getDir() to get the path of the temporary folder.

Kind: inner constant of crdtes

crdtes~USERDATA_DIR : string

Pass USERDATA_DIR into getDir() to get the path to the user data folder (%APPDATA% or ~/Library/Application Support).

Kind: inner constant of crdtes

crdtes~base64decode(base64Str) ⇒ string

Decode a string that was encoded using base64.

Kind: inner method of crdtes
Returns: string - decoded string

Param Type Description
base64Str string base64 encoded string

crdtes~base64encode(str_or_ByteArr) ⇒ string

Encode a string or an array of bytes using Base 64 encoding.

Kind: inner method of crdtes
Returns: string - encoded string

Param Type Description
str_or_ByteArr string either a string or an array containing bytes (0-255).

crdtes~binaryToStr(in_byteArray) ⇒ string

Convert an array of bytes into string format. This string is UTF-16 internally, and we map one byte to one UTF-16 character. The resulting string might contain character values (charCodeAt()) that would be invalid in UTF8.

Kind: inner method of crdtes
Returns: string - a string

Param Type Description
in_byteArray array an array containing UTF-16 values in the range 0-255

crdtes~binaryUTF8ToStr(in_byteArray) ⇒ string

Decode an array of bytes that contains a UTF-8 encoded string.

Kind: inner method of crdtes
Returns: string - a string, or undefined if some invalid UTF-8 is encountered

Param Type Description
in_byteArray array an array containing bytes (0-255) for a string that was encoded using UTF-8 encoding.

crdtes~configLogger(logInfo) ⇒ boolean

Configure the logger

Kind: inner method of crdtes
Returns: boolean - success/failure

Param Type Description
logInfo object object with logger setup info logLevel: 0-4 logEntryExit: boolean logToESTKConsole: boolean logToCRDT: boolean logToFilePath: undefined or a file path for logging

crdtes~decrypt(str_or_ByteArr, aesKey) ⇒ array

Reverse the operation of the encrypt() function.

Only available to paid developer accounts

Kind: inner method of crdtes
Returns: array - an array of bytes

Param Type Description
str_or_ByteArr string a string or an array of bytes
aesKey string a string or an array of bytes

crdtes~deQuote(quotedString) ⇒ array

Reverse the operation of dQ() or sQ().

Kind: inner method of crdtes
Returns: array - a byte array. If the quoted string contains any `\uHHHH`` codes, these are first re-encoded using UTF-8 before storing them into the byte array.

Param Type Description
quotedString string a quoted string

crdtes~dirCreate(filePath) ⇒ array

Create a directory.

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: array - list if items in directory

Param Type
filePath string

crdtes~dirDelete(filePath, recurse) ⇒ boolean

Delete a directory.

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: boolean - success or failure

Param Type
filePath string
recurse boolean

crdtes~dirExists(dirPath) ⇒ boolean

Verify whether a directory exists. Will return false if the path points to a file (instead of a directory).

Also see fileExists().

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: boolean - true or false

Param Type Description
dirPath string a path to a directory

crdtes~dirScan(filePath) ⇒ array

Scan a directory.

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: array - list if items in directory

Param Type
filePath string

crdtes~dQ(str_or_ByteArr) ⇒ string

Wrap a string or a byte array into double quotes, encoding any binary data as a string. Knows how to handle Unicode characters or binary zeroes.

When the input is a string, high Unicode characters are encoded as \uHHHH.

When the inoput is a byte array, all bytes are encoded as characters or as \xHH escape sequences.

Kind: inner method of crdtes
Returns: string - a string enclosed in double quotes. This string is pure 7-bit ASCII and can be inserted into generated script code Example: var script = "a=b(" + dQ(somedata) + ");";

Param Type Description
str_or_ByteArr string a Unicode string or an array of bytes

crdtes~encrypt(str_or_ByteArr, aesKey) ⇒ string

Encrypt a string or array of bytes using a key. A random salt is added into the mix, so even when passing in the same parameter values, the result will be different every time.

Only available to paid developer accounts

Kind: inner method of crdtes
Returns: string - a base-64 encoded encrypted string.

Param Type Description
str_or_ByteArr string a string or an array of bytes
aesKey string a string or an array of bytes

crdtes~evalScript(scriptName, parentScriptFile) ⇒ any

Evaluate a script file. If the unencrypted script file is not available (.jsx or .js), use crdtesDLL to try and run an .ejsx or .ejs file.

Kind: inner method of crdtes
Returns: any - the returned value

Param Type Description
scriptName string the name of the script to run, without file name extension or parent directory
parentScriptFile string the name of the script from which we're calling this (pass in $.fileName). If this is missing, evaluate the path relative to the parent of CreativeDeveloperTools_ES

crdtes~evalTQL(tqlScript, tqlScopeName) ⇒ any

Send a TQL script to the DLL

Kind: inner method of crdtes
Returns: any - the returned value

Param Type Description
tqlScript string a script to run
tqlScopeName string a scope name to use. Such scope can be used to pass data between different processes

crdtes~fileClose(fileHandle) ⇒ boolean

Close a currently open file

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: boolean - success or failure

Param Type Description
fileHandle number a file handle as returned by fileOpen().

crdtes~fileDelete(filePath) ⇒ boolean

Delete a file

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: boolean - success or failure

Param Type
filePath string

crdtes~fileExists(filePath) ⇒ boolean

Check if a file exists. Will return false if the file path points to a directory.

Also see dirExists().

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: boolean - existence of file

Param Type
filePath string

crdtes~fileOpen(fileName, mode) ⇒ number

Open a binary file and return a handle

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: number - file handle

Param Type Description
fileName string a native full file path to the file
mode string one of 'a', 'r', 'w' (append, read, write)

crdtes~fileRead(fileHandle, isBinary) ⇒ any

Read a file into memory

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: any - either a byte array or a string

Param Type Description
fileHandle number a file handle as returned by fileOpen().
isBinary boolean whether the file is considered a binary file (as opposed to a UTF-8 text file)

crdtes~fileWrite(fileHandle, str_or_ByteArr) ⇒ boolean

Binary write to a file. Strings are written as UTF-8

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: boolean - success or failure

Param Type Description
fileHandle number a file handle as returned by fileOpen().
str_or_ByteArr string data to write to the file

crdtes~getCapability(issuer, capabilityCode, encryptionKey) ⇒ string

Determine whether, or which, features of some software or module are currently activated or not

Kind: inner method of crdtes
Returns: string - either "NOT_ACTIVATED" or a JSON structure with capability data (customer GUID, decrypted developer-provided data from the activation file).

Param Type Description
issuer string a GUID identifier for the developer account as seen in the PluginInstaller
capabilityCode string a code for the software features to be activated (as determined by the developer who owns the account). capabilityCode is not the same as orderProductCode - there can be multiple orderProductCode associated with a single capabilityCode (e.g. capabilityCode 'XYZ', orderProductCode 'XYZ_1YEAR', 'XYZ_2YEAR'...).
encryptionKey string the secret encryption key (created by the developer) needed to decode the capability data. As a developer you want to make sure this encryptionKey is obfuscated and only contained within encrypted script code.

crdtes~getDir(dirTag) ⇒ string

Get the path of a system directory

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: string - file path of dir or undefined. Directory paths include a trailing slash or backslash

Param Type Description
dirTag string a tag representing the dir: DESKTOP_DIR DOCUMENTS_DIR HOME_DIR LOG_DIR SYSTEMDATA_DIR TMP_DIR USERDATA_DIR

crdtes~getEnvironment(envVarName) ⇒ string

Access the environment

Not restricted by the UXP security sandbox. Not needed for pure ExtendScript - provided to offer some compatibility with the UXP version of CRDT

Kind: inner method of crdtes
Returns: string - environment variable value

Param Type Description
envVarName string name of environment variable

crdtes~getBooleanFromINI(in_value) ⇒ boolean

Interpret a value extracted from some INI data as a boolean. Things like y, n, yes, no, true, false, t, f, 0, 1

Kind: inner method of crdtes
Returns: boolean - value

Param Type Description
in_value string ini value

crdtes~getFloatWithUnitFromINI(in_value, in_defaultUnit) ⇒ boolean

Interpret a string extracted from some INI data as a floating point value, followed by an optional unit If there is no unit, then no conversion is performed.

Kind: inner method of crdtes
Returns: boolean - value

Param Type Description
in_value string ini value
in_defaultUnit string default to use if no match is found

crdtes~getUnitFromINI(in_value, in_defaultUnit) ⇒ boolean

Interpret a string extracted from some INI data as a unit name

Kind: inner method of crdtes
Returns: boolean - value

Param Type Description
in_value string ini value
in_defaultUnit string default to use if no match is found

crdtes~getPluginInstallerPath() ⇒ string

Get file path to PluginInstaller if it is installed

Kind: inner method of crdtes
Returns: string - file path

crdtes~getPersistData(issuer, attribute, password) ⇒ string

Fetch some persistent data

Only available to paid developer accounts

Kind: inner method of crdtes
Returns: string - whatever persistent data is stored for the given attribute

Param Type Description
issuer string a GUID identifier for the developer account as seen in the PluginInstaller
attribute string an attribute name for the data
password string the password (created by the developer) needed to decode the persistent data

crdtes~intPow(i, intPower) ⇒ number

Calculate an integer power of an int value. Avoids using floating point, so should not have any floating-point round-off errors. Math.pow() will probably give the exact same result, but I am doubtful that some implementations might internally use log and exp to handle Math.pow()

Kind: inner method of crdtes
Returns: number - i ^ intPower

Param Type Description
i number Integer base
intPower number integer power

crdtes~getCreativeDeveloperToolsLevel() ⇒ number

Determine the license level for CRDT: 0 = not, 1 = basic, 2 = full

Some functions, marked with "Only available to paid developer accounts" will only work with level 2. Licensing function only work with level 1

Kind: inner method of crdtes
Returns: number - 0, 1 or 2

crdtes~leftPad(s, padChar, len) ⇒ string

Extend or shorten a string to an exact length, adding padChar as needed

Kind: inner method of crdtes
Returns: string - padded or shortened string

Param Type Description
s string string to be extended or shortened
padChar string string to append repeatedly if length needs to extended
len number desired result length

crdtes~logEntry(reportingFunctionArguments)

Make a log entry of the call of a function. Pass in the arguments keyword as a parameter.

Kind: inner method of crdtes

Param Type Description
reportingFunctionArguments array pass in the current arguments to the function. This is used to determine the function's name for the log

crdtes~logError(reportingFunctionArguments, message)

Make a log entry of an error message. Pass in the arguments keyword as the first parameter If the error level is below LOG_LEVEL_ERROR nothing happens

Kind: inner method of crdtes

Param Type Description
reportingFunctionArguments array pass in the current arguments to the function. This is used to determine the function's name for the log
message string error message

crdtes~logExit(reportingFunctionArguments)

Make a log entry of the exit of a function. Pass in the arguments keyword as a parameter.

Kind: inner method of crdtes

Param Type Description
reportingFunctionArguments array pass in the current arguments to the function. This is used to determine the function's name for the log

crdtes~functionNameFromArguments(functionArguments) ⇒ string

Extract the function name from its arguments

Kind: inner method of crdtes
Returns: string - function name

Param Type Description
functionArguments object pass in the current arguments to the function. This is used to determine the function's name

crdtes~logMessage(reportingFunctionArguments, logLevel, message)

Output a log message. Pass in the arguments keyword as the first parameter.

Kind: inner method of crdtes

Param Type Description
reportingFunctionArguments array pass in the current arguments to the function. This is used to determine the function's name for the log
logLevel number log level
message string the note to output

crdtes~logNote(reportingFunctionArguments, message)

Make a log entry of a note. Pass in the arguments keyword as the first parameter. If the error level is below LOG_LEVEL_NOTE nothing happens

Kind: inner method of crdtes

Param Type Description
reportingFunctionArguments array pass in the current arguments to the function. This is used to determine the function's name for the log
message string the note to output

crdtes~logTrace(reportingFunctionArguments, message)

Emit a trace messsage into the log. Pass in the arguments keyword as the first parameter. If the error level is below LOG_LEVEL_TRACE nothing happens

Kind: inner method of crdtes

Param Type Description
reportingFunctionArguments array pass in the current arguments to the function. This is used to determine the function's name for the log
message string the trace message to output

crdtes~logWarning(arguments, message)

Emit a warning messsage into the log. Pass in the arguments keyword as the first parameter. If the error level is below LOG_LEVEL_WARNING nothing happens

Kind: inner method of crdtes

Param Type Description
arguments array pass in the current arguments to the function. This is used to determine the function's name for the log
message string the warning message to output

crdtes~machineGUID() ⇒ string

The unique GUID of this computer

Only available to paid developer accounts

Kind: inner method of crdtes
Returns: string - a GUID string

crdtes~pluginInstaller() ⇒ boolean

Attempt to launch the PluginInstaller if it is installed

Kind: inner method of crdtes
Returns: boolean - success or failure

crdtes~popLogLevel() ⇒ number

Restore the log level to what it was when pushLogLevel was called

Kind: inner method of crdtes
Returns: number - log level that was popped off the stack

crdtes~pushLogLevel(newLogLevel) ⇒ number

Save the previous log level and set a new log level

Kind: inner method of crdtes
Returns: number - previous log level

Param Type Description
newLogLevel number new log level to set

crdtes~readINI(in_text) ⇒ object

Read a bunch of text and try to extract structured information in .INI format

This function is lenient and is able to extract slightly mangled INI data from the text frame content of an InDesign text frame.

This function knows how to handle curly quotes should they be present.

The following flexibilities have been built-in:

  • Attribute names are case-insensitive and anything not a-z 0-9 is ignored. Entries like this or that = ... or thisOrThat = ... or this'orThat = ... are all equivalent. Only letters and digits are retained, and converted to lowercase.

  • Attribute values can be quoted with either single, double, curly quotes. This often occurs because InDesign can be configured to convert normal quotes into curly quotes automatically. Attribute values without quotes are trimmed (e.g. bla = x is the same as bla=x) Spaces are retained in quoted attribute values.

  • Any text will be ignore if not properly formatted as either a section name or an attribute-value pair with an equal sign

  • Hard and soft returns are equivalent

The return value is an object with the section names at the top level, and attribute names below that. The following .INI

[My data]
this is = " abc "
that =      abc

returns

{
  "mydata": {
     "thisis": " abc ",
     "that": "abc"
  }
}

Kind: inner method of crdtes
Returns: object - either the ini data or undefined.

Param Type Description
in_text string raw text, which might or might not contain some INI-formatted data mixed with normal text

crdtes~rightPad(s, padChar, len) ⇒ string

Extend or shorten a string to an exact length, adding padChar as needed

Kind: inner method of crdtes
Returns: string - padded or shortened string

Param Type Description
s string string to be extended or shortened
padChar string string to append repeatedly if length needs to extended
len number desired result length

crdtes~setIssuer(issuerGUID, issuerEmail)

Send in activation data to determine whether some software is currently activated or not.

Needs to be followed by a sublicense() call

Kind: inner method of crdtes
Returnss: boolean - success or failure

Param Type Description
issuerGUID string a GUID identifier for the developer account as seen in the PluginInstaller
issuerEmail string the email for the developer account as seen in the PluginInstaller

crdtes~setPersistData(issuer, attribute, password, data) ⇒ boolean

Store some persistent data (e.g. a time stamp to determine a demo version lapsing)

Only available to paid developer accounts

Kind: inner method of crdtes
Returns: boolean - success or failure

Param Type Description
issuer string a GUID identifier for the developer account as seen in the PluginInstaller
attribute string an attribute name for the data
password string the password (created by the developer) needed to decode the persistent data
data string any data to persist

crdtes~sQ(str_or_ByteArr) ⇒ string

Wrap a string or a byte array into single quotes, encoding any binary data as a string. Knows how to handle Unicode characters or binary zeroes.

When the input is a string, high Unicode characters are encoded as \uHHHH

When the input is a byte array, all bytes are encoded as \xHH escape sequences.

Kind: inner method of crdtes
Returns: string - a string enclosed in double quotes. This string is pure 7-bit ASCII and can be used into generated script code Example: var script = "a=b(" + sQ(somedata) + ");";

Param Type Description
str_or_ByteArr string a Unicode string or an array of bytes

crdtes~strToUTF8(in_s) ⇒ array

Encode a string into an byte array using UTF-8

Kind: inner method of crdtes
Returns: array - a byte array

Param Type Description
in_s string a string

crdtes~strToBinary(in_s) ⇒ array

Encode a string into an byte array using the 8 lowest bits of each UTF-16 character

Kind: inner method of crdtes
Returns: array - a byte array

Param Type Description
in_s string a string

crdtes~sublicense(key, activation) ⇒ boolean

Send in sublicense info generated in the PluginInstaller so we can determine whether some software is currently activated or not.

Needs to be preceded by a setIssuer() call.

Kind: inner method of crdtes
Returns: boolean - success or failure

Param Type Description
key string key needed to decode activation data
activation string encrypted activation data

crdtes~toHex(i, numDigits) ⇒ string

Convert an integer into a hex representation with a fixed number of digits. Negative numbers are converted using 2-s complement (so -15 results in 0x01)

Kind: inner method of crdtes
Returns: string - hex-encoded integer

Param Type Description
i number integer to convert to hex
numDigits number How many digits. Defaults to 4 if omitted.

crdtes~unitToInchFactor(in_unit) ⇒ number

Conversion factor from a length unit into inches

Kind: inner method of crdtes
Returns: number - conversion factor or 1.0 if unknown/not applicable

Param Type Description
in_unit string unit name (crdtes.UNIT_NAME...)