The Hotline Network Protocol – Version 1.9

Property of Hotsprings Inc. Publicly licensed under the GPL

Table of Contents

• Protocol Overview
• Session Initialization
• Transactions
• Transaction Types
• Transaction Descriptions
• Flattened File Object
• Transaction Fields
• Access Privileges
• Download Folder Actions
• Transaction Sequences
• Tracker Interface
• HTTP Tunneling
• Global Server

Licensing

The Hotline Protocol is the property of Hotsprings Inc. It is licensed to you under the GPL, or a commercial license negotiated with Hotsprings Inc. If you do not have a commercial license, then this protocol is automatically GPL.

For most developers, the GPL is the best option. Contrary to conventional wisdom, there is no prohibition in the GPL to charging money for a GPL'd application. The GPL is about free as in speech, not free as in beer.

If you want to use the protocol to develop a closed source application, you can do so by contacting Hotsprings for a commercial license. Possession of a commercial license allows for conventional commercial development.

Protocol Overview

Hotline client is an application executing on the user's computer, and providing user interface for end-user services (chat, messaging, file services and other). Hotline server provides services and facilitates communication between all clients that are currently connected to it. Tracker application stores the list of servers that register with it, and provides that list to clients that request it. All these applications use TCP/IP for communication.

To be able to connect to the specific server, IP address and port number must be provided to the client application. If client receives server's address from a tracker, the tracker will provide the client with complete address. Otherwise, the user of Hotline client software must manually set this address. IP port number, set in the Hotline client for a specific server, is called base port number. Additional port numbers utilized by the network protocol are determined by using this base port number:

Note: Numeric data transmitted over the wire is always in network byte order (big-endian).

Session Initialization

After establishing TCP connection, both client and server start the handshake process in order to confirm that each of them comply with requirements of the other. The information provided in this initial data exchange identifies protocols, and their versions, used in the communication. In the case where, after inspection, the capabilities of one of the subjects do not comply with the requirements of the other, the connection is dropped.

Client Request

Server Reply

In the case of an error, client and server close the connection.

Transactions

After the initial handshake, client and server communicate over the connection by sending and receiving transactions. Every transaction contains description (request) and/or status (reply) of the operation that is performed, and parameters used for that specific operation.

Transaction Header

Parameter List Header

Parameter Structure

Every field data format is based on the field type. Currently, there are only 3 predefined field data types: integer, string and binary.

Transaction Types (with Type ID)

This is the list of all transactions in the current version of Hotline software:

Related Transaction Groups

User Login and Management

Chat Transactions

Messaging Transactions

Transaction Description

Transaction types are described using the following format:

• Constant: Constant identifier used in the old version of the application
• Access: Specifies access privilege required to perform the transaction
• Initiator: Specifies transaction initiator (client or server)
• Fields used in the request: List of fields sent by the transaction initiator
• Fields used in the reply: List of fields sent back to the transaction initiator
• Reply is not sent: Receiver of transaction is not sending reply
• Reply is not expected: Sender of transaction is not expecting reply

Error (100)

• Constant: myTran_Error
• Initiator: None (?)

Get Messages (101)

• Constant: myTran_GetMsgs
• Initiator: Client

Fields used in the request: None

Fields used in the reply:

New Message (102)

• Constant: myTran_NewMsg
• Initiator: Server

Fields used in the request:

Reply is not sent.

Old Post News (103)

• Constant: myTran_OldPostNews
• Access: News Post Article (21)
• Initiator: Client

Fields used in the request:

Fields used in the reply: None

Server Message (104)

• Constant: myTran_ServerMsg
• Initiator: Server

Receive a message from the user on the current server, server's administrator, or server software itself.

Fields used in the request:

If User ID (103) field is not sent, receiver assumes that sender uses the following fields:

Reply is not sent.

Send Chat (105)

• Constant: myTran_ChatSend
• Access: Send Chat (10)
• Initiator: Client

Send a chat message to the chat.

Fields used in the request:

Reply is not expected.

Chat Message (106)

• Constant: myTran_ChatMsg
• Initiator: Server

Receive a chat message from the chat.

Fields used in the request:

If Chat ID is not available, the Data field contains:

Reply is not sent.

Login (107)

