Hotsprings Protocol: Difference between revisions

From Hotline Wiki

Lostarch (talk | contribs)
0 edits
Created page with "__TOC__ == 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: {|..."
 
Updating Hotsprings Protocol
 
Line 1: Line 1:
__TOC__
__TOC__
== Licensing ==
The Hotline Protocol is the property of '''Hotsprings Inc.''' and is licensed under the '''GPL'''. For closed-source development, a commercial license must be negotiated.


== Protocol Overview ==
== 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.
Hotline uses a client-server architecture facilitated by a Tracker application. All communication utilizes TCP/IP.


=== Port Assignments ===
=== 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:
The '''base port number''' is set manually. Related ports are derived as follows:
 
{| class="wikitable"
{| class="wikitable"
! Port !! Usage
! Port !! Usage
Line 16: Line 18:
| Base port + 2 || HTTP tunneling (transactions)
| Base port + 2 || HTTP tunneling (transactions)
|-
|-
| Base port + 3 || HTTP tunneling (files)
| Base port + 3 || HTTP tunneling (uploads/downloads)
|}
|}
 
'''Note:''' Numeric data is always in '''network byte order (big-endian)'''.
'''Note:''' Numeric data is always transmitted in '''network byte order (big-endian)'''.


== Session Initialization ==
== Session Initialization ==
Both parties perform a handshake (TRTP) to identify protocols and versions. If capabilities do not comply, the connection is dropped.
After TCP connection, a TRTP handshake occurs.


