AudioGalaxy Client Protocol


Contents


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.


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 (squash.audiogalaxy.com or garlic.audiogalaxy.com).

  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.

  9. Every 30 seconds, you send Message_ReadyForTransfer to inform the server that you are still alive.

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 the Message_NewSharedFile, 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 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.


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 typeMeaning
StringA 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.
BlockA 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.
ByteA single byte value
WordA 2-byte value
IntegerA 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.

TypeNameContents
IntegerSTART_SIGNAL0x455FD0D5
IntegerMESSAGE_SIZESize of the whole message without START_SIGNAL
IntegerIDMessage count
IntegerPORTPort to connect to
StringSERVER_IPIP 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 :

TypeNameContents
IntegerSTART_SIGNAL0x455FD0D5
IntegerMESSAGE_SIZESize of the whole message without START_SIGNAL
IntegerIDMessage count
BlockFILE_IDServer file ID request
IntegerFILESIZESize of the file
IntegerRESUME_OFFSETOffset in file to start at

FileRequestReply

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

TypeNameContents
IntegerSTART_SIGNAL0x455FD0D5
IntegerMESSAGE_SIZESize of the whole message without START_SIGNAL
IntegerIDMessage count (need not be the same as that in the FileRequest)
StringOK"OK"

Client/Server message

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

Protocol for 0.606W and 0.608W

TypeNameContents
WordSTART_SIGNAL0x455F
WordMESSAGE_SIZESize of the whole message without START_SIGNAL
ByteMESSAGE_TYPEMessage type (see below)

Protocol for 0.520L

TypeNameContents
IntegerSTART_SIGNAL0x455FD0D5
IntegerMESSAGE_SIZESize of the whole message without START_SIGNAL
IntegerIDMessage count (starting at 0)
WordMESSAGE_TYPEMessage type (see below)


Message types


Message_Login 0.606W
(&0)

Log in to the server (for 0.606W and 0.502L clients)
Message
TypeNameContents
IntegerUNKNOWNUsage is unknown (use 0)
StringLOGINLogin name
StringPASSWORDPassword
StringSATELLITE_VERSIONSatellite version "0.606W"
StringCLIENT_IPClient IP in dotted-quad format
StringCLIENT_HOSTNAMEClient hostname
WordFILES_SENTConjecture: Number of files sent (use 0)
WordFILES_RECEIVEDConjecture: 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

Message_Login 0.608W
(&0)

Log in to the server (for 0.608W clients)
Message
TypeNameContents
IntegerUNKNOWNUsage is unknown (use 0)
StringLOGINLogin name
StringNULLEmpty string
StringSATELLITE_VERSIONSatellite version "0.608W"
StringCLIENT_IPClient IP in dotted-quad format
StringCLIENT_HOSTNAMEClient hostname
WordFILES_SENTConjecture: Number of files sent (use 0)
WordFILES_RECEIVEDConjecture: Number of files received (use 0)
16 BytesMD5HASH16 byte MD5 hash of the password, prefixed by the magic value
Source
Client
Use

This message is sent by the Client to notify the Server of the user name and client information required. This version of the Login message is only applicable to 0.608W. You should respond to Message_MagicResponse with this message. If the magic prefix were 'teapot' and the users password was 'thursday', the MD5 has would be calculated of the string 'teapotthursday'.

Related messages
Message_MagicRequest, Message_MagicResponse, Message_Logout, Message_LoginError

Message_Logout
(&1)

Disconnect from the Server
Message
No additional data
Source
Client
Use

This message is sent by the Client to notify the Server that it is disconnecting.

Related messages
Message_Logout

Message_FileDeleted
(&4)

Informs the server that a file is no longer available
Message
TypeNameContents
IntegerLOCAL_IDClient identifier number
IntegerFILESIZESize of file
Source
Client
Use

This message is sent by the Client to inform the server that a file that was shared is no longer available.

Related APIs
None

Message_ReadyForTransfer
(&5)

Ping the server
Message
No additional data
Source
Client
Use

This message is sent by the Client to notify the Server that it is still alive and available for transferring files.

Related APIs
None

Message_FileTransferState
(&6)