• Constant: myTran_Login
• Initiator: Client

Start login sequence with the server (see Transaction Sequences).

Fields used in the request:

Fields used in the reply:

If Version is >= 151, additional fields are included:

If server version is < 151, client sends Set Client User Info (304) transaction with only User Name (102) and User Icon ID (104) fields used, and does not expect a reply. It does not expect agreement to be received (109). Subsequently, it sends Get User Name List (300) request, followed by Get File Name List (200) or Get News Category Name List (370), depending on user preferences. After that, a banner is requested from HTTP server.

Send Instant Message (108)

• Constant: myTran_SendInstantMsg
• Initiator: Client

Send instant message to the user on the current server.

Fields used in the request:

Fields used in the reply: None

Show Agreement (109)

• Constant: myTran_ShowAgreement
• Initiator: Server

Receive agreement that will be presented to the user of the client application. This transaction is part of the login sequence.

Fields used in the request:

Reply is not sent.

Disconnect User (110)

• Constant: myTran_DisconnectUser
• Access: Disconnect User (22)
• Initiator: Client

Disconnect user from the current server.

Fields used in the request:

Fields used in the reply: None

Disconnect Message (111)

• Constant: myTran_DisconnectMsg
• Initiator: Server

Receive disconnect message from the server. Upon receiving this transaction, client should close the connection with server.

Fields used in the request:

Reply is not sent.

Invite New Chat (112)

• Constant: myTran_InviteNewChat
• Initiator: Client

Invite users to the new chat.

Fields used in the request:

Fields used in the reply:

Invite To Chat (113)

• Constant: myTran_InviteToChat
• Initiator: Client

Invite user to the existing chat.

Fields used in the request:

Reply is not expected.

The server can also be an initiator of this transaction.

Initiator: Server

Fields used in the request:

Reply is not sent.

When client receives this message from the server with version < 151, and client has automatic response or reject chat flag set, Reject Chat Invite (114) transaction is sent back to the server.

Reject Chat Invite (114)

• Constant: myTran_RejectChatInvite
• Initiator: Client

Reject invitation to join the chat.

Fields used in the request:

Reply is not expected.

Join Chat (115)

• Constant: myTran_JoinChat
• Initiator: Client

Join the chat.

Fields used in the request:

Fields used in the reply:

Leave Chat (116)

• Constant: myTran_LeaveChat
• Initiator: Client

Leave the chat.

Fields used in the request:

Reply is not expected.

Notify Chat Change User (117)

• Constant: myTran_NotifyChatChangeUser
• Initiator: Server

Notify the user of the chat that the information for some another user changed, or that a new user just joined the chat. This information should be added to (user joined the chat), or updated (user changed its info) in the chat user list.

Fields used in the request:

Reply is not sent.

In the Hotline implementation v1.8x, this transaction is in fact used only when the user joins the chat. The user information update done by Notify Change User (301) transaction is also applied to any chat rooms on the clients receiving the update.

Notify Chat Delete User (118)

• Constant: myTran_NotifyChatDeleteUser
• Initiator: Server

Notify the user of the chat that a user left that chat. The client should update the chat user list.

Fields used in the request:

Reply is not sent.

Notify Chat Subject (119)

• Constant: myTran_NotifyChatSubject
• Initiator: Server

Notify the user of the chat of the chat subject.

Fields used in the request:

Reply is not sent.

Set Chat Subject (120)

• Constant: myTran_SetChatSubject
• Initiator: Client

Set chat subject for the chat.

Fields used in the request:

Reply is not expected.

Agreed (121)

• Constant: myTran_Agreed
• Initiator: Client

Notify the server that the user accepted the server agreement.

Fields used in the request:

Fields used in the reply: None

After receiving server's acknowledgement, the client sends Get User Name List (300) request, followed by Get File Name List (200) or Get News Category Name List (370), depending on user preferences.

Server Banner (122)

• Constant: myTran_ServerBanner
• Initiator: Server

Notify the client that a new banner should be displayed.

Fields used in the request:

Reply is not sent.

If banner type is URL, it is requested from that URL. Otherwise, the banner is requested from the server by Download Banner (212) request.

This transaction uses only literal value constants in the banner type field (e.g., 'URL ', 'JPEG' or other).

