Lostarch: Updating Hotsprings Protocol

2026-03-03T20:00:15Z

Updating Hotsprings Protocol

Lostarch: 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: {|..."

2026-03-03T18:44:26Z

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: {|..."

New page

__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:

{| class="wikitable"
! 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 ===
{| class="wikitable"
! 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 ===
{| class="wikitable"
! 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 ===
{| class="wikitable"
! 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 ==
{| 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>
|-
| 202 || Download file || Client || <nowiki>myTran_DownloadFile</nowiki>
|-
| 300 || Get user name list || Client || <nowiki>myTran_GetUserNameList</nowiki>
|}

== Detailed Transaction Descriptions ==

=== Login (107) ===
Starts the login sequence with the server.
* '''Constant:''' <nowiki>myTran_Login</nowiki>
* '''Initiator:''' Client

'''Fields in Request:'''
{| class="wikitable"
! ID !! Field Name !! Note
|-
| 105 || User login ||
|-
| 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) ===
Sends a message to the public chat.
* '''Constant:''' <nowiki>myTran_ChatSend</nowiki>
* '''Access:''' Send Chat (10)
* '''Initiator:''' Client

'''Fields in Request:'''
{| class="wikitable"
! 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).

{| class="wikitable"
! Bit !! Name !! Constant !! Type
|-
| 0 || Delete File || <nowiki>myAcc_DeleteFile</nowiki> || folder
|-
| 1 || Upload File || <nowiki>myAcc_UploadFile</nowiki> || general
|-
| 2 || Download File || <nowiki>myAcc_DownloadFile</nowiki> || general
|-
| 9 || Read Chat || <nowiki>myAcc_ReadChat</nowiki> || general
|-
| 10 || Send Chat || <nowiki>myAcc_SendChat</nowiki> || general
|-
| 22 || Disconnect User || <nowiki>myAcc_DisconUser</nowiki> || general
|-
| 32 || Broadcast || <nowiki>myAcc_Broadcast</nowiki> || general
|}

== Tracker Interface ==
Trackers facilitate server discovery.

=== Server List Record ===
{| class="wikitable"
! 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:''' <code>hotline/protocol</code>

'''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.

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

Hotsprings Protocol - Revision history

Lostarch: Updating Hotsprings Protocol