ŠĻą”±į > ž’ Ł Ū ž’’’ Ń Ņ Ó Ō Õ Ö × Ų ’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’’ģ„Į 7 ųæ ģ bjbjUU "R 7| 7| ęē ¦ ’’ ’’ ’’ l ų ų ų ų ų ų ų ö ö ö 8 . t ¢ > 2 Ź : ( , , , , L X ½ æ æ æ æ æ æ $ p Ö ć ų ` , , ` ` ć ^¬ ų ų , , ų ^¬ ^¬ ^¬ ` š ų , ų , ½ ^¬ ` ½ ^¬ H ^¬ ¦ r Æ T ų ų qÆ , ¾ ą£Ö!;üĀ ź ö P¦ ä UÆ qÆ Li 0 > cÆ f 4« * f qÆ ^¬ ų ų ų ų Ł Licensing The Hotline Protocol is the property of HYPERLINK "http://www.Hotspringsinc.com" Hotsprings Inc. It is licensed to you under the HYPERLINK "http://www.fsf.org" 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 GPLd 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 HYPERLINK "mailto:sales@hotspringsinc.com?subject=HL%20Protocol%20Licensing"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 users 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 servers 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. Namely, the base port number itself is used for regular transactions, while base port + 1 is used when upload/download is requested. HTTP tunneling uses base port + 2 for the regular transactions, and base + 3 for uploads/downloads. Numeric data transmitted over the wire is always in the network byte order. 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. The following information is sent to the server: DescriptionSizeDataNoteProtocol ID4TRTP0x54525450Sub-protocol ID4User definedVersion21Currently 1Sub-version2User defined The server replies with the following: DescriptionSizeDataNoteProtocol ID4TRTPError code4Error code returned by the server (0 = no error) 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. A transaction begins with the following header: DescriptionSizeDataNoteFlags10Reserved (should be 0)Is reply10 or 1Request (0) or reply (1)Type2Requested operation (user defined)ID4Not 0Unique transaction ID (must be != 0)Error code4Used in the reply (user defined, 0 = no error)Total size4Total data size for the transaction (all parts)Data size4Size of data in this transaction part This allows splitting large transactions into smaller parts Immediately following the header is optional transaction data. Data part contains transaction parameters. When these parameters are used, data part starts with the field containing the number of parameters in the parameter list: DescriptionSizeDataNoteNumber of parameters2Number of the parameters for this transactionParameter list Parameter list contains multiple records with the following structure: DescriptionSizeDataNoteField ID2Field size2Size of the data partField data sizeActual field content 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: IDTypeInitiatorConstant100Error?myTran_Error101Get messagesClientmyTran_GetMsgs102New messageServermyTran_NewMsg103Old post newsClientmyTran_OldPostNews104Server messageServermyTran_ServerMsg105Send chatClientmyTran_ChatSend106Chat messageServermyTran_ChatMsg107LoginClientmyTran_Login108Send instant messageClientmyTran_SendInstantMsg109Show agreementServermyTran_ShowAgreement110Disconnect userClientmyTran_DisconnectUser111Disconnect messageServermyTran_DisconnectMsg112Invite to a new chatClientmyTran_InviteNewChat113Invite to chatClientServermyTran_InviteToChat114Reject chat inviteClientmyTran_RejectChatInvite115Join chatClientmyTran_JoinChat116Leave chatClientmyTran_LeaveChat117Notify chat of a user changeServermyTran_NotifyChatChangeUser118Notify chat of a delete userServermyTran_NotifyChatDeleteUser119Notify of a chat subjectServermyTran_NotifyChatSubject120Set chat subjectClientmyTran_SetChatSubject121AgreedClientmyTran_Agreed122Server bannerServermyTran_ServerBanner200Get file name listClientmyTran_GetFileNameList202Download fileClientmyTran_DownloadFile203Upload fileClientmyTran_UploadFile204Delete fileClientmyTran_DeleteFile205New folderClientmyTran_NewFolder206Get file infoClientmyTran_GetFileInfo207Set file infoClientmyTran_SetFileInfo208Move fileClientmyTran_MoveFile209Make file aliasClientmyTran_MakeFileAlias210Download folderClientmyTran_DownloadFldr211Download infoServermyTran_DownloadInfo212Download bannerClientmyTran_DownloadBanner213Upload folderClientmyTran_UploadFldr300Get user name listClientmyTran_GetUserNameList301Notify of a user changeServermyTran_NotifyChangeUser302Notify of a delete userServermyTran_NotifyDeleteUser303Get client info textClientmyTran_GetClientInfoText304Set client user infoClientmyTran_SetClientUserInfo350New userClientmyTran_NewUser351Delete userClientmyTran_DeleteUser352Get userClientmyTran_GetUser353Set userClientmyTran_SetUser354User accessServermyTran_UserAccess355User broadcastClientServermyTran_UserBroadcast370Get news category name listClientmyTran_GetNewsCatNameList371Get news article name listClientmyTran_GetNewsArtNameList380Delete news itemClientmyTran_DelNewsItem381New news folderClientmyTran_NewNewsFldr382New news categoryClientmyTran_NewNewsCat400Get news article dataClientmyTran_GetNewsArtData410Post news articleClientmyTran_PostNewsArt411Delete news articleClientmyTran_DelNewsArt The following are the lists of related transactions that are implemented in the new version of Hotline software: User Login and ManagementIDTypeInitiatorNote107LoginClient109Show agreementServer121AgreedClient304Set client user infoClient301Notify of a user changeServer300Get user name listClient302Notify of a delete userServer Chat TransactionsIDTypeInitiatorNote115Join chatClient112Invite to a new chatClient113Invite to chatClient/Server114Reject chat inviteClient117Notify chat of a user changeServer116Leave chatClient118Notify chat of a delete userServer120Set chat subjectClient119Notify of a chat subjectServer105Send chatClient106Chat messageServer Messaging TransactionsIDTypeInitiatorNote104Server messageServer108Send instant messageClient 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: IDField NameNote101DataMessage text New Message (102) Constant: myTran_NewMsg Initiator: Server Fields used in the request: IDField NameNote101DataNews text Reply is not sent. Old Post News (103) Constant: myTran_OldPostNews Access: News Post Article (21) Initiator: Client Fields used in the request: IDField NameNote101Data Fields used in the reply: None Server Message (104) Constant: myTran_ServerMsg Initiator: Server Receive a message from the user on the current server, servers administrator, or server software itself. Fields used in the request: IDField NameNote103User ID102User name113OptionsBitmap created by combining the following values: - Automatic response (4) - Refuse private chat (2) - Refuse private message (1)101DataMessage to display214Quoting messageMessage to quote If User ID (103) field is not sent, receiver assumes that sender uses the following fields: IDField NameNote101Data109Chat optionsServer message (1) or admin message (any other value) 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: IDField NameNote109Chat optionsOptional Normal (0) or alternate (1) chat message114Chat IDOptional101DataChat message string Reply is not expected. Chat Message (106) Constant: myTran_ChatMsg Initiator: Server Receive a chat message from the chat. Fields used in the request: IDField NameNote114Chat ID101DataChat text If Chat ID is not available, the Data field contains: IDField NameNote101DataSpecial chat message 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: IDField NameNote105User login106User password160VersionCurrently 151 Fields used in the reply: IDField NameNote160Version If Version is >= 151, additional fields are included: IDField NameNote161Banner IDUsed for making HTTP request to get banner162Server nameServer name string 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: IDField NameNote103User ID113OptionsOne of the following values: - User message (myOpt_UserMessage = 1) - Refuse message (myOpt_RefuseMessage = 2) - Refuse chat (myOpt_RefuseChat = 3) - Automatic response (myOpt_AutomaticResponse = 4)101DataOptional214Quoting messageOptional 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 (see Transaction Sequences). Fields used in the request: IDField NameNote101DataAgreement string154No server agreementOptional No agreement available (1)152Server banner type153Server banner URLOptional If banner type is URL (1)151Server bannerOptional If banner type is not URL (1) 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: IDField NameNote103User ID113OptionsOptional Ban options101DataOptional Name? 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: IDField NameNote101DataMessage to display on disconnect (mandatory) Reply is not sent. Invite New Chat (112) Constant: myTran_InviteNewChat Initiator: Client Invite users to the new chat. Fields used in the request: IDField NameNote103User IDOptional103 User ID Optional More user IDs Fields used in the reply: IDField NameNote103User ID104User icon ID112User flags102User name114Chat ID Invite To Chat (113) Constant: myTran_InviteToChat Initiator: Client Invite user to the existing chat. Fields used in the request: IDField NameNote103User IDUser to invite114Chat ID Reply is not expected. The server can also be an initiator of this transaction. Initiator: Server Fields used in the request: IDField NameNote114Chat ID103User IDUser to invite102User name Reply is not sent. When client receives this message from the sever 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: IDField NameNote114Chat ID Reply is not expected. Join Chat (115) Constant: myTran_JoinChat Initiator: Client Join the chat. Fields used in the request: IDField NameNote114Chat ID Fields used in the reply: IDField NameNote115Chat subject300User name with infoOptional300 User name with info Optional More user names with info Leave Chat (116) Constant: myTran_LeaveChat Initiator: Client Leave the chat. Fields used in the request: IDField NameNote114Chat ID 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: IDField NameNote114Chat ID103User ID104User icon ID112User flags102User name 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: IDField NameNote114Chat ID103User ID 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: IDField NameNote114Chat ID115Chat subjectChat subject string Reply is not sent. Set Chat Subject (120) Constant: myTran_SetChatSubject Initiator: Client Set chat subject for the chat. Fields used in the request: IDField NameNote114Chat ID115Chat subjectChat subject string 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: IDField NameNote102User name104User icon ID113OptionsBitmap created by combining the following values: - Automatic response (4) - Refuse private chat (2) - Refuse private message (1)215Automatic responseOptional Automatic response string used only if the options field indicates this feature Fields used in the reply: None After receiving servers 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: IDField NameNote152Server banner typeUses only literal values153Server banner URLOptional 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 (etc. 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: IDField NameNote202File pathOptional If not specified, root folder assumed Fields used in the reply: IDField NameNote200File name with infoOptional200 File name with info Optional More file names with info 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: IDField NameNote201File name202File path203File resume dataOptional204File transfer optionsOptional Currently set to 2 Used only for TEXT, JPEG, GIFF, BMP or PICT files Fields used in the reply: IDField NameNote108Transfer sizeSize of data to be downloaded207File size107Reference numberUsed later for transfer116Waiting count 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: DescriptionSizeDataNoteProtocol4HTXF0x48545846Reference number4Use reference number received from the serverData size40RSVD40? 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: IDField NameNote201File name202File path204File transfer optionsOptional Used only to resume download, currently has value 2108File transfer sizeOptional Used if download is not resumed Fields used in the reply: IDField NameNote203File resume dataOptional Used only to resume download107Reference number 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: DescriptionSizeDataNoteProtocol4HTXF0x48545846Reference number4Use reference number received from the serverData size4File sizeRSVD40? 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: IDField NameNote201File name202File path 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: IDField NameNote201File name202File path 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: IDField NameNote201File name202File pathOptional Fields used in the reply: IDField NameNote201File name205File type string206File creator string210File commentComment string213File type208File create date209File modify date207File size 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: IDField NameNote201File name202File pathOptional211File new nameOptional210File commentOptional 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: IDField NameNote201File name202File path212File new path 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: IDField NameNote201File name202File path212File new pathDestination path 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: IDField NameNote201File name202File path Fields used in the reply: IDField NameNote220Folder item count107Reference numberUsed later for transfer108Transfer sizeSize of data to be downloaded116Waiting count 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: DescriptionSizeDataNoteProtocol4HTXF0x48545846Reference number4Use reference number received from the serverData size40Type21RSVD20?Download folder action23Next file action (3) See Download folder actions For every item in the folder, server replies with: DescriptionSizeDataNoteHeader size2Header datasize Header data contains the following: DescriptionSizeDataNoteType2?File pathrest 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: DescriptionSizeDataNoteDownload folder action23Next file action (3) See Download folder actions This notifies the server to send next item header. (2) If download of a file is to be resumed: DescriptionSizeDataNoteDownload folder action22Resume file transfer (2) See Download folder actionsResume data size2File resume datasizeSee content for field (203) (3) Otherwise, file download is requested by: DescriptionSizeDataNoteDownload folder action21Send file action (1) starts file download See Download folder actions When download is requested (case 2 or 3), server replies with: DescriptionSizeDataNoteFile size4File content sizeActual flattened file object (see Flattened File Object) After every file download client could request next file: DescriptionSizeDataNoteDownload folder action23Next file action (3) See Download folder actions This notifies the server to send next item header. 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: IDField NameNote107Reference numberDownload reference number116Waiting countPosition in the servers queue 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: IDField NameNote107Reference numberUsed later for transfer108Transfer sizeSize of data to be downloaded 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: DescriptionSizeDataNoteProtocol4HTXF0x48545846Reference number4Use reference number received from the serverData size40Type22RSVD20? 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: IDField NameNote201File name202File path108Transfer sizeTotal size of all items in the folder220Folder item count204File transfer optionsOptional Currently set to 1 Fields used in the reply: IDField NameNote107Reference numberUsed later for transfer 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: DescriptionSizeDataNoteProtocol4HTXF0x48545846Reference number4Use reference number received from the serverData size40Type21RSVD20? Server can reply with: DescriptionSizeDataNoteDownload folder action23Next file action (3) See Download folder actions After which client sends: DescriptionSizeDataNoteData size2Size of this structure (not including data size element itself)Is folder20 or 1Is the following file path a folderPath item count2Number of items in the pathFile name path File name path contains: DescriptionSizeDataNote20Currently 0Name size1File/folder namesize After every file, server can send one of 3 requests. (1) Request next file: DescriptionSizeDataNoteDownload folder action23Next file action (3) See Download folder actions This notifies the client to send next item. (2) Resume a file download procedure: DescriptionSizeDataNoteDownload folder action22Resume file transfer (2) See Download folder actionsResume data size2File resume datasizeSee content for field (203) After receiving this request, client starts sending file content from the requested location in the file. (3) Request a file download: DescriptionSizeDataNoteDownload folder action21Send file action (1) starts file download See Download folder actions Client replies to download requests with: DescriptionSizeDataNoteFile size4Current file size 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: IDField NameNote300User name with infoOptional300 User name with info Optional More user names with info 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: IDField NameNote103User ID104User icon ID112User flags102User name 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: IDField NameNote103User ID 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: IDField NameNote103User ID Fields used in the reply: IDField NameNote102User name101DataUser info text string Set Client User Info (304) Constant: myTran_SetClientUserInfo Initiator: Client Set user preferences on the server. Fields used in the request: IDField NameNote102User name104User icon ID113OptionsBitmap created by combining the following values: - Automatic response (4) - Refuse private chat (2) - Refuse private message (1)215Automatic responseOptional Automatic response string used only if the options field indicates this feature Reply is not expected. New User (350) Constant: myTran_NewUser Initiator: Client Add a new user to the servers list of allowed users. Fields used in the request: IDField NameNote105User login106User password102User name110User accessUser access privileges bitmap (see Access Privileges) Fields used in the reply: None Delete User (351) Constant: myTran_DeleteUser Initiator: Client Delete the specific user from the servers list of allowed users. Fields used in the request: IDField NameNote105User login Fields used in the reply: None Get User (352) Constant: myTran_GetUser Initiator: Client Request the information for the specific user from the servers list of allowed users. Fields used in the request: IDField NameNote105User login Fields used in the reply: IDField NameNote102User name105User loginEvery character in this string is negated (login[ i ] = ~login[ i ])106User password110User accessUser access privileges bitmap (see Access Privileges) Set User (353) Constant: myTran_SetUser Initiator: Client Set the information for the specific user in the servers list of allowed users. Fields used in the request: IDField NameNote105User login106User password102User name110User accessUser access privileges bitmap (see Access Privileges) 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: IDField NameNote110User accessUser access privileges bitmap (see Access Privileges) 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: IDField NameNote101Data Fields used in the reply: None The server can also be an initiator of this transaction. Initiator: Server Fields used in the request: IDField NameNote101DataAdministrator message 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: IDField NameNote325News pathOptional Fields used in the reply: IDField NameNote323News category list dataOptional323 News category list data Optional More news categories If version of client/server is 1.5 (prior to April 15, 1999?), instead of the previous reply, the following is sent: IDField NameNote320News category list dataOptional320 News category list data Optional More news categories 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: IDField NameNote325News pathOptional Fields used in the reply: IDField NameNote321News article list dataOptional 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: IDField NameNote325News path 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: IDField NameNote201File name325News path 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: IDField NameNote322News category name325News path 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: IDField NameNote325News path326News article ID327News article data flavor Fields used in the reply: IDField NameNote328News article title329News article poster330News article date331Previous article ID332Next article ID335Parent article ID336First child article ID327News article data flavorShould be text/plain Other values are currently ignored333News article dataOptional (if data flavor is text/plain) 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: IDField NameNote325News path326News article IDID of the parent article?328News article title334News article flags327News article data flavorCurrently text/plain333News article data 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: IDField NameNote325News path326News article ID337News article recursive deleteDelete child articles (1) or not (0) 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: DescriptionSizeDataNoteFormat4FILP0x46494C50Version21RSVD16Fork count22 Flat file information fork header: DescriptionSizeDataNoteFork type4INFO0x494E464FCompression type40Currently no compressionRSVD4Data size4Size of the flat file information fork Flat file information fork: DescriptionSizeDataNotePlatform4AMAC or MWINOperating system usedType signature4File type signatureCreator signature4File creator signatureFlags4Platform flags4RSVD32Create date8See description for the File Create Date field (208)Modify date8See description for the File Modify Date field (209)Name script2Name size2NamesizeMaximum 128 characters Flat file data fork header: DescriptionSizeDataNoteFork type4DATA0x44415441Compression type40Currently no compressionRSVD4Data size4Actual file content size 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, its 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: BitValueDescription01User is away12User is admin (or disconnected?)24User refuses private messages38User refuses private chat 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: ValueEquivalent ValueDescription1URL URL link3JPEGJPEG file4GIFfGIF file5BMP BMP file6PICTPICT file 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: DescriptionSizeDataNoteType4Folder (fldr) or otherCreator4File size44Reserved?Name script2Name size2Name datasize 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: DescriptionSizeDataNoteFormat4RFLTVersion21Currently 1RSVD34?Fork count22Currently 2Fork info list Fork info list contains one or more records with the following structure: DescriptionSizeDataNoteFork4DATAData size4Current file sizeRSVD A4?RSVD B4? 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 create date field has this structure: DescriptionSizeDataNoteYear2Milliseconds2Seconds4 File Modify Date (209) Constant: myField_FileModifyDate Type: Binary File modify date field has this structure: DescriptionSizeDataNoteYear2Milliseconds2Seconds4 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 File type field contains only one value: DescriptionSizeDataNoteFile type4File type code (fldr or other) 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 User name with info field contains this structure: DescriptionSizeDataNoteUser ID2Icon ID2User flags2User name size2User namesizeUser name string 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: DescriptionSizeDataNoteType11, 10 or 255Category folder (1), category (10) or other (255)Category namerest This field is used for client/server version 1.5 (prior to April 15, 1999?). News Article List Data (321) Constant: myField_NewsArtListData Type: Binary News article list data field contains this structure: DescriptionSizeDataNoteID4Article count4Number of articlesName size1NamesizeName stringDescription size1DescriptionsizeDescription stringList of articles Optional (if article count > 0) List of articles contains: DescriptionSizeDataNoteArticle ID4Time stamp8Year (2 bytes), milliseconds (2 bytes) and seconds (4 bytes)Parent article ID4Article flags4Flavor count2Title size1TitleSizeTitle stringPoster size1PosterSizePoster stringFlavor list Optional (if flavor count > 0) Flavor list has the following structure: DescriptionSizeDataNoteFlavor size1Flavor textsizeMIME type stringArticle size2 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: DescriptionSizeDataNoteType22 or 3Bundle (2) or category (3) If type value indicates a bundle, what follows the type is: DescriptionSizeDataNoteCount2Name size1Name datasize In the case of a category type, type value is followed by: DescriptionSizeDataNoteCount2GUIDAdd SN4Delete SN4Name size1Name datasize 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 date field contains this structure: DescriptionSizeDataNoteYear2Milliseconds2Seconds4 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) (Delete Children) 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. Delete File (0) Constant: myAcc_DeleteFile Type: folder Upload File (1) Constant: myAcc_UploadFile Type: folder, general Download File (2) Constant: myAcc_DownloadFile Type: folder, general Rename File (3) Constant: myAcc_RenameFile Move File (4) Constant: myAcc_MoveFile Create Folder (5) Constant: myAcc_CreateFolder Type: folder Delete Folder (6) Constant: myAcc_DeleteFolder Type: folder Rename Folder (7) Constant: myAcc_RenameFolder Move Folder (8) Constant: myAcc_MoveFolder Read Chat (9) Constant: myAcc_ReadChat Type: general Send Chat (10) Constant: myAcc_SendChat Type: general Open Chat (11) Constant: myAcc_OpenChat Close Chat (12) Constant: myAcc_CloseChat Show in List (13) Constant: myAcc_ShowInList Create User (14) Constant: myAcc_CreateUser Delete User (15) Constant: myAcc_DeleteUser Open User (16) Constant: myAcc_OpenUser Modify User (17) Constant: myAcc_ModifyUser Change Own Password (18) Constant: myAcc_ChangeOwnPass Send Private Message (19) Constant: myAcc_SendPrivMsg News Read Article (20) Constant: myAcc_NewsReadArt Type: bundle, general News Post Article (21) Constant: myAcc_NewsPostArt Type: general, bundle Disconnect User (22) Constant: myAcc_DisconUser Type: general Cannot be Disconnected (23) Constant: myAcc_CannotBeDiscon Get Client Info (24) Constant: myAcc_GetClientInfo Type: general Upload Anywhere (25) Constant: myAcc_UploadAnywhere Any Name (26) Constant: myAcc_AnyName Type: general No Agreement (27) Constant: myAcc_NoAgreement Set File Comment (28) Constant: myAcc_SetFileComment Type: folder Set Folder Comment (29) Constant: myAcc_SetFolderComment Type: folder View Drop Boxes (30) Constant: myAcc_ViewDropBoxes Make Alias (31) Constant: myAcc_MakeAlias Type: folder Broadcast (32) Constant: myAcc_Broadcast Type: general News Delete Article (33) Constant: myAcc_NewsDeleteArt Type: bundle News Create Category (34) Constant: myAcc_NewsCreateCat Type: bundle News Delete Category (35) Constant: myAcc_NewsDeleteCat Type: bundle News Create Folder (36) Constant: myAcc_NewsCreateFldr Type: bundle News Delete Folder (37) Constant: myAcc_NewsDeleteFldr Type: bundle 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 in not initiated. Transaction Sequences Hotline client contains few predefined transaction sequences in its current implementation. These sequences are described in this section. 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 sever 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: DescriptionSizeDataNoteMagic number4HTRKVersion21 or 2Old protocol (1) or new (2) When version number is 2, request also includes additional data: DescriptionSizeDataNoteLogin size1>= 31Login string sizeLoginsizeLogin string (padded with 0)Password size1>= 31Password string sizePasswordsizePassword string (padded with 0) Reply received from the tracker starts with a header: DescriptionSizeDataNoteMagic number4HTRK0x4854524BVersion21 or 2Old protocol (1) or new (2) Server information header follows, formatted as: DescriptionSizeDataNoteMessage type21Sending list of serversMessage data size2Remaining size of this requestNumber of servers2Number of servers in the server listNumber of servers2Same as previous fieldServer list A record in the server list has the following structure: DescriptionSizeDataNoteIP address4Servers IP addressIP port number2Servers IP port numberNumber of users2Number of users connected to this particular server20Name size1Servers name string sizeNamesizeServers nameDescription size1Servers description string sizeDescriptionsizeDescription of the server 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: DescriptionSizeDataNote21IP port number2Servers listening UDP port numberNumber of users2Number of users connected to this particular server20Pass ID4Random number generated by the serverName size1Servers name string sizeNamesizeServers nameDescription size1Servers description string sizeDescriptionsizeDescription of the server In the case when old (?) tracker is used, the additional information is formatted as follows: DescriptionSizeDataNotePassword size1Servers tracker password string sizePasswordsizeServers tracker password For a new version of the tracker: DescriptionSizeDataNoteLogin size1Servers tracker login string sizeLoginsizeServers tracker loginPassword size1Servers tracker password string sizePasswordsizeServers tracker password 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. The POST request is specified as follows: POST
HTTP/1.0\r\n Proxy-Connection: Keep-Alive\r\n Pragma: no-cache\r\n Host: