Remote Commands
From IRCBotWiki
Contents |
Remote Protocol Overview
Bot Protocol 1.4
Latest Version (1.4): Wednesday, October 29, 2008
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.
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 or go to the IRCBot v2 wiki.
Command Structures
Here are the structures used in the protocol:
typedef struct {
unsigned int cmd; // command 0xXX
unsigned int datalen; // length of data sent along with the cmd (in bytes)
} REMOTE_HEADER;
typedef struct {
char title[64];// stream title
char dj[64];
int listeners;
int peak;
int max;
} STREAM_INFO;
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, MP3-Source, 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\x14
This should be the first thing sent to IRCBot after you connect, the only thing that can be sent before it is RCMD_ENABLE_SSL, 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_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_QUERY_STREAM
Hex Code: 0x02
Data Sent with Command: None
The bot will reply with RCMD_STREAM_INFO.
Request System Commands
RCMD_REQ_LOGIN
Hex Code: 0x11
Data Sent with Command: None
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_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_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 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>".
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
RCMD_SRC_COUNTDOWN
Hex Code: 0x30
Data Sent with Command: None
Makes AutoDJ count you in, just like !autodj-stop
RCMD_SRC_FORCE_OFF
Hex Code: 0x31
Data Sent with Command: None
Makes AutoDJ stop playing immediately, just like !autodj-force
RCMD_SRC_FORCE_ON
Hex Code: 0x32
Data Sent with Command: None
Makes AutoDJ start playing immediately, just like !autodj-play
RCMD_SRC_NEXT
Hex Code: 0x33
Data Sent with Command: None
Makes AutoDJ skip the current song, just like !next
RCMD_SRC_RELOAD
Hex Code: 0x34
Data Sent with Command: None
Makes AutoDJ skip the current song, 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 AutoDJ is currently playing, or RCMD_GENERIC_ERROR if AutoDJ isn't playing anything currently. (Note: On AutoDJ builds before 10/29/2008 the bot would reply with RCMD_GENERIC_MSG and a string beginning with Error:, sorry!)
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 AutoDJ 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 AutoDJ is loaded. Or RCMD_GENERIC_ERROR if it isn't.
User Info/Sharing Commands
RCMD_GETUSERINFO
Hex Code: 0x40
Data Sent with Command: An IRCBot 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: unsigned char (1 bytes) containing the user's level.
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.
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
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
| IRCBot v • d • e
|
|---|
| IRCBot main pages |
| Main Page • Installation • Changelog • Commands • Plugins • FAQ • Configuration• Credits • Remote Client • Buffered Send • Built-In Variables • Multi Sound Server Mode • Username Character Restrictions |
| Auto DJ Pages |
| Auto DJ Main Page • WebRequest System • Scheduler • MP3 Encoder • Voice Support • MySQL Plugin |
| IRCBot Programming v • d • e
|
| IRCBot Programming |
| IPC Messages • Remote Commands • Plugin Initialization • IRCBot DB • ShoutIRC Music Database |
| Tcl Functions |
| Tcl Scripting • Tcl Events |
