AudioGalaxy Client Protocol

Contents

• Introduction and Overview
• Technical Details
  • Connecting to the server
  • Redirection servers
  • Proxy test
  • Informing the Server of shares
  • Transfering files
    • If the client must listen for a connection
    • If the client make a connection
    • If the client downloads
    • Transfer shutdown
  • Client upgrades
• Data formats
  • Redirection message
  • Peer-to-peer messages
    • FileRequest
    • FileRequestReply
  • Client/Server message
    • Protocol for 0.606W and 0.608W
    • Protocol for 0.520L
  • Text encoding
• Message types
  • Login (&0) 0.606W
  • Login (&0) 0.608W
  • Logout (&1)
  • NewSharedFile (&2) 0.520L
  • FileDeleted (&4)
  • ReadyForTransfer (&5)
  • FileTransferState (&6)
  • ReadyToSendShares (&7)
  • SendSharesStandBy (&8)
  • SendShares (&9)
  • FileTransfer (&A)
  • StopFileTransfer (&B)
  • NewShareReply (&D)
  • LoginError (&E)
  • PlayFile (&F)
  • AccountExistence (&1F)
  • OldShares (&20)
  • NewSharedFile (&21) 0.608W
  • DeleteReply (&22)
  • NewAccount (&23)
  • MagicRequest (&24)
  • NewAccountReply (&32)
  • AccountExistenceReply (&33)
  • DeleteRequest (&34)
  • PlaySongList (&35)
  • MagicResponse (&37)
  • ActivateGo (&38)

Introduction and Overview

This document describes the way in which the AudioGalaxy software communicates with server. It describes the structure of messages, between 2 clients, and the messages used. This document is a simple instruction guide, for public use. It can be enriched by any one who has an information related to the topic of this document. If you have found any faults, or you wish to add anything, just mail me (insert original author details). The following information was received by analysing the traffic from AGSatelite.exe (client version 0.606W, 0.608W, and the linux version 0.520L).

This document was constructed from an original document written by Mity. This document was written by Justin Fletcher, using the RISC OS client (by Marc Warne) as a test platform for the messages. It is Mity who should get the praise for the information in this document - he's the one who worked out 99% of it. I should also like to thing Marc Warne and Eric Seidel for their help

Technical Details

The AudioGalaxy Satellite (in future referred to as the 'Client') uses TCP for data transmission. The connection to servers is made through port 21. The connecting client will contact 2 servers. The first of these is the redirection server. This provides the address of the second server (in future referred to as the 'Server') with which the client will communicate.

Connecting to the server

In order to connect to the Server, the client connects first to the redirection server, then attempts a connection to the Server itself. The sequence a Client should use to connect and hold a connection to the Server is :

1. Client makes connection to the redirection server
2. Client receives a REDIRECTION message.
3. Client disconnects from redirection server and connects to the Server as given in the REDIRECTION message.
4. If the connection fails, the client should retry the redirection server for another host to connect to.
5. Clients using the 0.608W protocol should send Message_MagicRequest. The server will reply with Message_MagicResponse.
6. Client then sends Message_Login 0.606W or Message_Login 0.608W message, using the appropriate variant.
7. Server tests the abilities of the client to Listen, and to Connect (further proxy test)
8. Inform server of shared files. Only files which are audio MPEGs should be shared, and they should end in .mp3. Shared files should be longer than 32k.
9. Every 30 seconds (for 608W) or 22 seconds (for 508L), you send Message_ReadyForTransfer to inform the server that you are still alive and of the progress of transfers.

Redirection servers

Clients connecting for normal accounts should resolve garlic.audiogalaxy.com and connect to that for server redirection. Multiple results may be returned for this host and clients should step through these in order. Clients should not attempt to connect to all hosts simultaneously as this will increase the load on the server and negate the point of having multiple addresses. The address order will be rotated by the server in order to reduce the load on the redirection servers.

Clients connecting for 'Gold' accounts should resolve gold.audiogalaxy.com and perform the same sequence as those for the normal accounts. As with normal accounts, multiple addresses may be returned but do not, at present, appear to be.