Get File Name List (200)

• Constant: myTran_GetFileNameList
• Initiator: Client

Get the list of file names from the specified folder.

Fields used in the request:

Fields used in the reply:

Download File (202)

• Constant: myTran_DownloadFile
• Access: Download File (2)
• Initiator: Client

Download the file from the specified path on the server.

Fields used in the request:

Fields used in the reply:

After receiving reply from the server, the client opens TCP (or HTTP) connection to base port + 1 (HTTP uses base port + 3). On successful establishment, client sends the following record using the new connection:

After this, server sends the flattened file object (see Flattened File Object) using this new TCP connection.

Upload File (203)

• Constant: myTran_UploadFile
• Access: Upload File (1)
• Initiator: Client

Upload a file to the specified path on the server.

Fields used in the request:

Fields used in the reply:

After receiving reply from the server, the client opens TCP (or HTTP) connection to base port + 1 (HTTP uses base port + 3). On successful establishment, client sends the following record using the new connection:

After this, client sends the flattened file object (see Flattened File Object) using this new TCP connection.

Delete File (204)

• Constant: myTran_DeleteFile
• Access: Delete File (0) or Delete Folder (6)
• Initiator: Client

Delete the specific file from the server.

Fields used in the request:

Fields used in the reply: None

New Folder (205)

• Constant: myTran_NewFolder
• Access: Create Folder (5)
• Initiator: Client

Create a new folder on the server.

Fields used in the request:

Fields used in the reply: None

Get File Info (206)

• Constant: myTran_GetFileInfo
• Initiator: Client

Request file information from the server.

Fields used in the request:

Fields used in the reply:

Set File Info (207)

• Constant: myTran_SetFileInfo
• Access: Set File Comment (28) or Set Folder Comment (29)
• Initiator: Client

Set information for the specified file on the server.

Fields used in the request:

Fields used in the reply: None

Move File (208)

• Constant: myTran_MoveFile
• Initiator: Client

Move the file from one folder to another on the same server.

Fields used in the request:

Fields used in the reply: None

Make File Alias (209)

• Constant: myTran_MakeFileAlias
• Access: Make Alias (31)
• Initiator: Client

Make the file alias using the specified path.

Fields used in the request:

Fields used in the reply: None

Download Folder (210)

• Constant: myTran_DownloadFldr
• Access: Download File (2)
• Initiator: Client

Download all files from the specified folder and its subfolders on the server.

Fields used in the request:

Fields used in the reply:

After receiving reply from the server, the client opens TCP (or HTTP) connection to base port + 1 (HTTP uses base port + 3). On successful establishment, client sends the following record using the new connection:

For every item in the folder, server replies with:

Header data contains:

After receiving this header, client can reply in 3 ways:

(1) If type is an odd number (unknown type?), or file download for the current file is completed:

This notifies the server to send next item header.

(2) If download of a file is to be resumed:

(3) Otherwise, file download is requested by:

When download is requested (case 2 or 3), server replies with:

After every file download, client could request next file:

Download Info (211)

• Constant: myTran_DownloadInfo
• Initiator: Server

Notify the client that all download slots on the server are full.

Fields used in the request:

Reply is not sent.

Download Banner (212)

• Constant: myTran_DownloadBanner
• Initiator: Client

Request a new banner from the server.

Fields used in the request: None

Fields used in the reply:

After receiving reply from the server, the client opens TCP (or HTTP) connection to base port + 1 (HTTP uses base port + 3). On successful establishment, client sends the following record using the new connection:

After this, server sends the file content using this new TCP connection.

Upload Folder (213)

• Constant: myTran_UploadFldr
• Access: Upload File (1)
• Initiator: Client

Upload all files from the local folder and its subfolders, to the specified path on the server.

Fields used in the request:

Fields used in the reply:

After receiving reply from the server, the client opens TCP (or HTTP) connection to base port + 1 (HTTP uses base port + 3). On successful establishment, client sends the following record using the new connection:

Server can reply with:

After which client sends:

File name path contains:

After every file, server can send one of 3 requests:

(1) Request next file:

(2) Resume a file download procedure:

(3) Request a file download:

Client replies to download requests with:

After this client sends the flattened file object (see Flattened File Object).