=== Client Request ===
=== Client Request ===
{| class="wikitable"
{| class="wikitable"
! Description !! Size !! Data !! Note
! Description !! Size (Bytes) !! Data !! Note
|-
|-
| Protocol ID || 4 || 'TRTP' || 0x54525450
| Protocol ID || 4 || 'TRTP' || 0x54525450
Line 39: Line 40:
=== Server Reply ===
=== Server Reply ===
{| class="wikitable"
{| class="wikitable"
! Description !! Size !! Data !! Note
! Description !! Size (Bytes) !! Data !! Note
|-
|-
| Protocol ID || 4 || 'TRTP' ||
| Protocol ID || 4 || 'TRTP' ||
Line 46: Line 47:
|}
|}


== Transaction Structure ==
== Transactions ==
Communication consists of sending and receiving transactions composed of a header and a parameter list.
Every transaction consists of a header followed by a parameter list.


=== Transaction Header ===
=== Transaction Header ===
{| class="wikitable"
{| class="wikitable"
! Description !! Size !! Data !! Note
! Description !! Size !! Note
|-
|-
| Flags || 1 || 0 || Reserved
| Flags || 1 || Reserved (0)
|-
|-
| Is reply || 1 || 0 or 1 || Request (0) or reply (1)
| Is reply || 1 || Request (0) or reply (1)
|-
|-
| Type || 2 || || Requested operation ID
| Type || 2 || Requested operation ID
|-
|-
| ID || 4 || Not 0 || Unique transaction ID
| ID || 4 || Unique ID (must be != 0)
|-
|-
| Error code || 4 || || 0 = no error
| Error code || 4 || 0 = no error
|-
|-
| Total size || 4 || || Total data size
| Total size || 4 || Total transaction data size
|-
|-
| Data size || 4 || || Size of this part
| Data size || 4 || Size of data in this part
|}
|}


=== Parameter List & Field Structure ===
=== Parameter Structure ===
Transactions contain a 2-byte field for the '''Number of parameters''', followed by the parameters themselves:
A transaction contains a 2-byte field for the '''Number of parameters''', followed by multiple structures:
* '''Field ID:''' 2 bytes
{| class="wikitable"
* '''Field size:''' 2 bytes
! Description !! Size !! Note
* '''Field data:''' Variable size (Integer, String, or Binary)
 
== Transaction Types ==
{| class="wikitable" style="width:100%"
! ID !! Type !! Initiator !! Constant
|-
| 101 || Get messages || Client || <nowiki>myTran_GetMsgs</nowiki>
|-
| 102 || New message || Server || <nowiki>myTran_NewMsg</nowiki>
|-
| 105 || Send chat || Client || <nowiki>myTran_ChatSend</nowiki>
|-
| 106 || Chat message || Server || <nowiki>myTran_ChatMsg</nowiki>
|-
| 107 || Login || Client || <nowiki>myTran_Login</nowiki>
|-
| 108 || Send instant message || Client || <nowiki>myTran_SendInstantMsg</nowiki>
|-
| 110 || Disconnect user || Client || <nowiki>myTran_DisconnectUser</nowiki>
|-
| 115 || Join chat || Client || <nowiki>myTran_JoinChat</nowiki>
|-
|-
| 200 || Get file name list || Client || <nowiki>myTran_GetFileNameList</nowiki>
| Field ID || 2 || Unique identifier
|-
|-
| 202 || Download file || Client || <nowiki>myTran_DownloadFile</nowiki>
| Field size || 2 || Data part size
|-
|-
| 300 || Get user name list || Client || <nowiki>myTran_GetUserNameList</nowiki>
| Field data || Var || Actual content
|}
|}


== Detailed Transaction Descriptions ==
== Transaction Descriptions ==


=== Login (107) ===
=== Login (107) ===
Starts the login sequence with the server.
* '''Constant:''' <nowiki>myTran_Login</nowiki>
* '''Constant:''' <nowiki>myTran_Login</nowiki>
* '''Initiator:''' Client
* '''Initiator:''' Client
 
'''Request Fields:'''
'''Fields in Request:'''
* 105: User login
{| class="wikitable"
* 106: User password
! ID !! Field Name !! Note
* 160: Version (Currently 151)
|-
'''Reply Fields:'''
| 105 || User login ||
* 160: Version
|-
* 161/162: Banner ID/Server Name (if Version >= 151)
| 106 || User password ||
|-
| 160 || Version || Currently 151
|}
 
'''Fields in Reply:'''
{| class="wikitable"
! ID !! Field Name !! Note
|-
| 160 || Version ||
|-
| 161 || Banner ID || If version >= 151
|-
| 162 || Server name || If version >= 151
|}


=== Send Chat (105) ===
=== Send Chat (105) ===
Sends a message to the public chat.
* '''Constant:''' <nowiki>myTran_ChatSend</nowiki>
* '''Access:''' Send Chat (10)
* '''Access:''' Send Chat (10)
* '''Initiator:''' Client
* '''Initiator:''' Client
'''Request Fields:'''
* 101: Chat message string
* 109: Chat options (Normal 0, Alternate 1)
* 114: Chat ID (Optional)


'''Fields in Request:'''
=== Disconnect User (110) ===
{| class="wikitable"
* '''Access:''' Disconnect User (22)
! ID !! Field Name !! Note
* '''Initiator:''' Client
|-
'''Request Fields:'''
| 101 || Data || Chat message string
* 103: User ID
|-
* 113: Options (Ban options)
| 109 || Chat options || Optional - Normal (0) or Alternate (1)
|-
| 114 || Chat ID || Optional
|}


== Flattened File Object (FILP) ==
== Flattened File Object (FILP) ==
Used in file transfers (Transactions 202, 203, 210, 213). It uses a fork-based structure:
Used for file/folder transfers (Trans 202, 203, 210, 213).


=== Flat File Header ===
=== Flat File Header ===
* '''Format:''' 'FILP' (0x46494C50)
* '''Format:''' 'FILP' (0x46494C50)
* '''Version:''' 2 bytes (1)
* '''Fork Count:''' 2 (Information Fork and Data Fork)
* '''Fork Count:''' 2 bytes (Currently 2)


=== Information Fork (INFO) ===
=== Information Fork (INFO) ===
Contains metadata:
* '''Platform:''' 'AMAC' or 'MWIN'
* '''Platform:''' 'AMAC' (Mac) or 'MWIN' (Windows)
* '''Metadata:''' Type signature, Creator signature, Create/Modify dates, Name.
* '''Type/Creator:''' 4-byte signatures
* '''Create/Modify Dates:''' 8 bytes each


=== Data Fork (DATA) ===
=== Data Fork (DATA) ===
Contains the actual file content.
* '''Data Size:''' 4 bytes
* '''Content:''' Actual file bytes.


== Access Privileges ==
== Transaction Fields ==
Represented as a 64-bit bitmap (Field 110).
Predefined types: '''Integer''', '''String''', and '''Binary'''.


{| class="wikitable"
{| class="wikitable"
! Bit !! Name !! Constant !! Type
! ID !! Constant !! Type !! Note
|-
| 101 || <nowiki>myField_Data</nowiki> || Binary || General data
|-
| 102 || <nowiki>myField_UserName</nowiki> || String ||
|-
|-
| 0 || Delete File || <nowiki>myAcc_DeleteFile</nowiki> || folder
| 103 || <nowiki>myField_UserID</nowiki> || Integer ||
|-
|-
| 1 || Upload File || <nowiki>myAcc_UploadFile</nowiki> || general
| 105 || <nowiki>myField_UserLogin</nowiki> || String ||
|-
|-
| 2 || Download File || <nowiki>myAcc_DownloadFile</nowiki> || general
| 106 || <nowiki>myField_UserPassword</nowiki> || String ||
|-
|-
| 9 || Read Chat || <nowiki>myAcc_ReadChat</nowiki> || general
| 110 || <nowiki>myField_UserAccess</nowiki> || Binary || 64-bit bitmap
|-
|-
| 10 || Send Chat || <nowiki>myAcc_SendChat</nowiki> || general
| 114 || <nowiki>myField_ChatID</nowiki> || Integer ||
|-
|-
| 22 || Disconnect User || <nowiki>myAcc_DisconUser</nowiki> || general
| 160 || <nowiki>myField_Vers</nowiki> || Integer || Protocol version
|-
|-
| 32 || Broadcast || <nowiki>myAcc_Broadcast</nowiki> || general
| 202 || <nowiki>myField_FilePath</nowiki> || Binary || File path structure
|}
|}


== Tracker Interface ==
== Access Privileges ==
Trackers facilitate server discovery.
Represented as a 64-bit bitmap in Field 110.


=== Server List Record ===
{| class="wikitable"
{| class="wikitable"
! Description !! Size !! Note
! Bit !! Name !! Constant !! Type
|-
| 0 || Delete File || <nowiki>myAcc_DeleteFile</nowiki> || folder
|-
|-
| IP address || 4 ||
| 1 || Upload File || <nowiki>myAcc_UploadFile</nowiki> || folder/general
|-
|-
| IP port number || 2 ||
| 9 || Read Chat || <nowiki>myAcc_ReadChat</nowiki> || general
|-
|-
| Number of users || 2 ||
| 10 || Send Chat || <nowiki>myAcc_SendChat</nowiki> || general
|-
|-
| Name size/data || Var || Server Name
| 22 || Disconnect User || <nowiki>myAcc_DisconUser</nowiki> || general
|-
|-
| Desc size/data || Var || Server Description
| 32 || Broadcast || <nowiki>myAcc_Broadcast</nowiki> || general
|}
|}
== Tracker Interface ==
=== Client to Tracker ===
'''Request:'''
* Magic Number: 'HTRK' (4 bytes)
* Version: 1 or 2 (2 bytes)
'''Record Structure:'''
* IP Address (4), Port (2), User Count (2), Name Size (1), Name (Var).


== HTTP Tunneling ==
== HTTP Tunneling ==
Used when TCP is blocked. Utilizes '''GET''' (receiving) and '''POST''' (sending) requests via a proxy.  
Uses POST for sending and GET for receiving.
* '''MIME:''' <code>hotline/protocol</code>
* '''Data Header:''' 4-byte Code (0=Disconnect, 1=Data, 2=Padding), 4-byte Size.


'''MIME Type:''' <code>hotline/protocol</code>
== Global Server ==
 
Servers register with a unique name and password to the Global Server to receive a '''Server ID'''.
'''Data Header:'''
=== Fields Stored ===
* '''Code 0:''' Pending Disconnect
* Server ID, Name, Password, Alias, Description, IP, Status Flags, User Count.
* '''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.


[[Category:Network Protocols]]
[[Category:Network Protocols]]
[[Category:Hotline]]
[[Category:Hotline]]

Latest revision as of 20:00, 3 March 2026

Licensing

The Hotline Protocol is the property of Hotsprings Inc. and is licensed under the GPL. For closed-source development, a commercial license must be negotiated.

Protocol Overview

Hotline uses a client-server architecture facilitated by a Tracker application. All communication utilizes TCP/IP.

Port Assignments

The base port number is set manually. Related ports are derived as follows:

Port Usage
Base port Regular transactions
Base port + 1 Upload/download
Base port + 2 HTTP tunneling (transactions)
Base port + 3 HTTP tunneling (uploads/downloads)

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

Session Initialization

After TCP connection, a TRTP handshake occurs.

Client Request

Description Size (Bytes) 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 (Bytes) Data Note
Protocol ID 4 'TRTP'
Error code 4 0 = no error

Transactions

Every transaction consists of a header followed by a parameter list.

Transaction Header

Description Size Note
Flags 1 Reserved (0)
Is reply 1 Request (0) or reply (1)
Type 2 Requested operation ID
ID 4 Unique ID (must be != 0)
Error code 4 0 = no error
Total size 4 Total transaction data size
Data size 4 Size of data in this part

Parameter Structure

A transaction contains a 2-byte field for the Number of parameters, followed by multiple structures:

Description Size Note
Field ID 2 Unique identifier
Field size 2 Data part size
Field data Var Actual content

Transaction Descriptions

Login (107)

  • Constant: myTran_Login
  • Initiator: Client

Request Fields:

  • 105: User login
  • 106: User password
  • 160: Version (Currently 151)

Reply Fields:

  • 160: Version
  • 161/162: Banner ID/Server Name (if Version >= 151)

Send Chat (105)

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

Request Fields:

  • 101: Chat message string
  • 109: Chat options (Normal 0, Alternate 1)
  • 114: Chat ID (Optional)

Disconnect User (110)

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

Request Fields:

  • 103: User ID
  • 113: Options (Ban options)

Flattened File Object (FILP)

Used for file/folder transfers (Trans 202, 203, 210, 213).

Flat File Header

  • Format: 'FILP' (0x46494C50)
  • Fork Count: 2 (Information Fork and Data Fork)

Information Fork (INFO)

  • Platform: 'AMAC' or 'MWIN'
  • Metadata: Type signature, Creator signature, Create/Modify dates, Name.

Data Fork (DATA)

  • Data Size: 4 bytes
  • Content: Actual file bytes.

Transaction Fields

Predefined types: Integer, String, and Binary.

ID Constant Type Note
101 myField_Data Binary General data
102 myField_UserName String
103 myField_UserID Integer
105 myField_UserLogin String
106 myField_UserPassword String
110 myField_UserAccess Binary 64-bit bitmap
114 myField_ChatID Integer
160 myField_Vers Integer Protocol version
202 myField_FilePath Binary File path structure

Access Privileges

Represented as a 64-bit bitmap in Field 110.

Bit Name Constant Type
0 Delete File myAcc_DeleteFile folder
1 Upload File myAcc_UploadFile folder/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

Client to Tracker

Request:

  • Magic Number: 'HTRK' (4 bytes)
  • Version: 1 or 2 (2 bytes)

Record Structure:

  • IP Address (4), Port (2), User Count (2), Name Size (1), Name (Var).

HTTP Tunneling

Uses POST for sending and GET for receiving.

  • MIME: hotline/protocol
  • Data Header: 4-byte Code (0=Disconnect, 1=Data, 2=Padding), 4-byte Size.

Global Server

Servers register with a unique name and password to the Global Server to receive a Server ID.

Fields Stored

  • Server ID, Name, Password, Alias, Description, IP, Status Flags, User Count.
Retrieved from "https://hlwiki.com/index.php?title=Hotsprings_Protocol&oldid=308"