N2 Library
N2 Library
Overview
The N2 Library is a precompiled object library that contains helper functions to increase runtime speed, as required. These functions are accessible directly from Lua.
Most functions in this library are used by other NCC API features and are not intended for direct access, so will only be lightly covered here.
This library is automatically included by the NCC API and can be accessed through it directly, e.g.:
x = ncc.logic.profile.ulong_to_bin (12345) -- x = 0x30 0x39
Functions
- ncc.logic.profile.bin_to_uint
- ncc.logic.profile.ulong_to_bin
- ncc.logic.profile.ushort_to_bin
- ncc.logic.profile.uchar_to_bin
- ncc.logic.profile.decode
- ncc.logic.profile.encode
- ncc.logic.ptree.decode
- ncc.logic.ptree.encode
▲ ncc.logic.profile.bin_to_uint (bytes)
Parameters
bytes
Binary string (mandatory).
Returns
An unsigned long (bytes length of 4) or short (bytes length of 2) number.
Errors
If bytes is not 2 or 4 bytes in length, the following error will be raised:
Need 2 or 4 bytes for uint, have <bytes length>.
Usage
This function converts a given 4-byte binary string to an unsigned long or a given 2-byte binary string to an unsigned short.
x = ncc.logic.profile.bin_to_uint ("09") -- x = 12345
▲ ncc.logic.profile.ulong_to_bin (num)
Parameters
num
Unsigned long number (mandatory).
Returns
A binary string of length 4.
Errors
None.
Usage
This function converts a given unsigned long (converted automatically by Lua) to a 4-byte binary string.
x = ncc.logic.profile.ulong_to_bin (1234567890) -- x = 0x49 0x96 0x02 0xD2
▲ ncc.logic.profile.ushort_to_bin (num)
Parameters
num
Unsigned short number (mandatory).
Returns
A binary string of length 2.
Errors
None.
Usage
This function converts a given unsigned short (converted automatically by Lua) to a 2-byte binary string.
x = ncc.logic.profile.ushort_to_bin (12345) -- x = 0x30 0x39
▲ ncc.logic.profile.uchar_to_bin (num)
Parameters
num
Unsigned short short number (mandatory).
Returns
A binary string of length 1.
Errors
None.
Usage
This function converts a given unsigned short short (converted automatically by Lua) to a 1-byte binary string.
x = ncc.logic.profile.uchar_to_bin (123) -- x = 0x7B
If the bytes provided is not a string: If the length of bytes is not a multiple of 4: If the length of bytes is less than 4 (the minimum for a profile num_entries field): If the length of bytes is not long enough for the encoded num_entries field): If an encoded data offset does not point to a valid location in bytes: If the end of an encoded data offset points past the end of bytes: This function is not used in the N2 Logic Node.
▲ ncc.logic.profile.decode (bytes)
Parameters
bytes
Binary string (mandatory).
Returns
A Lua table with tags => binary strings, e.g.:
{
["100"] = "0F0F"
}
Errors
If more than one parameter is provided:
Too many parameters, at most 1 is allowed.
Bytes must be string not <bytes type>.
Bytes len of <bytes length> is not a multiple of four bytes.
Bytes insufficient length for num_entries.
Bytes insufficient length for <num_entries> entries.
Data <data offset> offset must be longword aligned.
Data offset + 4 = <data offset> falls beyond end of bytes.
Usage
Decode the raw bytes of a provided profile block (as stored in the database) into a Lua table. All tags are decoded into binary strings and no attempt is made to identify any contained content.
If the profile provided is not a table: If a key in profile is not a number: If a value in profile is not a string: If a tag number is negative in profile: If a tag number is higher than the supported maximum: If a tag number cannot be cast to an integer: If a value length is greater than the supported maximum: If the total length of the encoded profile is greater than the supported maximum: Additionally, some errors are - in theory - impossible: All tags must be numbers, and all values must be strings (i.e. binary data). No content encoding is performed. This function is not used in the N2 Logic Node.
▲ ncc.logic.profile.encode (profile)
Parameters
profile
Table of tags => binary strings values, as returned by ncc.logic.profile.decode (mandatory).
Returns
A binary string of raw profile bytes.
Errors
If more than one parameter is provided:
Too many parameters, at most 1 is allowed.
Profile must be table not <profile type>.
Profile keys must be number not <key type>
Profile values must be string not <value type>
Profile tag <tag number> is negative, not supported.
Profile tag <tag number> is > <unsigned long maximum>, not supported.
Profile tag <tag number> is not integer, not supported.
Profile value length <value length> bytes is > <unsigned long maximum> byte limit.
Profile total length <profile length> bytes is > <unsigned long maximum> byte limit.
Profile number of tags mismatch on second pass, impossible!
Profile entry for tag %d is %s not string on third pass, impossible!
Usage
Encode a provided profile in a Lua table into the raw bytes of a profile block (as stored in the database).
If the prefix path goes beyond what NCC supports: If the offset of a node does not provide enough room for the node: If the characters at the node will not fit in the available bytes: If the sub-nodes at the node will not fit in the available bytes: If the maximum path length would be exceeded while processing nodes: If the offset provided indicates a circular definition: These values will indicate the same output as from the acsProfile tool. Prefix trees within NCC can have values at branches or leaves, depending on their type. This function is called by the ncc.profile functions for reading and writing prefix trees.
▲ ncc.logic.ptree.decode (bytes)
Parameters
bytes
Binary string (mandatory).
Returns
A Lua table with prefix => value strings, e.g.:
{
["1234"] = "0",
["4567"] = "0"
}
Errors
If the bytes provided is not a string:
Bytes must be string not <bytes type>.
Max path length <maximum path length (38)> reached in prefix tree,
cannot recurse further.
Insufficient bytes to process uncompressed node. Have <available bytes>, need 4.
Insufficient bytes to process compressed node. Have <available bytes>, need 8.
Insufficient bytes to process compressed node with <number of path chars>
path chars. Have <available bytes>, need <required bytes>.
Insufficient bytes to process uncompressed node with <number of sub-nodes> sub-nodes.
Have <available bytes>, need <required bytes>.
Max path length <maximum path length (38)> exceeded in prefix tree
trying to add <number of path chars> to <current path length>.
Sub-Node offset <next offset> is not > current offset <current offset>.
Possible loop detected.
Usage
Decode the raw bytes of a provided prefix tree into a Lua table.
If a key in ptree is not of type string: If a value in ptree is greater than the allowed maximum: If a value in ptree is not able to be cast to an unsigned integer: If a key in ptree has a length that would exceed the maximum NCC path: This function is called by the ncc.profile functions for reading and writing prefix trees.
▲ ncc.logic.ptree.encode (ptree)
Parameters
ptree
Table of prefix => value strings values, as returned by ncc.logic.ptree.decode (mandatory).
Returns
A binary string of raw prefix tree bytes.
Errors
If the ptree provided is not a table:
Prefix tree must be table not <ptree type>.
Profile table keys must be string not <key type>
Profile table value <value> is > <unsigned long maximum>, not supported.
Profile table value <value> is not integer, not supported.
Profile key length <key length> bytes is > <maximum path length (38)> byte limit.
Usage
Encode the provided prefix tree ptree in a Lua table into the raw bytes of a profile field suitable for storing in NCC.