Acarsd client

From Acarsd

How to build your own acarsd client

If you wish to connect to one (or more) running acarsd servers you'll need an acarsd client. You can download one of the already existing clients from our download section or you build your own acarsd client application.

How to build your own acarsd client application

This is a short description on how to build your own acarsd client software application.

The communication between server & client is done via normal TCP sockets. Read the manual of your favorite programming language on how to create a normal TCP socket. Under C you'll use the socket() systemcall to get a new socket. The communication between client and server will be initiated by the client software and can be closed by the server or the client software. All communication pakets between client and server have a fixed length and a fixed structure.

Paket structure:

struct server_data {
    int operation;                             // Integer 4 bytes long
    int length;                                  // Integer 4 bytes long
    unsigned long numvalue;          // Long Integer 4 bytes long
    char data[4096];                       // Array of chars with 4096 bytes
};

The operation field will be filled (by client & server) with defined integer values. See the current acarsd API table to get a list of the supported values. All pakets with values < AS_BINARY (200) are plain pakets where the data array contains normal strings in standard C notation (trailing 0 byte). Binary pakets contains a defined length of bytes.

The lower word of the length field contains the length of the following string in data. If the paket is of type AS_CXML or AS_XML the high word of the length field contains the length of the string and the lower word contains the length of the bytestream. This will be used to decompress ZIP compressed binary content (such as standard ACARS transmissions) Some pakets are used to transfer numerical values to client or to the server. The numerical value will be available within the numvalue member of the structure.

After you have got your socket, you should use the connect() function to connect to the selected server on the given port (default is 2202) When you are successfully connected, you'll get the first paket from the server. The paket identifier will be AS_ACARSD and the data member will contain a tab separated string of:

Programname <TAB> Version <TAB> API Version

This can be used by your client to display the serverinformations to the enduser. After this paket you'll get a license information (AS_LICENSE) when the server has a valid acarsd license. If you'll get the AS_BUSY paket, you have to close the connection, because the server is full and no more online slots are available. In this case the server will also close the connection to your client. Now you should send your first paket to the server. Normally this is the AS_CLIENT with the versioninformations of your acarsd client. The versioninformations are send as string where all 3 fields are separated by space

Major version <SPACE> Minor version <SPACE> Revision

Now you should send information on how you can handle ACARS transmissions. ACARS transmissions will be send as ZIP compressed XML string. All acarsd versions up to 1.65 can send compressed and uncompressed strings. From 1.66 we will remove the support of uncompressed XML pakets! So please send your AS_USECOMP paket and set the string of the data member to CXML to tell acarsd that you can handle compressed XML strings. All other pakets are depends on your configuration. For example you can send the AS_UPLINKS paket, the AS_BADMSG and some other 'switch' pakets to controll the results of your communication.

The next paket from the server will be the AS_WELXML paket which contains a small XML string (uncompressed) with the server settings and capabilities. It's possible that the serveradmin has set a password to enable message content or to allow connections. In these cases you'll get the AS_ADMINMSG and AS_IDENTIFY pakets. AS_ADMINMSG pakets always contain a normal string which can be displayed to the enduser of your client application. AS_IDENTIFY pakets should be answered with the same code (AS_IDENTIFY) and the name of your client application within the data member of the communication structure.

The server can everytime close the connection. In normal cases (no broken connection or crashes) you'll get the AS_CBYE paket before the connection will be closed.

If a password is needed to stay connected or to see the message content, you should send the AS_ENABLE paket where the data member contains the MD5 checksum over the correct password. The AS_NEEDPWD paket to request your password is obsolete on servers newer than 1.50

The server will wait appr. 45 seconds for your AS_ENABLE paket.

Now, after the welcome handshake is done, you should enter a communication loop where you check for waiting pakets from the server or where you send pakets to the server (Report requests, Mailing requests or others)

Please read the acarsd API table to see which pakets are possible and supported within Client <-> Server communication. The FLOW column of the table will show you the initiator of the paket. SC means Server to Client and CS means Client to Server. Some pakets (like AS_IDENTIFY) can be send in both directions.

How to work on binary pakets?

Binary pakets (the operation member is greater/equal AS_BINARY (200)) are special pakets. The first AS_BINARY paket will contain the length information of the following stream and the first (max. 4096, see structure) bytes of the binary stream. AS_BINARY streams are not compressed and can be saved as is. AS_COMPR pakets are like AS_BINARY except the contect is ZIP compressed. Before you'll get a AS_COMPR paket, you should get an AS_AREPCNTC or AS_RECHCNTC paket. The string value of such a paket is separated by tab and will contain the following informations:

Uncompressed size <TAB> Compressed size <TAB> Searchstring

The searchstring element can contain the original search request from your client application or an empty string. Now you should get the AS_COMPR paket until you have read Compressed size bytes from the data member of the AS_COMPR paket. After you have all needed bytes you should decompress the bytestream. There are a some free ZIB libs available for different environements. If the result of the decompress operation has the same length as the Uncompressed size you can display the string. In all other cases this look like an error. Check you handling and your decompress functions!

The AS_CXML paket contains compressed ACARS data. There is NO lead paket for this one. Every AS_CXML contains one ACARS transmission in XML format. The original length of the XML string is defined in the high word of the length member and the uncompressed size in the low word. Read LOWORD() bytes and decompress the result stream. Now you should get the ACARS transmission as XML string.

Operation types which are marked with INTERNAL (see acarsd API table) should never be send between client & server. The server will ignore these types if they are received via the socket part of acarsd.

Before you terminate the connection you should send the AS_BYE paket to the server.

You can use the AS_HEART paket to check if you are still connected. The answer will be AS_HEARTOK within a defined timeout. If not than your connection is broken and you should close the socket.