Get User Name List (300)

• Constant: myTran_GetUserNameList
• Initiator: Client

Request the list of all users connected to the current server.

Fields used in the request: None

Fields used in the reply:

Notify Change User (301)

• Constant: myTran_NotifyChangeUser
• Initiator: Server

Notify the user that the information for some another user changed, or that a new user just connected to the server. This information is to be added to (user joined), or updated (user changed its info) in the existing user list.

Fields used in the request:

Reply is not sent.

In the Hotline implementation v1.8x, this transaction is also applied to any chat rooms on the clients receiving the update.

Notify Delete User (302)

• Constant: myTran_NotifyDeleteUser
• Initiator: Server

Notify the user that some another user disconnected from the server. The client should update the existing user list.

Fields used in the request:

Reply is not sent.

Get Client Info Text (303)

• Constant: myTran_GetClientInfoText
• Access: Get Client Info (24)
• Initiator: Client

Request user information for the specific user.

Fields used in the request:

Fields used in the reply:

Set Client User Info (304)

• Constant: myTran_SetClientUserInfo
• Initiator: Client

Set user preferences on the server.

Fields used in the request:

Reply is not expected.

New User (350)

• Constant: myTran_NewUser
• Initiator: Client

Add a new user to the server's list of allowed users.

Fields used in the request:

Fields used in the reply: None

Delete User (351)

• Constant: myTran_DeleteUser
• Initiator: Client

Delete the specific user from the server's list of allowed users.

Fields used in the request:

Fields used in the reply: None

Get User (352)

• Constant: myTran_GetUser
• Initiator: Client

Request the information for the specific user from the server's list of allowed users.

Fields used in the request:

Fields used in the reply:

Set User (353)

• Constant: myTran_SetUser
• Initiator: Client

Set the information for the specific user in the server's list of allowed users.

Fields used in the request:

Fields used in the reply: None

User Access (354)

• Constant: myTran_UserAccess
• Initiator: Server

Set access privileges for the current user.

Fields used in the request:

Reply is not sent.

User Broadcast (355)

• Constant: myTran_UserBroadcast
• Access: Broadcast (32)
• Initiator: Client

Broadcast the message to all users on the server.

Fields used in the request:

Fields used in the reply: None

The server can also be an initiator of this transaction.

Initiator: Server

Fields used in the request:

Reply is not sent.

Get News Category Name List (370)

• Constant: myTran_GetNewsCatNameList
• Initiator: Client

Get the list of category names at the specified news path.

Fields used in the request:

Fields used in the reply:

If version of client/server is 1.5 (prior to April 15, 1999?), instead of the previous reply, the following is sent:

Get News Article Name List (371)

• Constant: myTran_GetNewsArtNameList
• Initiator: Client

Get the list of article names at the specified news path.

Fields used in the request:

Fields used in the reply:

Delete News Item (380)

• Constant: myTran_DelNewsItem
• Access: News Delete Folder (37) or News Delete Category (35)
• Initiator: Client

Delete an existing news item from the server.

Fields used in the request:

Fields used in the reply: None

New News Folder (381)

• Constant: myTran_NewNewsFldr
• Access: News Create Folder (36)
• Initiator: Client

Create new news folder on the server.

Fields used in the request:

Fields used in the reply: None

New News Category (382)

• Constant: myTran_NewNewsCat
• Access: News Create Category (34)
• Initiator: Client

Create new news category on the server.

Fields used in the request:

Fields used in the reply: None

Get News Article Data (400)

• Constant: myTran_GetNewsArtData
• Access: News Read Article (20)
• Initiator: Client

Request information about the specific news article.

Fields used in the request:

Fields used in the reply:

Post News Article (410)

• Constant: myTran_PostNewsArt
• Access: News Post Article (21)
• Initiator: Client

Post new news article on the server.

Fields used in the request:

Fields used in the reply: None

Delete News Article (411)

• Constant: myTran_DelNewsArt
• Access: News Delete Article (33)
• Initiator: Client

Delete the specific news article.

Fields used in the request:

Fields used in the reply: None

Flattened File Object

Transactions 202 (Download File), 203 (Upload File), 210 (Download Folder) and 213 (Upload Folder) format the file object in the following way:

Flat File Header

Flat File Information Fork Header

Flat File Information Fork

Flat File Data Fork Header

Transaction Fields

There are 3 predefined field data types: integer, string and binary. If field data does not fit in the first two categories, it is sent as binary data and interpreted by the receiving machine. Some of the binary fields are currently used as strings. All integer fields are treated as unsigned, and can be sent as 16 or 32-bit numbers. This is determined by evaluation of the number itself. Namely, if integer can be represented using only 2 bytes, it is sent as such. In the case when the number is greater than 2^16, it's sent as 32-bit number. String fields currently use 8-bit ASCII character set.

Error Text (100)

• Constant: myField_ErrorText

Data (101)

• Constant: myField_Data
• Type: Binary

User Name (102)

• Constant: myField_UserName
• Type: String

User ID (103)

• Constant: myField_UserID
• Type: Integer

User Icon ID (104)

• Constant: myField_UserIconID
• Type: Integer

User Login (105)

• Constant: myField_UserLogin
• Type: String

User Password (106)

• Constant: myField_UserPassword
• Type: String

Reference Number (107)

• Constant: myField_RefNum
• Type: Integer

Transfer Size (108)

• Constant: myField_TransferSize
• Type: Integer

Chat Options (109)

• Constant: myField_ChatOptions
• Type: Integer

User Access (110)

• Constant: myField_UserAccess
• Type: Binary

This field is represented as 64-bit bitmap. The specific bit meaning is described in the Access Privileges section of this document.

User Alias (111)

• Constant: myField_UserAlias

User Flags (112)

• Constant: myField_UserFlags
• Type: Integer

User flags field is a bitmap with the following values:

Options (113)

• Constant: myField_Options
• Type: Integer

Chat ID (114)

• Constant: myField_ChatID
• Type: Integer

Chat Subject (115)

• Constant: myField_ChatSubject
• Type: String

Waiting Count (116)

• Constant: myField_WaitingCount
• Type: Integer

Server Agreement (150)

• Constant: myField_ServerAgreement

Server Banner (151)

• Constant: myField_ServerBanner
• Type: Binary

Server Banner Type (152)

• Constant: myField_ServerBannerType
• Type: Integer

This field can have one of the following values:

Server Banner URL (153)

• Constant: myField_ServerBannerUrl
• Type: Binary

No Server Agreement (154)

• Constant: myField_NoServerAgreement
• Type: Integer

The value of this field is 1 if there is no agreement to be sent.

Version (160)

• Constant: myField_Vers
• Type: Integer

Community Banner ID (161)

• Constant: myField_CommunityBannerID
• Type: Integer

Server Name (162)

• Constant: myField_ServerName
• Type: Binary

File Name with Info (200)

• Constant: myField_FileNameWithInfo
• Type: Binary

File name with info field content is presented in this structure:

File Name (201)

• Constant: myField_FileName
• Type: String

File Path (202)

• Constant: myField_FilePath
• Type: Binary

File Resume Data (203)

• Constant: myField_FileResumeData
• Type: Binary

File resume data field content is presented in this structure:

Fork info list contains one or more records with the following structure:

File Transfer Options (204)

• Constant: myField_FileXferOptions
• Type: Integer

File Type String (205)

• Constant: myField_FileTypeString
• Type: String

File Creator String (206)

• Constant: myField_FileCreatorString
• Type: String

File Size (207)

• Constant: myField_FileSize
• Type: Integer

File Create Date (208)

• Constant: myField_FileCreateDate
• Type: Binary

File Modify Date (209)

• Constant: myField_FileModifyDate
• Type: Binary

File Comment (210)

• Constant: myField_FileComment
• Type: String

File New Name (211)

• Constant: myField_FileNewName
• Type: String

File New Path (212)

• Constant: myField_FileNewPath
• Type: Binary

File Type (213)

• Constant: myField_FileType
• Type: Binary

Quoting Message (214)

• Constant: myField_QuotingMsg
• Type: Binary

Automatic Response (215)

• Constant: myField_AutomaticResponse
• Type: String

Folder Item Count (220)

• Constant: myField_FldrItemCount
• Type: Integer

User Name with Info (300)

• Constant: myField_UserNameWithInfo
• Type: Binary