Proxy test

The Server sends Message_FileTransfer message which makes the Client download the 'proxy test' file. Connection is made with client-client protocol. After connecting to server or opening port, the Client sends message Message_FileTransferState with status 3. After the Client sends FileRequest, server closes the connection without sending any data (this stage checks that the connection is available and is able to function as a means of transferring files). After connection is closed, the Client sends Message_FileTransferState with status 5. There are 3 tests. 2 - test for an ability to Listen, 1 - test for ability to Connect.

Informing the Server of shares

The server sends Message_SendSharesStandBy a few times, to which you reply with message 7. Then server sends Message_SendShares message. This message shows that you can send your shares. If you have any new files (which don't have server id) in the database you send it's info with Message_NewSharedFile 0.520L or Message_NewSharedFile 0.608W, then the server will reply with message Message_NewShareReply with the server IDs for the file. To inform the server about the files which already have server id, and that they are online, you send Message_OldShares. If you don't have any files to share, you reply with Message_ReadyToSendShares, but if so you will not be able to download more then 1 file at a time.

Transfering files

After going through Message_Login 0.606W or Message_Login 0.608W process, the client may receive Message_FileTransfer message. This is an notification from the server to start a file transfer. It may inform you to upload or download file, and also includes information about whether the client should Listen or Connect.

If the client must listen for a connection

1. The Client opens a port defined in the message Message_FileTransfer. The IP given in the message is just a mask, it shows only first 2 bytes.
2. The Client sends Message_FileTransferState status 3

If the client make a connection

1. The Client makes a connection to the IP and port defined in message Message_FileTransfer
2. The Client sends Message_FileTransferState status 3

If the client downloads

1. After connection is done Client sends FileRequest message which consists of FILE_ID received from Message_FileTransfer. The size of the file to be downloaded, and the position to resume (the first byte of the file is at position 0).
2. If the file was found, the sender sends a response to the receiver (see below). After finishing, both sides send Message_FileTransferState status 0. And the downloader sends Message_NewSharedFile 0.520L or Message_NewSharedFile 0.608W with the information on new file.

Transfer shutdown

During file transfer server may send message Message_StopFileTransfer with the FILE_ID of the transfer to be shutdown. After the file transfer connection is closed, the Client sends Message_FileTransferState status 8.

Client upgrades

The server may send to a client a file named AGSatellite.exe. This file is an upgrade for the client and will be run by the Windows client. It does not appear that a normal user can share such a file.

It is strongly recommended that clients not handle such cases and possibly warn the user of attempts to upgrade clients in this manner. Whilst unlikely, this may be a means in future to execute unauthorised content on a machine if the AudioGalaxy servers are compromised. Since no security checks can be performed on the executable it is impossible to tell whether it is from AudioGalaxy or not. This is quite aside from the fact that the file will be an x86 executable.

Data formats

Within messages passed between clients, values are passed in big-endian format, ie the largest byte value appears first in the stream. A number of data types are used to describe the content of the stream.

Data type	Meaning
String	A variable length field which contains textual data. It consists of 2-bytes which describe the string length (excluding the 2-bytes themselves) followed by the string.
Block	A variable length field which contains binary data. It consists of 2-bytes which describe the data block length (excluding the 2-bytes themselves) followed by the block.
Byte	A single byte value
Word	A 2-byte value
Integer	A 4-byte value

Redirection message

When the Client connects to the redirection server, a reply is sent back to indicate the Server that the Client should connect to.

Type	Name	Contents
Integer	START_SIGNAL	0x455FD0D5
Integer	MESSAGE_SIZE	Size of the whole message without START_SIGNAL
Integer	ID	Message count
Integer	PORT	Port to connect to
String	SERVER_IP	IP to connect to

Peer-to-peer messages

Peer-to-peer connections supply a 'message count' (ID) which is not used by either end of the connection. It is usual to start a counter at zero and with every FileRequest or FileRequestReply to increment this counter. Whilst it might seem obvious to use this field as an additional check to return to the client, this is not done. Using an incrementing counter might be useful for tracing transactions more easily.

FileRequest

When the Client connects to the another Client to transfer a file, the Client receiving the file should send a request of the form :

Type	Name	Contents
Integer	START_SIGNAL	0x455FD0D5
Integer	MESSAGE_SIZE	Size of the whole message without START_SIGNAL
Integer	ID	Message count
Block	FILE_ID	Server file ID request
Integer	FILESIZE	Size of the file
Integer	RESUME_OFFSET	Offset in file to start at

FileRequestReply

The Client sending the file will send a similar message as a response :

Type	Name	Contents
Integer	START_SIGNAL	0x455FD0D5
Integer	MESSAGE_SIZE	Size of the whole message without START_SIGNAL
Integer	ID	Message count (need not be the same as that in the FileRequest)
String	OK	"OK"

Client/Server message

Communication with the server takes a similar form to the redirection message.

Protocol for 0.606W and 0.608W

Type	Name	Contents
Word	START_SIGNAL	0x455F
Word	MESSAGE_SIZE	Size of the whole message without START_SIGNAL
Byte	MESSAGE_TYPE	Message type (see below)

Protocol for 0.520L

Type	Name	Contents
Integer	START_SIGNAL	0x455FD0D5
Integer	MESSAGE_SIZE	Size of the whole message without START_SIGNAL
Integer	ID	Message count (starting at 0)
Word	MESSAGE_TYPE	Message type (see below)

Text encoding

For the most part, the text encoding of strings is unspecified. However, some of the strings are in particular encoding formats :

Field	Encoding
ID3v1_TITLE	Unspecified (ID3v1 restriction)
ID3v1_ARTIST	Unspecified (ID3v1 restriction)
ID3v1_ALBUM	Unspecified (ID3v1 restriction)
ID3v2_TITLE	ISO-8859-1 (ID3v2 restriction)
ID3v2_ARTIST	ISO-8859-1 (ID3v2 restriction)
ID3v2_ALBUM	ISO-8859-1 (ID3v2 restriction)

For ID3v2 data, if the encoding is not ISO-8859-1 then it will be necessary for the client to either discard the data or to convert it to ISO-8859-1.

Message types

---

Message_Login 0.606W
(&0)

Log in to the server (for 0.606W and 0.502L clients)

Message

Type	Name	Contents
Integer	UNKNOWN	Usage is unknown (use 0)
String	LOGIN	Login name
String	PASSWORD	Password
String	SATELLITE_VERSION	Satellite version "0.606W"
String	CLIENT_IP	Client IP in dotted-quad format
String	CLIENT_HOSTNAME	Client hostname
Word	FILES_SENT	Conjecture: Number of files sent (use 0)
Word	FILES_RECEIVED	Conjecture: Number of files received (use 0)

Source

Client

Use

This message is sent by the Client to notify the Server of the user name and client information required.

Related messages

Message_Logout, Message_LoginError

Document information

Maintainer(s):	Justin Fletcher <gerph@innocent.com>
History:	Revision Date Author Changes 1 12 Jan 2002 JRF First version which is recorded with a change entry. 2 22 May 2002 JRF Corrected to document passwords as being applied in lower case. Details of gold redirection server and connection recommendations (Eric Seidel) Added comments about encoding formats for ID3 text strings (Eric Seidel) Added details of encoding format (Eric Seidel) Added details of ReadyForTransfer after confirmation of my beliefs by Eric Seidel. Clarified the MD5HASH passed during login is without a block identifier. Corrected details of FileTransfer where file not found (Eric Seidel). Clarification of presence/absence of ID3v[12] data (Eric Seidel). NewShareReply FILE_ID (an integer) is now known as SERVER_ID (Eric Seidel). It is also documented as 'usually 0'. OldShare FILE_ID (an integer) is now known as SERVER_ID (Eric Seidel). PlaySongList details updated (Jeff Connelly).
Related:	None
Disclaimer:	This document is based on documentation initially created by Mity, and development of the RISC OS client !Satellite. This is not an official document from AudioGalaxy, nor is it endorsed by them.