Remote Commands

Remote Protocol Overview

Bot Protocol 1.8
Latest Version (1.8): Sunday, April 26, 2015
Version (1.7): Sunday, December 23, 2012
Version (1.6): Saturday, October 15, 2011
Version (1.5): Saturday, January 1, 2011
First Version (1.0): Thursday, January 29, 2004

This is a pretty simple protocol to implement, and was designed as such.
Any multi-byte values (shorts, ints, etc.) are little-endian.
All ints are 32-bits unless specified otherwise.
Unless specified otherwise, all commands will reply with RCMD_GENERIC_MSG on success, or RCMD_GENERIC_ERROR on failure.
Note: References to the old "remote console" (which just opened a window and printed ircbot text to it) have been removed starting with the protocol 1.4 revision.
The remote console only existed in IRCBot v2 and has been deprecated for some time now. To view information on it view a version of this page from before 10/29/2008.

Command Structures

Here are the structures used in the protocol:

typedef struct {
 unsigned int32 cmd; // command 0xXX
 unsigned int32 datalen; // length of data sent along with the cmd (in bytes)
} REMOTE_HEADER;

typedef struct {
 char title[64]; // stream title
 char dj[64];
 int32 listeners;
 int32 peak;
 int32 max;
} STREAM_INFO;

typedef struct {
 uint32_t file_id;
 char fn[1024];
 char artist[256];
 char album[256];
 char title[256];
 char genre[128];
 int32_t songLen; // length of the file in seconds from metadata or rough calculation
 bool is_request;
 char requested_by[64];
 int64_t playback_position; // position in the file playback in milliseconds
 int64_t playback_length; // length of the file in milliseconds (if known, <= 0 otherwise)
} IBM_SONGINFO;

Command Classifications

I classify the commands (.cmd) in this way:

0x0X = Login/Control Commands
0x1X = Request System Commands
0x2X = Misc Commands
0x3X = Source Control Commands (AutoDJ, SimpleDJ, etc.)
0x4X = User Info/Sharing Commands
0xFE = Generic Error Message

Commands from Client to Server

Login/Control Commands

RCMD_LOGIN
Hex Code: 0x00
Data Sent with Command: username\xFEpassword\xFE\x17
This should be the first thing sent to RadioBot after you connect, the only things that can be sent before it are RCMD_ENABLE_SSL and RCMD_GET_VERSION, any other commands will be ignored until you are logged in.
The bot will either: a) respond back with RCMD_LOGIN_OK, or b) respond back with RCMD_LOGIN_FAILED and an informational message.

RCMD_QUERY_STREAM
Hex Code: 0x02
Data Sent with Command: None
The bot will reply with RCMD_STREAM_INFO.

RCMD_ENABLE_SSL
Hex Code: 0x03
Data Sent with Command: None
The bot will either: a) respond back with RCMD_ENABLE_SSL_ACK and then call SSL_accept(), or b) reply with RCMD_GENERIC_MSG saying SSL support in the bot isn't enabled.
If the SSL_accept fails, or SSL support is not enabled you can continue the session un-encrypted without issue.}}

RCMD_GET_VERSION
Hex Code: 0x04
Data Sent with Command: None
The bot will reply back with RCMD_IRCBOT_VERSION or RCMD_GENERIC_MSG if it is a v4 or previous bot that doesn't support the command.

Request System Commands

RCMD_REQ_LOGOUT
Hex Code: 0x10
Data Sent with Command: None
The bot will reply with RCMD_REQ_LOGOUT_ACK if you were the active DJ and were successfully logged out, or with RCMD_GENERIC_ERROR and an error message.

RCMD_REQ_LOGIN
Hex Code: 0x11
Data Sent with Command:

v1-v4	None
v5	Optional - 1 byte - unsigned char with request options. Currently the only flag is 0x01 to enable @find Support.

The bot will reply with RCMD_REQ_LOGIN_ACK if you were successfully marked as the active DJ, or with RCMD_GENERIC_ERROR and an error message.

