Hotsprings Protocol
Protocol Overview
The Hotline client provides end-user services (chat, messaging, file services), while the server facilitates communication between connected clients. The Tracker application stores and provides lists of available servers. All communication occurs via TCP/IP.
Port Assignments
IP port number, set in the Hotline client for a specific server, is called the base port number. Additional ports are determined relative to this:
| Port | Usage |
|---|---|
| Base port | Regular transactions |
| Base port + 1 | Upload/download |
| Base port + 2 | HTTP tunneling (transactions) |
| Base port + 3 | HTTP tunneling (files) |
Note: Numeric data is always transmitted in network byte order (big-endian).
Session Initialization
Both parties perform a handshake (TRTP) to identify protocols and versions. If capabilities do not comply, the connection is dropped.
Client Request
| Description | Size | Data | Note |
|---|---|---|---|
| Protocol ID | 4 | 'TRTP' | 0x54525450 |
| Sub-protocol ID | 4 | User defined | |
| Version | 2 | 1 | Currently 1 |
| Sub-version | 2 | User defined |
Server Reply
| Description | Size | Data | Note |
|---|---|---|---|
| Protocol ID | 4 | 'TRTP' | |
| Error code | 4 | 0 = no error |
Transaction Structure
Communication consists of sending and receiving transactions composed of a header and a parameter list.
Transaction Header
| Description | Size | Data | Note |
|---|---|---|---|
| Flags | 1 | 0 | Reserved |
| Is reply | 1 | 0 or 1 | Request (0) or reply (1) |
| Type | 2 | Requested operation ID | |
| ID | 4 | Not 0 | Unique transaction ID |
| Error code | 4 | 0 = no error | |
| Total size | 4 | Total data size | |
| Data size | 4 | Size of this part |
Parameter List & Field Structure
Transactions contain a 2-byte field for the Number of parameters, followed by the parameters themselves:
- Field ID: 2 bytes
- Field size: 2 bytes
- Field data: Variable size (Integer, String, or Binary)
Transaction Types
| ID | Type | Initiator | Constant |
|---|---|---|---|
| 101 | Get messages | Client | myTran_GetMsgs |
| 102 | New message | Server | myTran_NewMsg |
| 105 | Send chat | Client | myTran_ChatSend |
| 106 | Chat message | Server | myTran_ChatMsg |
| 107 | Login | Client | myTran_Login |
| 108 | Send instant message | Client | myTran_SendInstantMsg |
| 110 | Disconnect user | Client | myTran_DisconnectUser |
| 115 | Join chat | Client | myTran_JoinChat |
| 200 | Get file name list | Client | myTran_GetFileNameList |
| 202 | Download file | Client | myTran_DownloadFile |
| 300 | Get user name list | Client | myTran_GetUserNameList |
Detailed Transaction Descriptions
Login (107)
Starts the login sequence with the server.
- Constant: myTran_Login
- Initiator: Client
Fields in Request:
| ID | Field Name | Note |
|---|---|---|
| 105 | User login | |
| 106 | User password | |
| 160 | Version | Currently 151 |
Fields in Reply:
| ID | Field Name | Note |
|---|---|---|
| 160 | Version | |
| 161 | Banner ID | If version >= 151 |
| 162 | Server name | If version >= 151 |
Send Chat (105)
Sends a message to the public chat.
- Constant: myTran_ChatSend
- Access: Send Chat (10)
- Initiator: Client
Fields in Request:
| ID | Field Name | Note |
|---|---|---|
| 101 | Data | Chat message string |
| 109 | Chat options | Optional - Normal (0) or Alternate (1) |
| 114 | Chat ID | Optional |
Flattened File Object (FILP)
Used in file transfers (Transactions 202, 203, 210, 213). It uses a fork-based structure:
Flat File Header
- Format: 'FILP' (0x46494C50)
- Version: 2 bytes (1)
- Fork Count: 2 bytes (Currently 2)
Information Fork (INFO)
Contains metadata:
- Platform: 'AMAC' (Mac) or 'MWIN' (Windows)
- Type/Creator: 4-byte signatures
- Create/Modify Dates: 8 bytes each
Data Fork (DATA)
Contains the actual file content.
Access Privileges
Represented as a 64-bit bitmap (Field 110).
| Bit | Name | Constant | Type |
|---|---|---|---|
| 0 | Delete File | myAcc_DeleteFile | folder |
| 1 | Upload File | myAcc_UploadFile | general |
| 2 | Download File | myAcc_DownloadFile | general |
| 9 | Read Chat | myAcc_ReadChat | general |
| 10 | Send Chat | myAcc_SendChat | general |
| 22 | Disconnect User | myAcc_DisconUser | general |
| 32 | Broadcast | myAcc_Broadcast | general |
Tracker Interface
Trackers facilitate server discovery.
Server List Record
| Description | Size | Note |
|---|---|---|
| IP address | 4 | |
| IP port number | 2 | |
| Number of users | 2 | |
| Name size/data | Var | Server Name |
| Desc size/data | Var | Server Description |
HTTP Tunneling
Used when TCP is blocked. Utilizes GET (receiving) and POST (sending) requests via a proxy.
MIME Type: hotline/protocol
Data Header:
- Code 0: Pending Disconnect
- Code 1: Standard Transaction Data
- Code 2: Keep-alive padding
Licensing
Licensed under the GPL by Hotsprings Inc. Contact Hotsprings for commercial (closed-source) licensing.