News Category GUID (319)

• Constant: myField_NewsCatGUID

News Category List Data (320)

• Constant: myField_NewsCatListData
• Type: Binary

News category list data field contains this structure (for client/server version 1.5):

News Article List Data (321)

• Constant: myField_NewsArtListData
• Type: Binary

News article list data field contains this structure:

List of articles contains:

Flavor list has the following structure:

News Category Name (322)

• Constant: myField_NewsCatName
• Type: String

News Category List Data 1.5 (323)

• Constant: myField_NewsCatListData15
• Type: Binary

News category list data field contains this structure:

If type value indicates a bundle, what follows the type is:

In the case of a category type, type value is followed by:

News Path (325)

• Constant: myField_NewsPath
• Type: Binary

News Article ID (326)

• Constant: myField_NewsArtID
• Type: Integer

News Article Data Flavor (327)

• Constant: myField_NewsArtDataFlav
• Type: String

News Article Title (328)

• Constant: myField_NewsArtTitle
• Type: String

News Article Poster (329)

• Constant: myField_NewsArtPoster
• Type: String

News Article Date (330)

• Constant: myField_NewsArtDate
• Type: Binary

News Article – Previous Article (331)

• Constant: myField_NewsArtPrevArt
• Type: Integer

News Article – Next Article (332)

• Constant: myField_NewsArtNextArt
• Type: Integer

News Article Data (333)

• Constant: myField_NewsArtData
• Type: Binary

News Article Flags (334)

• Constant: myField_NewsArtFlags
• Type: Integer

News Article – Parent Article (335)

• Constant: myField_NewsArtParentArt
• Type: Integer

News Article – First Child Article (336)

• Constant: myField_NewsArt1stChildArt
• Type: Integer

News Article – Recursive Delete (337)

• Constant: myField_NewsArtRecurseDel
• Type: Integer

Access Privileges

The following is the list of access privileges currently employed by the application. There are 3 types of access privileges: general, folder and bundle. Folder privileges are set per folder. Bundle access is related to the logical grouping of the information. General access privileges are used to set privileges for a user.

Download Folder Actions

These values are used to control folder upload/download process. When an application receives folder upload request, it is presented with the first applicable file. In the reply, application will specify an action to be performed:

Send File (1)

• Constant: dlFldrAction_SendFile

Send file action starts the download of the file specified in the request. An additional TCP connection is opened to transfer this file, according to the protocol described in Download Folder (210) and Upload Folder (213) transaction.

Resume File Download (2)

• Constant: dlFldrAction_ResumeFile

This action is similar to the send file action. It also starts the download, while providing the starting position in the file. An additional TCP connection is opened to transfer this file, in the same manner as for send file action.

Next File (3)

• Constant: dlFldrAction_NextFile

Next file action notifies the receiver to send the name of the next file in a folder. Download of the current file is not initiated.

Transaction Sequences

Hotline client contains few predefined transaction sequences in its current implementation.

Login

After sending Login transaction (107), server will reply with Show Agreement (109). If user accepts the agreement, Hotline client sends Agreed transaction (121), followed by Get User Name List (300). Next, a Get File Name List (200) or Get News Category Name List (370) transaction is sent, depending on user preferences.

If server version is < 151, server will not send Show Agreement reply. In this case, after Login (107) transaction is sent, client sends Set Client User Info (304) transaction with only User Name (102) and User Icon ID (104) fields used, and does not expect a reply. Subsequently, it sends Get User Name List (300) request, followed by Get File Name List (200) or Get News Category Name List (370), depending on user preferences. After that, a banner is requested from HTTP server.

Invite To Chat

When client receives Invite To Chat (113) transaction from the server with version < 151, and client has automatic response or reject chat flag set, Reject Chat Invite (114) transaction is sent back to the server.

Tracker Interface

All string values use 8-bit ASCII character set encoding.

Client Interface with Tracker

After establishing a connection with tracker, the following information is sent:

When version number is 2, request also includes additional data:

Reply received from the tracker starts with a header:

Server information header follows:

A record in the server list has the following structure:

If the number of servers in the server list is less than number of servers specified in the server information header, client will expect an additional server information, starting with the new server information header. The field containing number of servers in the new header should have the same value as the previous one.