RCMD_REQ_CURRENT
Hex Code: 0x12
Data Sent with Command: None
The bot will reply with RCMD_GENERIC_MSG and the message will be the current nick (IRCBot v3) or username (IRCBot v4+) of the currently logged in DJ. If there is no logged in DJ, it will reply with RCMD_GENERIC_ERROR and an error message.

RCMD_SEND_REQ
Hex Code: 0x13
Data Sent with Command: The dedication text
This makes the bot send all the channels it is on request text like this: "This song was requested by <your text>".

RCMD_REQ
Hex Code: 0x14
Data Sent with Command: The request text/filename
This will submit a request to the current DJ or AutoDJ.

RCMD_SEND_DED
Hex Code: 0x15
Data Sent with Command: The dedication text
This makes the bot send all the channels it is on dedication text like "This song is dedicated to <your text>".

RCMD_FIND_RESULTS
Hex Code: 0x16
Data Sent with Command: Protobuf RemoteFindResult
See Find Support for more details.

Misc Commands

RCMD_DOSPAM
Hex Code: 0x20
Data Sent with Command: None
Toggles the global DoSpam flag.

RCMD_DIE
Hex Code: 0x21
Data Sent with Command: None
Kills the bot.

RCMD_BROADCAST_MSG
Hex Code: 0x22
Data Sent with Command: None
The bot will send the text you specify to all the channels it is on.

RCMD_RESTART
Hex Code: 0x23
Data Sent with Command: None
Restarts the bot.

RCMD_REHASH
Hex Code: 0x26
Data Sent with Command: None
Rehashes the bot.

Source Control Commands

Note: Not all Source Plugins support all Source Control Commands!
RCMD_SRC_COUNTDOWN
Hex Code: 0x30
Data Sent with Command: None
Makes the Source Plugin count you in, just like !autodj-stop

RCMD_SRC_FORCE_OFF
Hex Code: 0x31
Data Sent with Command: None
Makes the Source Plugin stop playing immediately, just like !autodj-force

RCMD_SRC_FORCE_ON
Hex Code: 0x32
Data Sent with Command: None
Makes the Source Plugin start playing immediately, just like !autodj-play

RCMD_SRC_NEXT
Hex Code: 0x33
Data Sent with Command: None
Makes the Source Plugin skip the current song, just like !next

RCMD_SRC_RELOAD
Hex Code: 0x34
Data Sent with Command: None
Scan for new songs, just like !autodj-reload

RCMD_SRC_GET_SONG
Hex Code: 0x35
Data Sent with Command: None
Replies with RCMD_GENERIC_MSG containing the filename of the song the Source Plugin is currently playing, or RCMD_GENERIC_ERROR if the Source Plugin isn't playing anything currently.

RCMD_SRC_RATE_SONG
Hex Code: 0x36
Data Sent with Command: nick\\xFErating\\xFEfilename
Nick is a username or other unique identifier (ie. an IP address if no nick is available)
Rating is a rating from 0-5 (0 = remove rating). This should be an ASCII 0-5 (ie. '0' = 0x30)
Filename is a file in the Source Plugin database. (just the filename, not the full path and filename)

RCMD_SRC_STATUS
Hex Code: 0x37
Data Sent with Command: None
Replies with RCMD_GENERIC_MSG containing either "playing", "connecting", or "stopped" if a Source Plugin is loaded. Or RCMD_GENERIC_ERROR if one isn't.

RCMD_SRC_GET_NAME
Hex Code: 0x38
Data Sent with Command: None
Replies with RCMD_GENERIC_MSG containing the name of your source plugin (AutoDJ, SimpleDJ, SAM, etc.) if one is loaded. Or RCMD_GENERIC_ERROR if not.

RCMD_SRC_RELAY
Hex Code: 0x39
Data Sent with Command: Filename or URL
Like !autodj-relay. Replies with RCMD_GENERIC_MSG acknowleding the submission of the file/URL if the Source Plugin is currently playing, or RCMD_GENERIC_ERROR if the Source Plugin isn't playing anything currently.

RCMD_SRC_GET_SONG_INFO
Hex Code: 0x3A
Data Sent with Command: None
Replies with RCMD_SONG_INFO containing a IBM_SONGINFO struct if the Source Plugin is currently playing, or RCMD_GENERIC_ERROR if the Source Plugin isn't playing anything currently.