Notification of transfer state
Message
TypeNameContents
BlockFILE_IDIdentifier for file transfer
IntegerSTATEFile transfer state :
ValueMeaning
0Download complete
1Internal error (eg file doesn't match that requested)
3Transfer being set up
4Could not connect to client
5Connection was closed
7Could not listen (eg bind failed)
8Transfer was stopped
9Reset connection (issued when connection reset was requested by user and after the socket has been closed)
Source
Client/Server
Use

This message is sent by the Client to notify the Server of the state of a file transfer.

Related APIs
None

Message_ReadyToSendShares
(&7)

Sent to notify the Server that the Client is ready to send any shared files
Message
No additional data
Source
Client
Use

This message is sent by the Client to notify the Server that it is ready to send its shared files. The Client should send it in response to messages Message_SendSharesStandBy and Message_SendShares.

Related messages
Message_SendSharesStandBy, Message_SendShares

Message_SendSharesStandBy
(&8)

Sent to notify the Client that it should prepare its list of shared files
Message
No additional data
Source
Server
Use

This message is sent by the Server to notify the Client that it should prepare shares for sending to the server. The Client should not send the shares until Message_SendShares is received. This message is sent when the proxy test completes.

Related messages
Message_ReadyToSendShares, Message_SendShares

Message_SendShares
(&9)

Sent to notify the Client that it should send its list of shared files
Message
No additional data
Source
Server
Use

This message is sent by the Server to notify the Client that it should send its list of shared files to the Server. The client should acknowledge this message with Message_ReadyToSendShares, followed by a list of shared files.

Within the list, files which are known to AudioGalaxy should be provided with Message_OldShares which includes the server file identifier. Any files which are not known to the AudioGalaxy server (or for which you do not keep a record of their server file id) should be provided with Message_NewSharedFile.

Related messages
Message_ReadyToSendShares, Message_SendSharesStandBy, Message_OldShares

Message_FileTransfer
(&A)

Request from the server to transfer a file
Message
TypeNameContents
BlockFILE_IDIdentifier for file transfer
ByteCONNECTConnection type :
ValueMeaning
0Listen for connection
1Connect to remote machine
ByteDIRECTIONConnection direction :
ValueMeaning
0Send file to remote host
1Receive file from remote host
StringIPIP to connect to/mask to accept from
IntegerPORTPort to connect on/listen on
IntegerLOCAL_IDClient identifier number
StringFILENAMESuggested filename to transfer as
IntegerFILESIZESize of file being transferred
Source
Server
Use

This message is sent by the Server to request that the Client begin a file transfer. If the file does not exist, the client should

Related messages
Message_FileTransferState, Message_StopFileTransfer

Message_StopFileTransfer
(&B)

Sent to stop a file transfer
Message
TypeNameContents
BlockFILE_IDServer file ID
Source
Server
Use

This message is sent by the Server to terminate a current file transfer.

Related messages
Message_FileTransferState, Message_FileTransfer

Message_NewShareReply
(&D)

Provides the association of a shared file to the server identifier
Message
TypeNameContents
IntegerLOCAL_IDClient identifier number
StringFILE_SETServer file set
IntegerFILE_IDServer file ID
IntegerSONG_IDServer song ID
IntegerFILESIZESize of file
Source
Server
Use

This message is sent by the Server to inform the client of the server identifer.

Related messages
Message_NewSharedFile

Message_LoginError
(&E)

Informs the Client that there was a problem with their login
Message
TypeNameContents
IntegerERROR TYPEError type :
ValueMeaning
1Bad login/password
2Bad client version
3Logged in elsewhere - another client has just logged in with your details
4Gold account has expired
5Account is not Gold
otherUnknown
Source
Server
Use

This message is sent by the Server to inform the client that there was a problem with its login, or current connection to the Server.

Related messages
Message_Login 0.606W, Message_Login 0.608W

Message_PlayFile
(&F)

Request that the client begin playing a track
Message
TypeNameContents
IntegerLOCAL_IDClient identifier number
IntegerSONG_IDServer song ID
IntegerOPERATIONPlay operation (usually 1)
Source
Server
Use

This message appears to be sent by the Server to request that the Client start playing the file specified.

Related messages
Message_PlaySongList

Message_AccountExistence
(&1F)

Check account existence
Message
TypeNameContents
StringSATELLITE_VERSIONSatellite version number (use 0.606W)
StringLOGINLogin name
StringPASSWORDPassword
Source
Client
Use

This message is sent by the Client to query the Server about the existence of an account. The client does not have to be logged in for this message to be used

Related messages
Message_AccountExistenceReply

Message_OldShares
(&20)

Notify Server of the return of a shared file
Message
TypeNameContents
IntegerLOCAL_IDClient identifier number
StringFILE_SETServer file set
IntegerFILE_IDServer file ID
IntegerSONG_IDServer song ID
IntegerFILESIZESize of file
WordBITRATEBit rate in KB/s
IntegerLASTMODDATELast modified date, in seconds past Midnight, 1st Jan 1970
Source
Client
Use

This message is sent by the Client to inform the server of the reappearance of a file which had previously been shared and had received server identifiers.

Related messages
Message_SendShares

Message_NewSharedFile
(&21)

Notify Server of a new shared file
Message
TypeNameContents
WordUNKNOWNUnknown value (use 0)
IntegerLOCAL_IDClient identifier number
StringFILENAMELocal filename
StringFOLDERLocal folder name
IntegerFILESIZESize of file
WordBITRATEBit rate in KB/s
IntegerSECLENGTHLength of the file in seconds
IntegerLASTMODDATELast modified date, in seconds past Midnight, 1st Jan 1970 UTC
ByteFLAG_ID3v1Flag marker for ID3v1 data following :
ValueMeaning
0ID3v1 data not present
1ID3v1 data present
StringID3v1_TITLEID3v1 song title field
StringID3v1_ARTISTID3v1 artist field
StringID3v1_ALBUMID3v1 album field
ByteFLAG_ID3v2Flag marker for ID3v2 data following :
ValueMeaning
0ID3v2 data not present
1ID3v2 data present
StringID3v2_TITLEID3v2 song title field (TIT2/TT2)
StringID3v2_ARTISTID3v2 artist field (TPE1/TP1)
StringID3v2_ALBUMID3v2 album field (TALB/TAL)
WordID3v2_TRACKID3v2 track number field (TRCK/TRK)
StringID3v2_TAGAudioGalaxy tag (XAG1/XAG)
Source
Client
Use

This message is sent by the Client to inform the Server of the existence of shared files which were not previously known to the Server.

Related messages
Message_SendShares

Message_DeleteReply
(&22)

Notify Server that a requested delete operation has been processed
Message
TypeNameContents
BlockFILE_IDServer file identifier
ByteSTATEState of the delete :
ValueMeaning
0File was not deleted
1File was deleted
Source
Client
Use

This message is sent by the Client to inform the server that it received and processed the delete operation. This message is a reply to Message_DeleteRequest.

Related messages
Message_DeleteRequest

Message_NewAccount
(&23)

Create new account
Message
TypeNameContents
StringSATELLITE_VERSIONClient version (use 0.606W)
StringLOGINLogin user name (max 23 characters)
StringEMAILEmail address
StringAGEAge
StringSEXSex
StringCITYCity
StringSTATEState
StringZIPZip code
StringCOUNTRYCountry
StringHOW HEARDHow you heard about AudioGalaxy
IntegerUNKNOWNUnknown value (use 0)
Source
Client
Use

This message is sent by the Client to request the creation of an account.

Related messages
Message_NewAccountReply

Message_MagicRequest
(&24)

Clients initial message asking for a magic prefix
Message
No additional data
Source
Client
Use

This message is sent by the Client immediately after it connects to request an magic value to prefix the password for MD5 hashing.

Related messages
Message_Login 0.608W, Message_MagicResponse

Message_NewAccountReply
(&32)

Create account status
Message
TypeNameContents
IntegerRESPONSEResponse type for the account creation :
ValueMeaning
1Successful account creation
2Email address already in use
4User name already in use
6Username and Email address already in use
Source
Server
Use

This message is sent by the Server to inform you whether the creation of the account succeeded.

Related messages
Message_NewAccount

Message_AccountExistenceReply
(&33)

Reply giving the state of an account
Message
TypeNameContents
IntegerRESPONSEResponse type for the account existence check :
ValueMeaning
1Successful - account exists
2No such login or password
Source
Server
Use

This message is sent by the Server to inform you about the existence (or not) of an account queried with Message_AccountExistence.

Related messages
Message_AccountExistence

Message_DeleteRequest
(&34)

Request that the client delete a file
Message
TypeNameContents
BlockFILE_IDServer file identifier
StringFILENAMEFilename
Source
Server
Use

This message is sent by the Server to request that it delete the file referenced in the message. When the deletion has been processed, the Client should send message Message_DeleteReply.

Related messages
Message_DeleteReply

Message_PlaySongList
(&35)

Request that the client begin playing, or queue a track(s)
Message
TypeNameContents
IntegerOPERATIONPlay operation (usually 1)
IntegerCOUNTCount of songs to play/queue
IntegerLOCAL_IDLocal file identifier
IntegerUNKNOWNUnknown value (?)
Source
Server
Use

This message appears to be sent by the Server to request that the Client start playing, or queue the file or files specified. The local file identifier and the unknown value are repeated COUNT times.

Related messages
Message_PlayFile

Message_MagicResponse
(&37)

Reply to 0.608W protocol magic request
Message
TypeNameContents
StringPREFIXMagic MD5 prefix
Source
Server
Use

This message is sent by the Server to inform it of the magic prefix to use with the password to generate hashes. This message is only applicable to the protocol 0.608W. The client will, after this message, send the login message with the appropriate hash.

Related messages
Message_Login 0.608W, Message_MagicRequest

Message_ActivateGo
(&38)

Activate the 'go' button on the client
Message
TypeNameContents
StringLOGIN_STRINGString to pass to servers for login
Source
Server
Use

This message is sent by the Server to inform it that the 'Go' button should be activated (unfaded). This message is only applicable to the protocol 0.608W.

LOGIN_STRING is a string which may be used with the AudioGalaxy servers to login. Usually it is appended to 'http://www.audiogalaxy.com/serverlogin?' to cause the client to log in and display their home page on the AudioGalaxy servers.

The current format of this string is : cli=<userid>g<magic-hash>g<time>

Where:

ValueMeaning
useridHexadecimal version of the users id number
magic-hashMD5 hash as sent to the server on login
timeSome time value, believed to be the server start, or server build, time measured in centi-seconds since midnight 1st January 1970.
Related APIs
None