Navigation :

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


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`


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`


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`


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`


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.` If the bytes provided is not a string: `Bytes must be string not <bytes type>.` If the length of bytes is not a multiple of 4: `Bytes len of <bytes length> is not a multiple of four bytes.` If the length of bytes is less than 4 (the minimum for a profile num_entries field): `Bytes insufficient length for num_entries.` If the length of bytes is not long enough for the encoded num_entries field): `Bytes insufficient length for <num_entries> entries.` If an encoded data offset does not point to a valid location in bytes: `Data <data offset> offset must be longword aligned.` If the end of an encoded data offset points past the end of bytes: `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. This function is not used in the N2 Logic Node.


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.` If the profile provided is not a table: `Profile must be table not <profile type>.` If a key in profile is not a number: `Profile keys must be number not <key type>` If a value in profile is not a string: `Profile values must be string not <value type>` If a tag number is negative in profile: `Profile tag <tag number> is negative, not supported.` If a tag number is higher than the supported maximum: `Profile tag <tag number> is > <unsigned long maximum>, not supported.` If a tag number cannot be cast to an integer: `Profile tag <tag number> is not integer, not supported.` If a value length is greater than the supported maximum: `Profile value length <value length> bytes is > <unsigned long maximum> byte limit.` If the total length of the encoded profile is greater than the supported maximum: `Profile total length <profile length> bytes is > <unsigned long maximum> byte limit.` Additionally, some errors are - in theory - impossible: `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). 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.


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>.` If the prefix path goes beyond what NCC supports: `Max path length <maximum path length (38)> reached in prefix tree, cannot recurse further.` If the offset of a node does not provide enough room for the node: `Insufficient bytes to process uncompressed node. Have <available bytes>, need 4.` `Insufficient bytes to process compressed node. Have <available bytes>, need 8.` If the characters at the node will not fit in the available bytes: `Insufficient bytes to process compressed node with <number of path chars>` `path chars. Have <available bytes>, need <required bytes>.` If the sub-nodes at the node will not fit in the available bytes: `Insufficient bytes to process uncompressed node with <number of sub-nodes> sub-nodes.` `Have <available bytes>, need <required bytes>.` If the maximum path length would be exceeded while processing nodes: `Max path length <maximum path length (38)> exceeded in prefix tree` `trying to add <number of path chars> to <current path length>.` If the offset provided indicates a circular definition: `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. 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.


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>.` If a key in ptree is not of type string: `Profile table keys must be string not <key type>` If a value in ptree is greater than the allowed maximum: `Profile table value <value> is > <unsigned long maximum>, not supported.` If a value in ptree is not able to be cast to an unsigned integer: `Profile table value <value> is not integer, not supported.` If a key in ptree has a length that would exceed the maximum NCC path: `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. This function is called by the ncc.profile functions for reading and writing prefix trees.