Network configuration

The XML Network configuration file specifies the configuration of the Network for a Client / Server communication. Note that it is only necessary to specify a common configuration properties Network if the communication is not basic.

Grammar

See the Network configuration Schema

Parsing of the XML File

The XML file root specifies the attributes of the Network. Each child "channel" XML node specifies the properties for one channel.

Network element

The Network element has several attributes:

• "protocol": specifies the ID of protocol which will be used by default for every Channel if the Channel does not override its value
• "notifMode": specifies how the notification will be sent (useful for the Server only, this property will have to effect for a Client). See Network notification mode
• "reinitOnConnection": set if Layers will send a A661_NOTE_REINIT_LAYER_DATA notification when notifying their activation upon Server connection
• "disconnectProtocolsOnClose": set if the Protocols must be disconnected if the Network is disconnected (default is true). Note that this should be the default value, be it is possible that some User Applications don't handle the disconnection / reconnection properly (the Server and Client handle the disconnection properly)
• "autoActivateLayers" : set if the layers will be auto-activated at start. In that case Layers will never take into account requests from the Client to make them inactive
• "tempoOnActivation": the default value for the temporisation on a Channel activation (used by default on all Channels). Note that this property can be overriden by any layer, including by removing the temporisation for a specific Layer (by using the value" none" for the Channel associated property)
• "comThreshold": the threshold value in ms which will be used by the Network to determine if the application on the other side of the connection was connected before this application

Channel element

• channel: A channel is characterized by a name (two channels must NOT have the same name), and an optional output host. If the output host if not defined, it will be the localhost
• direction: The direction can be one of: For every other direction tag, the handler will emit an exception.
• "input" : will be set for the input
• "output" : will be set for the output
• "serverInput" : will be set for the input for the Server, and the output for the Client
• "serverOutput" : will be set for the output for the Server, and the input for the Server
• layerSet: Parse the definition of a LayerSet for the lastChannel. The layers defined in this set will be added to the Channel. Several types of LayerSets can be defined:
• appli="2": take into account all the layers for the application ID
• appli="2" layers="*": take into account all the layers for the application ID
• appli="2" layers="2-10": take into account all layers from layerID 2 to layerID 10 for the application ID
• "property": a property to configure the protocol. Some properties are general to all protocols, but protocols can support their own properties. Note that a specific "server.evtProcessorYield" property is supported for all protocols and allows to set a minimum delay in ms between two events sent by the Server to the UA

Controlling the use of a property or direction

It is possible to control if a "property" or "direction" will be applied by using the "engine" XML attribute:

• The value "server" will only apply the "property" or "direction" for a Server engine
• The value "client" will only apply the "property" or "direction" for a Client engine

Generic properties

• "protocol": the protocol type. The supported built-in types are "tcp", "udp", "webserver", or "sharedmemory", but custom ProtocolProviders can define their own protocols
• "protocol.isSilent": refer to a silent protocol, which is a protocol which listen to input events, but which does not pass the contents to its Engine
• "maximumQueueSize": The property name to specify the maximum queue size for the protocol Channels. The value is an int and sets the number of Buffers which will be stored by the Protocol in case the Engine could not process them
• "queueRate": The property name to specify the queue rate. For example a value of 2 means that only one message will be decoded every 2 messages. By default every message will be decoded if the queue is not full
• "tempoOnActivation": This property specifies the temporisation on a Channel activation. The value is specified in ms, meaning that the Channel will notify for the activation of its Layers (and possibly ask for their reinitilization), if the last time an activation was send was greater than the value of the temporisation. Note that specifying the value "none" for this property will remove the temporisation for the Channel if it was specified at the Network level

Socket protocols properties

• "protocol.host": the host of the other side of the connection for socket protocols
• "protocol.SO_RCVBUF": The SO_RCVBUF property. This is a hint on the expected received buffer size
• "protocol.SO_SNDBUF": The SO_SNDBUF property. This is a hint on the expected sent buffer size
• "protocol.SO_BROADCAST": The SO_BROADCAST property. Allows to define UDP sockets as broadcasted
• "protocol.IP_TOS": The type of service (IP_TOS) property. The type of service (IP_TOS) property. See wikipedia.org/wiki/Type_of_service or Socket.html#setTrafficClass for more informations on how to set this property
• "protocol.broadcastAddress": The broadcast address property, to use with "protocol.SO_BROADCAST"
• "protocol.blockingConnect": A boolean property which specifies that the connection must be blocking if possible for a protocol. It will wait (for example for a TCP protocol) for the other side of the Connection to be ready if set to true, before exiting the Connection Thread