When a client is connected to the tracker over the HTTP tunneling protocol, the client does not send any request to the tracker, although it still expects a properly formatted reply. In this case establishing a connection to the tracker indicates a request for the server list.

Server Interface with Tracker

Server sets up UDP port that is used to periodically send the following information to the trackers:

In the case when old (?) tracker is used, the additional information is formatted as follows:

For a new version of the tracker:

HTTP Tunneling

When client is unable to communicate with the server using plain TCP connection, HTTP tunneling can be utilized to access the Hotline server over an HTTP proxy. To accomplish this, the client creates two connections to the server. One would be used for sending, and other for receiving data. After these connections are open, the client begins transmitting standard HTTP requests. If HTTP proxy terminates connection while that connection is still in use, the client recreates them, and interrupted requests are resent.

HTTP Requests

HTTP POST request is sent over sending, while GET request is sent over receiving connection.

POST request:

POST <address> HTTP/1.0\r\n
        Proxy-Connection: Keep-Alive\r\n
        Pragma: no-cache\r\n
        Host: <host>\r\n
        Content-Length: 999999999\r\n
        Content-Type: hotline/protocol\r\n
        \r\n
        

Server reply to POST (when connection is about to be closed):

HTTP/1.0 302 Found\r\n
        Connection: close\r\n
        Content-Length: 8\r\n
        Content-Type: hotline/protocol\r\n
        \r\n
        

Next 8 bytes are filled with 0 to indicate termination of a connection.

GET request:

GET <address> HTTP/1.0\r\n
        Proxy-Connection: Keep-Alive\r\n
        Pragma: no-cache\r\n
        Host: <host>\r\n
        Accept: hotline/protocol\r\n
        \r\n
        

Server's immediate reply to GET:

HTTP/1.0 200 OK\r\n
        Proxy-Connection: Keep-Alive\r\n
        Content-Length: 999999999\r\n
        Content-Type: hotline/protocol\r\n
        \r\n
        

After this reply, server uses this connection to send data to the client.

Address used in these requests is standard URL address followed by the session ID, specified as the file in the root directory. Example:

http://tracker.com:5497/5555-5555-5555
        

Session ID is used in order to identify the client in the case of disconnect. Host name specified in the HTTP headers is in the form of standard domain name string, followed by the port number. Example:

tracker.com:5497
        

Data Header

Additional header precedes every transaction that is sent over these two connections:

Data content depends on the data code specified:

• Code 1 (http_Data): Transaction data as described in this specification (includes tracker protocol)
• Code 0: Notifies the remote end of a pending disconnect
• Code 2 (http_Padding): Padding data to keep the connection alive; data content is discarded

Global Server

1.1 Server Information

Hotline servers will be able to create an account on the global server by providing a unique server name (relatively short in size) and an access password. This information constitutes an account login information that will have to be provided in every subsequent access to the global server. At the time the account is created, the global server assigns the unique server ID to the server.

Global server will provide servers with the ability to store a predefined set of data fields:

1.2 Global Server Transactions

1.2.1 Server Login

• Initiator: Server

This transaction is used every time the server logins to the global server. It must be the first transaction sent to the global server.

Fields used in the request:

Fields used in the reply: None

If server indicates that it creates a new account, and account with identical ID already exists in the database, or if a new account cannot be created for any other reason, the global server indicates these conditions with the proper error code.

1.2.2 Update Server Information

• Initiator: Server

Update server information on the global server. All fields in this request are optional.

Fields used in the request:

Fields used in the reply: None

1.2.3 Delete Server Account

• Access: Administrator
• Initiator: Client

Delete server account from the database.

Fields used in the request:

Fields used in the reply: None

1.2.4 Rate Server

• Initiator: Client

Fields used in the request:

Fields used in the reply: None

1.2.5 Query Server Database

• Initiator: Client

Create a query for the server database. All fields in this request are optional. If client does not specify the search string, the list of all servers is returned.

Fields used in the request:

Fields used in the reply:

1.2.6 Get Server Information

• Initiator: Client

Get information about the specific server.

Fields used in the request:

Fields used in the reply:

This reference is published from the Mobius protocol documentation. Mobius is a cross-platform Hotline server — learn more.