Sign In
Register
Help
No specific character set is specified. The protocol is based on a set of codes which are composed of eight ( 8 ) bits, making up an octet. Each message may be composed of any number of these octets; however, some octet values are used for control codes which act as message delimiters.
Messages
The HiveMind server and clients send each other messages which may or may not generate a reply. If the message contains a valid command, as described in later sections, the client should expect a reply as specified but it is not advised to wait forever for the reply; client to server communication is essentially asynchronous in nature.
Each HiveMind message may consist of up to three main parts: the prefix (optional), the command, and the command parameters (of which there may be up to 15). The command is separated from the prefix by a single ASCII space character (0x20). The command parameters begin immediately after the command and are separated by one ASCII space character. It is important to note that their is no ASCII space separating the command and the first command parameter as the command is always 1 octet. Some command parameters in HiveMind are ASCII space delimited and if a space is actually part of a single argument you can escape it with an ASCII backslash ('\', 0x5C).
The presence of a prefix is indicated with a single leading ASCII colon character (':', 0x3b), which must be the first character of the message itself. There must be no gap (whitespace) between the colon and the prefix. The prefix is used by the client to indicate the true origin of the message. If the prefix is missing from the message, it is assumed that the message originated from the server. Clients should never use a prefix when sending a message from themselves.
The command must be a valid HiveMind command represented as 1 octet.
If however, the origin of the message as declared by the prefix is a mechanical channel (IE: :&distributed) then the command used must be a valid command of the enhancement protocol relevant to '&distributed' instead of the HiveMind protocol
HiveMind messages are always lines of characters terminated with a CR-LF (Carriage Return - Line Feed) pair, and these messages shall not exceed 512 characters in length, counting all characters including the trailing CR-LF. Thus, there are 510 characters maximum allowed for the command and its parameters. There is no protocol level provision for continuation message lines.
Message details
What follows are descriptions of each message recognized by the HiveMind server and client.
The server is required to parse the complete message, returning any appropriate errors. If the server encounters a fatal error while parsing a message, an error must be sent back to the client and the parsing terminated. A fatal error may be considered to be incorrect command, a destination which is otherwise unknown to the server (server, nick or channel names fit this category), not enough parameters or incorrect privileges.
If a full set of parameters is presented, then each must be checked for validity and appropriate responses sent back to the client.
In the examples below, some messages appear using the full format:
:Name COMMAND parameter list
Such examples represent a message from "Name" in transit between, where it is essential to include the name of the original sender of the message so clients may be aware of the origin of the message.
Connection Registration
The commands described here are used to register a connection with an IRC server as either a user or a server as well as correctly disconnect.
Before the client is allowed to do anything else through the HiveMind server they must first authenticate with their CS.net credentials. This is accomplished by sending an AUTH message.
Authentication message
Command: AUTH
Octet value: 0x01
Parameters: <username> <password>
The AUTH command is used to authenticate a user with the HiveMind server. The password parameter is ASCII space (0x20) delimeted from the password, therefore spaces in usernames must be escaped with a ASCII backslash ('\', 0x5C). Escaping space characters in the password should be irrelavent as we encourage all paswords to be transmitted only after they have been hashed for security reasons. Anonymous sessions will be initiate by the client sending an AUTH command wich is immediately terminated by a CR-LF. Upon successful client authentication the server will respond with a single AUTH command (0x01) granting the user permission to proceed through as an authenticated session. If however the credentials did not check out or something else went wrong in transit the server will instead send the client an ERROR command (0x0E) notifying it of what went wrong and unless this is followed by a KILL command (0x0C) then it is implied that the server is waiting for another authentication attempt via the AUTH command.
Examples:
[0x01]UserNameHere PasswordHashHere ; non anonymous user authentication
[0x01] ; Coming from the client, this is asking permision to initiate an anonymous session, coming from the server this is confirming that an authenticated session has been granted.
NOTE: Once a client is authenticated and has a valid session, the client still can't do anything until it has gone through the current version sequence with the sever (see the VERSION command)
Quit
Command: QUIT
Octet value: 0x02
Parameters: [<Quit message>]
A client session is ended with a quit message. The server must close the connection to a client which sends a QUIT message. If a "Quit Message" is given, this will be sent instead of the default message, the nickname.
If, for some other reason, a client connection is closed without the client issuing a QUIT command (e.g. client dies and EOF occurs on socket), the server is required to fill in the quit message with some sort of message reflecting the nature of the event which caused it to happen.
Examples:
[0x02]:Gone for some dinner ; Let the server know you're leaving to get some food
:Pilot [0x02]:Sleep ; notification that Pilot left HiveMind to get some sleep
Channel operations
Currently GeoIP is the only use for channel operations in the future channelized communication may be utilized to provide opt-in services such as distributed computing, torrent seeding on demand, etc or even just multiple IRC like chat channels.
Channels that would be utilized for human to human communication would be prefixed with a single # (0x23) while channels utilized for machine channelized communication would be prefixed with a single & (0x26)
Join message
Command: JOIN
Octet value: 0x03
Parameters: <channel>{,<channel>}
The JOIN command is used by client to start listening a specific channel.
Once a user has joined a channel, they receive notice about all commands the HiveMind server receives which affect the channel. This includes KICK, PART, QUIT and of course PRIVMSG/NOTICE amongst various other channelized mechanical communications.
If a client receives the join request back from the server this means that it's request to join that channel has been granted. Otherwise it is assumed although not required that the server will respond with an ERROR command on why the request was denied.
Examples:
[0x03]#hive ; Client requesting to join #hive, or server telling the client it's request has been granted
[0x03]&distributed ; Client request to join &distributed, or server telling client it's request has been granted
:Thetan [0x03]#hive ; Notification that Thetan joined #hive
:Fallen_demon [0x03]&distributed ; Notification that Fallen_demon is participating in distributed computing
Part message
Command: PART
Octet value: 0x04
Parameters: <channel>{,<channel>} [<reason>]
The PART message causes the client sending the message to be removed from the list of active users for all given channels listed in the parameter string.
Examples:
[0x04]#hive :Can't talk anymore ; leave channel #hive with the reason that you can't talk anymore
:Thetan [0x04]#hive :Busy ; Notification that Thetan left hive because he was busy
[0x04]&distributed ; Stop distributed computing, no reason needed
:Fallen_Demon [0x04]&distributed :movie time ; Notification that Fallen_Demon stopped distributed computing because it's movie time.
Names message
Command: NAMES
Octet value: 0x05
Parameters: <channel>
By using the NAMES command, a user can list all nicknames that are visible to them on any channel that they can see. This would be useful in HiveMind to see who's currently participating in what opt-in service.
Examples:
[0x05]&seedondemand ; client request a list of users participating in seeding on demand
[0x05]&distributed ; client request a list of users participating in distributed computing
The servers response to this this is the same command (0x05) as a stream where the first command parameter set to the corresponding channel and the other parameters are space delimited user names. The stream only ends when a NAMES command has been received with only the channel parameter set and no more user names.
Examples:
[0x05]&distributed Thetan Pilot Fallen_Demon ; Thetan, Pilot and Fallen_Demon are participating in &distributed
[0x05]&distributed ; End of NAMES stream for channel &distributed
List message
Command: LIST
Octet value: 0x06
Parameters: [<channel>]
The list message is used to list channels and their topics. If the <channel> parameter is used, only the status of that channel is displayed. Private channels are listed (without their topics) as channel "Prv" unless the client generating the query is actually on that channel. Likewise, secret channels are not listed at all unless the client is a member of the channel in question.
Examples:
[0x06] ; List all channels.
[0x06]&distributed ; Queries the status of distributed work.
If no channel was specified then the server should respond with a stream of LIST messages, one for each channel. The first command parameter in it's response will be a channel, the second parameter will be the number of people in that channel and the third parameter will be the channel topic. The stream of LIST messages is to come to an end only when the client receives a LIST command with no parameters. If a channel was specified then message stream will occur and instead their should only be one LIST response from the server. If the specified channel doesn't exist then then instead of the server responding with a LIST command it will respond with an appropriate ERROR command instead.
Examples:
[0x06]#hive 2 :I FLY, do you? ; 2 users in channel #hive and the topic is 'i FLY, do you?'
[0x06]&geo 5 :Fly's are taking ova' ; 5 users participating in GeoIP
[0x06] ; A blank LIST command, thus the end of the LIST stream
Kick command
Command: KICK
Octet value: 0x07
Parameters: <channel> <user> [<comment>]
The KICK command can be used to forcibly remove a user from a channel. It 'kicks them out' of the channel (forced PART).
Only a channel/hive operator may kick another user out of a channel.
Examples:
[0x07]&distributed Thetan :Client out of date ; Stop Thetan from doing distributed work because his client is out of date.
[0x07]#hive Pilot :For being awesome ; Kick Pilot from #hive for being awesome.
:Fallen_Demon [0x07]#hive Pilot ; Notification that Fallen_Demon has kicked Pilot from #hive
Topic command
Command: TOPIC
Octet value: 0x12
Parameters: <channel>[<topic>]
The TOPIC command is used to either query the server for the specified channel's topic or if the topic parameter is set attempt to change the specified channels topic.
Examples:
[0x12]#hive ; Client requesting the channel topic for #hive
[0x12]#hive :Welcome to the hive! ; attempt to set the topic for channel #hive to 'Welcome to the hive!'
The servers response to a TOPIC query will be the TOPIC command with the first parameter as the requested channel and the second parameter as the topic. The servers response to a successful topic change will be the same as the response to a TOPIC query. If for any reason the server decides to deny the request to change the topic it should respond (although not necessary) with an appropriate ERROR command.
Example:
[0x12]#hive :New topic! ; response that the channel topic for #hive is now 'New topic!'
NOTE: Only channel/hive ops should be allowed to change channel topics.
Server queries and commands
The server query group of commands has been designed to return statistical information on the server and clients. Any invalid response (or lack thereof) must be considered a sign of a broken server and it must be disconnected/disabled as soon as possible until the situation is remedied.
Version message
Command: VERSION
Octet value: 0x08
Parameters: [<version number>]
The VERSION message is sent from the server to the client with the most up to date version number, querying the client for their current version number. The clients response should be the same command with it's current version number following immediately after. Version numbers will be sent as delimited 8-bit integers (1 octet). IE version 10.1.5 would be sent as [0x0A][0x01][0x05]. When the client receives the up to date version number and it doesn't match it's current version number the client can either update and retry or go ahead and try to connect with an outdated version. If the server becomes aware that the client is connecting with an outdated version the server can either choose to let this happen (if the versions are compatible to communicate with each other) or send the client the KILL command and discontinue their connection.
Examples:
[0x08][0x01][0x08][0x02] ; When the client receives this the server is saying the most recent version number is 1.8.2 and asking for the client's current version number
[0x08][0x01][0x08][0x02] ; When the client sends this to the server it's saying that it's running version 1.8.2
Stats message
Command: STATS
Octet value: 0x09
Parameters: None
Used by HiveMind clients to query the server for up to date server statistics.
Example:
[0x09] ; A client requesting the current stats from the server
The response to this reqeust from the server will be the STATS command followed by a parameter list as follows.
Parameters: <#connected><most #connected><date of most><longest up><shortest up><#outdated><avg load>
Where '#connected' will be a unsigned 32-bit integer, 'most #connected' will be a unsigned 32-bit integer, 'date of most' will be a 32-bit unix timestamp, 'longest up' will be an unsigned 32-bit integer, 'shortest up' will be an unsigned 32-bit integer, '#outdated' will be an unsigned 32-bit integer and 'avg load' will be the ASCII representation of average load
Example:
[0x09][0x00000CC4][0x00001B4B][0x4AFC6ACA][0x1B6D9C8C][0x000000f0][0X0000000C]0.05 0.04 0.10
; Is the server saying that the number of people currently connected are 3268, the most ever connected was 6987 and this happened on 11/12/2009 at 2:06 pm EST, -5 GMT w/DST, the longest up time was 326 days 12 hours 32 minutes 12 seconds, with the shortest up time being 4 minutes and average client load is currently 0.05 0.04 0.10
Sending messages
The HiveMind server also provides a good base for clients to communicate with each other. PRIVMSG and NOTICE are the only messages available which actually perform delivery of a text message from one client to another - the rest just make it possible and try to ensure it happens in a reliable and structured manner.
Private messages
Command: PRIVMSG
Octet value: 0x0A
Parameters: <receiver>{,<receiver>} <text to be sent>
PRIVMSG is used to send private messages between users. <receiver> is the nickname of the receiver of the message. <receiver> can also be a list of names or channels separated with commas.
Examples:
:Pilot [0x0A]Thetan :Hey, are you there? ; Received message from Pilot to Thetan.
[0x0A]Pilot :yes sir.; Response to Pilot.
Notice
Command: NOTICE
Octet value: 0x0B
Parameters: <nickname> <text>
The NOTICE message is used similarly to PRIVMSG. NOTICE will be primarily used for mechanical channelized communications.
Miscellaneous messages
Messages in this category do not fit into any of the above categories
but are nonetheless still a part of and required by the protocol.
Kill message
Command: KILL
Octet value: 0x0C
Parameters: <nickname> [<comment>]
The KILL message is used to cause a client-server connection to be closed by the server which has the actual connection.
Example:
[0x0C]morkeh :No flooding please ; A hive op killing morkeh for flooding
:Thetan [0x0C]rawr :No spam kthx ; Hive op Thetan killing user rawr for spamming
NOTE:
Only hive operators should be allowed to kill users.
Ping message
Command: PING
Octet value: 0x0D
Parameters: <challenge>
The PING message is used to test the presence of an active client at the other end of the connection. A PING message is sent at regular intervals if no other activity detected coming from a connection. If a connection fails to respond to a PING command within a set amount of time, that connection is closed. A PING message will be immediately followed by a challenge octet. The challenge octet must be sent back to the server as the challenge parameter for the response PONG. The client should expect the challenge parameter to change every PING request.
Examples:
[0x0D][0x3B] ; PING message from the server with the challenge set to 0x3B
Pong message
Command: PONG
Octet value: 0x0D
Parameters: <challenge>
PONG message is a reply to PING message. The octet value for the PING command and the PONG command are the same. So all commands of [0x0D] coming from the server should be interpreted as PING messages requiring a response and all command of [0x0D] being received by the server from a client should be considered a PONG response.
Examples:
[0x0D][0x3B] ; PONG response to a PING with the challenge of 0x3B
Error
Command: ERROR
Octet value: 0x0E
Parameters: <error message>
The ERROR command is for notifying the client of any errors encountered by the server. If the first parameter begins with a : then the error message is treated as a human readable one. Otherwise the only command parameter should be a 1 octet error code
-------List of error codes will be compiled soon!-------------
Examples:
[0x0E]:Invalid credentials; Invalid credentials during login
[0x0E][0x12] ; Returns error code 12
Away
Command: AWAY
Octet value: 0x0F
Parameters: [message]
With the AWAY message, clients can set an automatic reply string for any PRIVMSG commands directed at them (not to a channel they are on). The automatic reply is sent by the server to client sending the PRIVMSG command. Sending the away command to the server while you're marked as away will un-mark you as being away.
The AWAY message is used either with one parameter (to set an AWAY message) or with no parameters (to remove the AWAY message).
Examples:
[0x0F]:Lunch time ; Setting your away message to "Lunch time"
Back in 5".
:Thetan [0x0F] ; unmark Thetan as being away.
Users
Command: USERS
Octet value: 0x10
Parameters: None
The USERS command requests a list of users logged into the server.
Examples:
[0x10] ; request a list of users logged in
The server response is a stream of USERS commands where the command parameters are space delimited user names. The stream is expected to have come to an end only when the client receives a blank USERS command from the server.
Examples:
[0x10]Thetan Pilot Fallen_Demon ; Thetan, Pilot and Fallen_Demon are currently on HiveMind.
[0x10] ; end of USERS stream
Ison message
Command: ISON
Octet value: 0x11
Parameters: <nickname>{<space><nickname>}
The ISON command was implemented to provide a quick and efficient means to get a response about whether a given nickname was currently on HiveMind. ISON takes one parameter which is a space seperated list of nicknames. The expected return from the server is a message with the ISON command followed by a space seperated list of nicknames that are on from the submitted list (users that aren't on will be ommitted from the list).
Examples:
[0x15]Thetan Fallen_Demon Pilot ; Sample ISON request for 7 nicks.
Enhancement protocols
In HiveMind enhancement protocols are encapsulated through mechanical channels to ultimately extend the functionality of HiveMind. If a client receives a message of origin from a mechanical channel, a channel prefixed by an ASCII ampersand ('&', 0x26) then the command sequence executed must be that of the enhancement protocol associated to that channel. Clients are able to send Enhancement protocol commands via the NOTICE command immediately followed by the channel name associated with the enhancement protocol followed by an enhancement protocol command seperated from the channel by an ASCII space (0x20) and as with a regular HiveMind command the command parameter list will immediately follow the enhancement protocol command and be a space seperated list.
GeoIP
The GeoIP enhancement protocol is associated with the mechanical channel &geo. It is usually automatically joined by the HiveMind client upon the start of a valid authenticated session. Simply 'sitting' (not parting) in this channel will opt the client in to participate in the GeoIP map of fly users. Users not wishing to participate in GeoIP may opt-out any time by simply parting from this channel.
Example:
[0x04]&geo ; opt-out of GeoIP
GeoIP messages
As a matter of fact, the PART command is the only effective command a client can send in this enhancement protocol that has any effect in the channel. This is mostly a enhancement protocol for pushing GeoIP data to the client.
Country messages
Command: COUNTRY
Octet value: 0x01
Parameters: <country><count>{<country><count>}
COUNTRY messages are streams of countries with the ammount of HiveMind users connected from them. Each country parameter will be an 8-bit octet while each . coresponding count parameter will be a 32-bit integer immediately following the country. Countries will be represented by numerical keys (starting at 0) of full country names in alphabetical order in accordance with ISO 3166 and if dispayed by the client it is expected to be displayed as the name or abbreviation also in accordance with ISO 3166( http://www.iso.org/i...en1-semic-3.txt ).
Example:
:&geo [0x01][0x00][0x00000001][0x50][0x00000146][0xE7][0x000001F4]
; translates to 1 user connected in afgahnistan, 80 users connected in germany and 500 users connected in the UK
End country messages
Command: ENDCOUNTRY
Octet value: 0x02
Parameters: None
Starting from the first country message received the client is expected to keep reading them until the stream has come to an end. The client knows that the stream has come to an end when the ENDCOUNTRY command has been received. So to sum it up. Starting from the first COUNTRY command the client will expect more and more COUNTRY commands until it receives an ENDCOUNTRY command.
Example:
:&geo [0x02] ; effectively ends the current COUNTRY stream
This post has been edited by Thetan: 16 November 2009 - 06:06 PM
MultiQuote
