AggreGate Communications Protocol

AggreGate Communications Protocol is used for communications between AggreGate LinkServer and AggreGate Agent and AggreGate Client. Communication is performed through a single TCP connection. Both sides exchange commands. In this chapter, the originator of the commands is called client, and the other side is called server. Commands are encapsulated using <STX> (0x02) and <CR> (0x0D) characters:

       <STX>command<CR>

Commands are extracted from the data stream, and all other data is discarded. If there are two or more <STX> characters without <CR>, all data belonging to the current is discarded on each received <STX>:

       <STX>aaa<STX>bbb<CR> is treated as command bbb.

Command Structure

Each command consists of several parts separated by 0x17 (“Command Separator”) characters. The command separator character is represented by / in this manual. For example:

<STX>aaa/bbb/ccc<CR>

contains three parts: aaa, bbb and ccc.

Thus, three characters are reserved and may not appear inside command parts:

Every command has the following structure:

<STX>command_code/command_parameters…<CR>

command_code is a single character, one of:

command_parameters is one or more parameters specific to the command code and separated by /.

Commands Reference

“Message” Command

The structure of this command is as follows (from this point, leading <STX> and terminating <CR> characters are not shown):

M/message_ID/message_code/message_parameters…

message_ID is unique within the current session.

message_code is a character, indicating the message type. Available message codes:

message_parameters is one or more parameter(s) specific to the message code, separated by /.

“Reply” Command

R/reply_ID/reply_code/reply_parameters…

reply_ID should be equal to the ID of the message being replied.

reply_code parameter is a character that indicates type of reply. Available reply codes:

Messages Reference

“Start” Message

M/message_ID/S/protocol_version

The format of this message is guaranteed to remain unchanged in the future. It should be sent by the client as the very first command during the data exchange with the server. The server returns an error if any other message is issued before the Start message was sent.

protocol_version is an integer number indicating the version of the communications protocol supported by client. The current version is 2.

Server responds to the Start command with a Reply command. If protocol version specified by client is supported by server, the reply code is Success, otherwise it is Denied. See description of the Reply command for more info.

“Operation” Message

M/message_ID/O/operation/context_name/entity[/data_table]

The Operation command orders the server to execute an operation on a given context.

Operation is a character specifying the operation to be executed. context_name is the name of the context for which the requested operation is executed. entity is an operation-specific parameter. It can be a variable name if operation is “Set Variable”, or a function name if operation is “Call Function”.

List of available operation codes:

data_table is an optional parameter containing operation specific data. See Data Table Encoding appendix for details.

“Event” Message

M//E/context_name/event_name/event_level/event_ID/event_listener_ID/data_table

This message is sent to the client when an event named event_name fires in context_name and this client was previously added as a listener for this event. It does not require any reply from the client. If the event is persistent, the event_ID field contains its unique ID. event_listener_ID is an integer number that indicates the listener object on the client side. data_table contains event-specific data.

Note: The "event" message has empty message_ID parameter.

Operations Reference

“Get variable” Operation

M/message_id/O/G/context _name/variable_name

This operation returns variable_name from context_name.

If the variable is found and no error occurred, the reply to this command includes the data table containing the value of the requested variable:

R/reply_id/A/data_table

“Set Variable” Operation

M/message_id/O/S/context _name/variable_name/data_table

This operation sets variable_name of context_name to the value contained in data_table.

If the variable value was changed successfully, the server replies:

R/reply_id/A

“Call Function” Operation

M/message_id/O/C/context _name/function_name/data_table

This operation calls function_name from context_name with data_table as input.

If no error occurred, the reply includes a data table containing the function's output:

R/reply_id/A/data_table

“Add Event Listener” Operation

M/message_id/O/L/context _name/event_name/event_listener_ID

This operation registers a listener with the specified integer event_listener_ID for the event_name in context_name. When this event fires, client receives an “Event” (E) message with the same event_listener_ID code.

On successfully adding event listener, server replies:

R/reply_id/A

“Remove Event Listener” operation

M/message_id/O/R/context _name/event_name/event_listener_ID

This operation removes listener with the specified event_listener_ID of event_name in context_name.

On successfully removing listener, server replies:

R/reply_id/A

Data Table Encoding

All data values received or sent within this protocol are represented by Data Tables. Every Data Table is encoded to the string to be inserted into the command. See Data Table Encoding for details.