Before you read

• Grab a coffee

Overview

In order for a client to communicate with the server a connection must be established. There are multiple ways to tell the API to do this, and there are multiple types of connections. Below we explain it all.

 

Host, port, and transport types

Before a client can connect to the server the server must be listening for connections on a specific host and port. A host is a DNS or ip - such as "electrotank.com" or "127.0.0.1". The port is a number that is chosen that no other application is using to keep data routed to the right place - such as 9899. The transport type is the type of connection and how it is used. Here are the supported transport types by ElectroServer and which client APIs support them.

 

 

Here they are described:

• BinaryTCP - This is the most common connection used across all clients. It is a socket that uses TCP and communicates using the binary protocol.
• HTTP - This type of connection should be used as a fallback. If the BinaryTCP connection fails due to a firewall or proxy server issue, then the HTTP connection should succeed since it looks like web traffic. It is a little slower and less efficient than BinaryTCP, but is still good for most uses.
• UDP - UDP is typically used in games for rapid message sending. By design, these messages should be expected to be unreliable as some may never reach their destination.
• RTMP - This is a Flash-only connection type used for streaming audio and video to achieve things like video chat.
• TextTCP - This is simply here to support ActionScript 2. ActionScript 2 only allows for a string-based protocol over a socket.

There are times when the client may want to establish more than one connection with the server. For example, for video chat. First the client would connect using BinaryTCP, find its way to a chat room, and then establish an RTMP connection for audio/video streaming.

 

Similarly, a client may want to have a BinaryTCP connection established in a first person shooter game, but also establish a UDP connection for rapid position updates.

It should be noted that some connection types can be standalone, which we call "primary", or are used only with a primary connection, which we call "secondary".

 

 

Connecting to ElectroServer

To connect to ElectroServer the client API must first be configured with one or more available connections to attempt. This can be done in two ways:

• Automatic - This is the simplest approach. List the available connections in an XML file and the API will load and use those.
• Manual - Using code you can manually configure the available connections and then add them to the API.

Both of those techniques will be shown below.

 

When the API is told to connect it starts with the first available connection in the list and tries to connect to it. If it fails, then it moves on to the next, and so on. When a connection it stops trying new ones. For each individual connection success or failure a ConnectionAttemptResponse event is fired. When a connection succeeds or when the all fail, a ConnectionResponse event is fired.

 

Connecting automatically

Here are the contents of a properly formatted settings file. This is file describes the host, port, and transport type for two available connections. The order matters. Firs the server will try to connect using BinaryTCP, if that fails it will move on to HTTP.

The value of the serverId parameter doesn't matter so long as you use the same value everywhere. There are some future features of ElectroServer that will use this, and so it was added now.

 

Using the settings.xml file is easy. Assuming that you already have an instance of the API called '_es', here is the line of code that will both load XML file and then immediately start trying to connect.

To capture the ConnectionResponse event add this line.

The onConnectionResponse takes a ConnectionResponse object.

Connecting manually

Connecting manually is possible as well. To do this you first create an instance of the Server class. Then you add instances of AvailableConnection to it. Then the server class is added to the API. And finally the API is simple told to connect.