IPC Encoding
Introduction
The n2svcd applications send messages to each other via shared memory circular buffers.
The encoding for this buffer is described here.
Encoding of integer and double values may vary across architecture. This format is not intended for inter-architecture data exchange.
IPC Message Header
Every message in the circular shared memory IPC buffer begins with a 4-byte unsigned integer describing the message body length, followed by the actual message.
| Field | Type | Description |
|---|---|---|
| Message Length | 4 Byte Unsigned Integer | The number of bytes that follow in the frozen envelope. |
| Envelope | Frozen HASH | The bytes of the frozen envelope HASH. |
Envelope HASH
All messages are wrapped in an enveloper which is a HASH frozen according to the HASH freezing rules described below.
| Field | Type | Description |
|---|---|---|
| Envelope | Frozen HASH | [Required] Container for the message elements. |
| Sender | Frozen STRING |
The name of the sending application. (Default = sender is anonymous and no reply is possible) |
| Sender Context | Frozen Element |
A Frozen element (typically a STRING) which should be returned to the sending application when responding
to this message, to identify the particular instance or dialog for correlation purposes. (Default = message is sent by the application not by an instance, or instance does not allow response) |
| Context | Frozen Element |
A Frozen element (typically a STRING) which is the context which we supplied earlier in the dialog,
and is now being returned to us to allow us to correlate the relevant instance or dialog. (Default = original message was sent by an application not by an instance) |
| Messsage | Frozen STRING | [Required] The name of the message which determines the expected structure of the details. |
| Details | Frozen HASH |
[Required] The details of the message. This must be present, even if it is an empty HASH. |
| Trace Level |
0 - 3
|
A request that the receiving application should activate tracing for the receiving instance.0 = None, 1 = Debug, 2 = Dump, 3 = Spam.(Default = do not activate tracing) |
| Sent TimeVal | Frozen ARRAY | The time at which the message was submitted for delivery. An array of 2 Frozen INTEGER values. |
| [0] | Frozen INTEGER | The epoch seconds at which the message was submitted for delivery. |
| [1] | Frozen INTEGER | The epoch microseconds at which the message was submitted for delivery. |
Frozen UNDEF
A Frozen UNDEF is represented as follows.
| Field | Type | Description |
|---|---|---|
00 00 00 01
|
4 Bytes Header |
An explicit UNDEF (i.e. NULL or NIL) header is a four byte sequence. The first three bytes are the body length (no body is present). The last byte is the UNDEF type indicator 01.
|
Example: 00 00 00 01.
Frozen INTEGER
A Frozen INTEGER is represented as follows.
| Field | Type | Description |
|---|---|---|
08 00 00 02
|
4 Bytes Header |
An integer value header is a four byte sequence. The first three bytes are the body length of 8 bytes, in little-endian order. The last byte is the INTEGER type indicator 02.
|
| Value | 8 Bytes Body | The value is x86-64 signed integer encoding. |
Example: 08 00 00 02 e8 03 00 00 00 00 00 00.
This represents the integer 1000.
Frozen DOUBLE
A Frozen DOUBLE is represented as follows.
| Field | Type | Description |
|---|---|---|
08 00 00 03
|
4 Bytes Header |
A floating/double value header is a four byte sequence. The first three bytes are the body length of 8 bytes, in little-endian order. The last byte is the DOUBLE type indicator 03.
|
| Value | 8 Bytes Body | The value is x86-64 signed double encoding according to the platform. |
Example: 08 00 00 03 b4 e4 f1 b4 fc b0 28 40.
This represents the double 12.345678.
Frozen TRUE
A Frozen TRUE is represented as follows.
| Field | Type | Description |
|---|---|---|
00 00 00 05
|
4 Bytes Header |
An explicit boolean TRUE value header is a four byte sequence. The first three bytes are the body length (no body is present). The last byte is the TRUE type indicator 05.
|
Example: 00 00 00 05.
Frozen FALSE
A Frozen FALSE is represented as follows.
| Field | Type | Description |
|---|---|---|
00 00 00 06
|
4 Bytes Header |
An explicit boolean FALSE value header is a four byte sequence. The first three bytes are the body length (no body is present). The last byte is the FALSE type indicator 06.
|
Example: 00 00 00 06.
Frozen STRING
A Frozen STRING is represented as follows.
| Field | Type | Description |
|---|---|---|
xx yy zz 04
|
4 Bytes Header |
A string value header is a four byte sequence. The first three bytes are the usable byte length of the string sequence (not including padding). The last byte is the STRING type indicator 04.
|
| Value | "N" Bytes Body |
The body is the sequence of bytes in the string, in little-endian order. This must be padded to a multiple of 4 bytes by adding 1, 2, or 3 padding bytes. The padding bytes should be 00 but this is not strictly enforced.
|
Example: 05 00 00 04 74 65 73 74 32 00 00 00.
This represents the 5-byte string sequence “test2”.
Example: 00 00 00 04.
This represents the 0-byte empty string sequence “”.
Frozen ARRAY
A Frozen ARRAY is represented as follows.
| Field | Type | Description |
|---|---|---|
xx yy zz 07
|
4 Bytes Header |
A array value header is a four byte sequence. The first three bytes are the total length of the contents including the size field. The last byte is the ARRAY type indicator 07.
|
aa bb cc dd
|
4 Bytes Size Field | The array size is the number of contained elements as a little-endian 4 byte unsigned integer. |
| Values | Sequence of Frozen Elements | The frozen array elements follows, encoded according to their type. |
Example:
28 00 00 07 02 00 00 00
01 00 00 04 58 00 00 00
18 00 00 07 02 00 00 00
01 00 00 04 59 00 00 00
08 00 00 03 00 00 00 00 00 00 0c 40
This represents the following nested ARRAY structure:
[ "X", [ "Y", 3.5 ] ]
Frozen HASH
A Frozen HASH is represented as follows.
| Field | Type | Description |
|---|---|---|
xx yy zz 08
|
4 Bytes Header |
A array value header is a four byte sequence. The first three bytes are the total length of the contents including the size field. The last byte is the HASH type indicator 08.
|
aa bb cc dd
|
4 Bytes Size Field | The hash size is the number of contained key/value pairs as a little-endian 4 byte unsigned integer. |
| Values | Sequence of Key/Value Pairs |
Each key value pair follows in the body – Key-0, Value-0, Key-1, Value-1, ... Each key is encoded as a Frozen STRING. Each value is encoded as the applicable type, which may be a nested ARRAY or HASH. These key/value pairs are not required to be sorted in any order. |
Example:
2c 00 00 08 01 00 00 00
05 00 00 04 54 48 49 53 31 00 00 00
18 00 00 08 01 00 00 00
05 00 00 04 54 48 41 54 31 00 00 00
04 00 00 08 00 00 00 00
This represents the following nested HASH structure:
{ 'THIS1' => { 'THAT1' => { } } }