Specific TCP protocol properties

• "protocol.TCP_NODELAY": The TCP_NODELAY property for the TCP protocol. A value of false will disable the Nagle's algorithm which by default try to reduce the bandwidth rather than the latency
• "protocol.tcpAcceptIncompleteBuffers": A boolean property which specifies that TCP protocols accept incomplete buffers and will merge the buffers for several consecutive receptions if they are incomplete^[1]
  It is important to consider that UDP sockets on Windows do not accept sockets which length is greater than 65535, so you should not define an input size of more than 65535 for UDP sockets. For TCP protocols, sockets will be truncated at the OS transfer layer if their length is greater than 65535. As TCP ensures that the blocks are sent in the correct order, it is however possible to recompose the initial sent buffer by merging the separate buffers

Examples

Simple example

<network>
  <channel name="channel1">
    <direction type="serverInput" port="8080" size="1000" />
    <direction type="serverOutput" port="8081" size="150" />
    <layerSet layers="*" />
  </channel>
</network>

In this example:

• There is only one Channel, using the default UDP protocol
• The Server input port is 8080, the Server output port is 8081. The Client can use the same configuration and use the port 8081 for the input port, and 8080 for the output port.

Note that this example is equivalent to:

<network>
  <channel name="channel1">
    <direction type="input" port="8080" size="1000" engine="server" />
    <direction type="output" port="8081" size="150" engine="server" />
    <direction type="input" port="8081" size="150" engine="client" />
    <direction type="output" port="8080" size="1000" engine="client" />
    <layerSet layers="*" />
  </channel>
</network>

Two Channels

<network>
  <channel name="channel1">
    <direction type="serverInput" port="8080" size="1000" />
    <direction type="serverOutput" port="8081" size="150" />
    <layerSet appli="1" />
    <property key="protocol" value="tcp" />
  </channel>
  <channel name="channel2">
    <direction type="serverInput" port="8083" size="1000" />
    <direction type="serverOutput" port="8084" size="150" />
    <layerSet appli="2" />
    <property key="protocol" value="udp" />
  </channel>
</network>

In this example:

• There are two channels. The first "channel1" channel is used for all Layers in the Application ID 1. The second "channel2" channel is used for all Layers in the Application ID 2
• The first Channel use the TCP protocol, the second channel use the UDP protocol

Network notification mode

The Network Network notification mode specifies when the Server will notify the A661_LAYER_ACTIVE notificaiton to the Client.

• "immediate" (default value): Layers in all Channels will automatically and immediately notify their availability at Server start, regardless of the detection of the User Application presence or not
• "onConnection": Layers in all Channels will notify their availability when their associated Channel detect its connection
• "onFirstConnection": Layers in all Channels will notify their availability, only for the Server initialization, when their associated Channel detect its connection. For example, at Server connection, when the Server detect that the Client is available, the notification message will be sent for every Layer, but if the connection is lost, the Server will not send again notification messages if the connection comes back again
• "never": Layers in all Channels will never notify their availability

Event Queue Size

The "maximumEventQueue" property specifies the maximum queue size for the protocol Channels.The property value is an int and sets the number of Buffers which will be stored by the Protocol in case the Engine could not process them (typically if too much buffers have been received in a very short amount of time). This property can have the following values:

• "blocking" or 1: the protocol Channels do not store any unprocessed Buffer, which means that a Buffer which could not be processed is lost. This is typically to use for cyclic messages as for example aircraft position and other live parameters
• >= 2: the protocol Channels store the specified number of unprocessed Buffers, which means that a Buffer which could not be processed will be stored if this number of stored Buffers has not been reached. The unprocessed buffers which have been stored will be processed when possible and removed from the Queue. This is typically to use for event messages as for example state parameters in Layers
• "unlimited" or -1: the protocol Channels store all unprocessed Buffers, which means that a Buffer which could not be processed will be stored and processed when possible and removed from the Queue. This case is the default but is dangerous in real-life use cases because the Queue can fill up quickly if too much Buffers are received