User Info/Sharing Commands

RCMD_GETUSERINFO
Hex Code: 0x40
Data Sent with Command: A RadioBot username or hostmask
Replies with RCMD_USERINFO containing user info or RCMD_USERNOTFOUND if no matching user was found. This can also return a RCMD_GENERIC_ERROR if the user isn't a high enough level to use this command.

Commands from Server to Client

Login/Control Commands

RCMD_LOGIN_FAILED
Hex Code: 0x00
Data Sent with Command: An error message
Sent if you try to log in with an invalid user/pass or if there is another login error. (reply to RCMD_LOGIN)

RCMD_LOGIN_OK
Hex Code: 0x01
Data Sent with Command:

v1-v4	1 byte - unsigned char containing the user's level.
v5	5 bytes - unsigned char set to 0 (for compatibility with older clients) plus 32-bit unsigned int containing the user's flags.

Acknowledgement sent if you were logged in successfully. (reply to RCMD_LOGIN)

RCMD_ENABLE_SSL_ACK
Hex Code: 0x03
Data Sent with Command: None
Acknowledgement that you want to use SSL encryption, the bot will call SSL_accept() right after this. You should call SSL_connect() right after receiving this command.

RCMD_IRCBOT_VERSION
Hex Code: 0x04
Data Sent with Command: A 4 byte unsigned 32-bit integer representing the version and flags.
The format of the integer is 0x00XXYYFL where XX is the major version, YY is the minor version, and FL are flags telling if the bot is Full/Basic/Lite and debug or not.

Request System Commands

RCMD_REQ_LOGOUT_ACK
Hex Code: 0x10
Data Sent with Command: None
Sent if you were logged out of the Request System successfully.

RCMD_REQ_LOGIN_ACK
Hex Code: 0x11
Data Sent with Command: None
Sent if you were logged in to the Request System successfully.

RCMD_REQ_INCOMING
Hex Code: 0x12
Data Sent with Command: The request text
You will receive this if you are logged in to the Request System and receive a request. May contain multiple lines seperated with \xFE

RCMD_STREAM_INFO
Hex Code: 0x13
Data Sent with Command: A STREAM_INFO structure (see the Structures section above)
Reply to RCMD_QUERY_STREAM

RCMD_FIND_QUERY
Hex Code: 0x14
Data Sent with Command: Protobuf RemoteFindQuery
See Find Support for more details.

Source Control Commands

RCMD_SONG_INFO
Hex Code: 0x30
Data Sent with Command: An IBM_SONGINFO structure
Reply to RCMD_SRC_GET_SONG_INFO

User Info/Sharing Commands

RCMD_USERINFO
Hex Code: 0x40
Data Sent with Command: An IBM_USEREXTENDED structure
Reply to RCMD_GETUSERINFO

RCMD_USERNOTFOUND
Hex Code: 0x41
Data Sent with Command: None
Reply to RCMD_GETUSERINFO

Generic Reply Commands

RCMD_GENERIC_MSG
Hex Code: 0xFE
Data Sent with Command: A status message, usually indicating success. Put the text into a status box

RCMD_GENERIC_ERROR
Hex Code: 0xFF
Data Sent with Command: An error message to put into a status box

Find Support

Protocol 1.7 has the new feature of @find support. Unlike the other Remote Protocol commands, the data structures for these use Google Protocol Buffers.
The .proto file for @find support is File:Remote protobuf.proto.
A @find request will go like this:
1. User does an @find, the bot will send the client RCMD_FIND_QUERY with a protobuf RemoteFindQuery containing the search string and a unique search ID.
2. The client prepares a protobuf RemoteFindResult and sets the search ID from the RemoteFindQuery buffer.
3. It then searches it's music DB and adds any results to the files member of the RemoteFindResult. The file_id member of the RemoteFindResultEntry is optional and the client can use it however it wants. Remember the full size of the reply cannot be over 4096 bytes!
4. The client sends the bot RCMD_FIND_RESULTS with the RemoteFindResult buffer.