Remote Commands - Revision history

Indy: /* Command Structures */

2015-04-26T18:37:30Z

Command Structures

← Older revision		Revision as of 18:37, 26 April 2015
Line 37:		Line 37:
	char title[256];		char title[256];
	char genre[128];		char genre[128];
	int32_t songLen;		int32_t songLen; // length of the file in seconds from metadata or rough calculation
	bool is_request;		bool is_request;
	char requested_by[64];		char requested_by[64];
			int64_t playback_position; // position in the file playback in milliseconds
	int64_t playback_position;		int64_t playback_length; // length of the file in milliseconds (if known, <= 0 otherwise)
	int64_t playback_length;
	} IBM_SONGINFO;		} IBM_SONGINFO;

Indy: /* Command Structures */

2015-04-26T18:35:48Z

Command Structures

← Older revision		Revision as of 18:35, 26 April 2015
Line 1:		Line 1:
	==Remote Protocol Overview==		==Remote Protocol Overview==
	Bot Protocol 1.7<br>		Bot Protocol 1.8<br>
	Latest Version (1.7): Sunday, December 23, 2012<br>		Latest Version (1.8): Sunday, April 26, 2015<br>
			Version (1.7): Sunday, December 23, 2012<br>
	Version (1.6): Saturday, October 15, 2011<br>		Version (1.6): Saturday, October 15, 2011<br>
	Version (1.5): Saturday, January 1, 2011<br>		Version (1.5): Saturday, January 1, 2011<br>
Line 50:		Line 51:
	0x1X = Request System Commands<br>		0x1X = Request System Commands<br>
	0x2X = Misc Commands<br>		0x2X = Misc Commands<br>
	0x3X = Source Control Commands (AutoDJ, ~~MP3-Source~~, etc.)<br>		0x3X = Source Control Commands (AutoDJ, SimpleDJ, etc.)<br>
	0x4X = User Info/Sharing Commands<br>		0x4X = User Info/Sharing Commands<br>
	0xFE = Generic Error Message<br>		0xFE = Generic Error Message<br>
Line 146:		Line 147:
	{{rcom\|RCMD_SRC_GET_NAME\|0x38\|None}}		{{rcom\|RCMD_SRC_GET_NAME\|0x38\|None}}
	Replies with {{rcomlink\|RCMD_GENERIC_MSG}} containing the name of your source plugin (AutoDJ, SimpleDJ, SAM, etc.) if one is loaded. Or {{rcomlink\|RCMD_GENERIC_ERROR}} if not.		Replies with {{rcomlink\|RCMD_GENERIC_MSG}} containing the name of your source plugin (AutoDJ, SimpleDJ, SAM, etc.) if one is loaded. Or {{rcomlink\|RCMD_GENERIC_ERROR}} if not.

			{{rcom\|RCMD_SRC_RELAY\|0x39\|Filename or URL}}
			Like !autodj-relay. Replies with {{rcomlink\|RCMD_GENERIC_MSG}} acknowleding the submission of the file/URL if the Source Plugin is currently playing, or {{rcomlink\|RCMD_GENERIC_ERROR}} if the Source Plugin isn't playing anything currently.

			{{rcom\|RCMD_SRC_GET_SONG_INFO\|0x3A\|None}}
			Replies with {{rcomlink\|RCMD_SONG_INFO}} containing a IBM_SONGINFO struct if the Source Plugin is currently playing, or {{rcomlink\|RCMD_GENERIC_ERROR}} if the Source Plugin isn't playing anything currently.

	===User Info/Sharing Commands===		===User Info/Sharing Commands===
Line 188:		Line 195:
	{{rcom\|RCMD_FIND_QUERY\|0x14\|Protobuf RemoteFindQuery}}		{{rcom\|RCMD_FIND_QUERY\|0x14\|Protobuf RemoteFindQuery}}
	See [[Remote_Commands#Find Support\|Find Support]] for more details.		See [[Remote_Commands#Find Support\|Find Support]] for more details.

			===Source Control Commands===
			{{rcom\|RCMD_SONG_INFO\|0x30\|An IBM_SONGINFO structure}}
			Reply to {{rcomlink\|RCMD_SRC_GET_SONG_INFO}}

	===User Info/Sharing Commands===		===User Info/Sharing Commands===

Indy: /* Command Structures */

2015-04-26T18:23:02Z

Command Structures

← Older revision		Revision as of 18:23, 26 April 2015
Line 17:		Line 17:

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

	typedef struct {		typedef struct {
	char title[64];// stream title		char title[64]; // stream title
	char dj[64];		char dj[64];
	~~int~~ listeners;		int32 listeners;
	~~int~~ peak;		int32 peak;
	~~int~~ max;		int32 max;
	} STREAM_INFO;		} 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;
			bool is_request;
			char requested_by[64];

			int64_t playback_position;
			int64_t playback_length;
			} IBM_SONGINFO;

	==Command Classifications==		==Command Classifications==

Indy: /* Source Control Commands */

2014-04-10T04:07:08Z

Source Control Commands

← Older revision		Revision as of 04:07, 10 April 2014
Line 102:		Line 102:

	===Source Control Commands===		===Source Control Commands===
	Note: Not all [[Plugins#Source_Control_Plugins\|Source Plugins]] support all Source Control Commands!		Note: Not all [[Plugins#Source_Control_Plugins\|Source Plugins]] support all Source Control Commands!<br />
	{{rcom\|RCMD_SRC_COUNTDOWN\|0x30\|None}}		{{rcom\|RCMD_SRC_COUNTDOWN\|0x30\|None}}
	Makes the Source Plugin count you in, just like !autodj-stop		Makes the Source Plugin count you in, just like !autodj-stop

Indy: /* Login/Control Commands */

2013-11-14T00:42:52Z

New page

==Remote Protocol Overview==
Bot Protocol 1.7 
Latest 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 {{rcomlink|RCMD_GENERIC_MSG}} on success, or {{rcomlink|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 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===
{{rcom|RCMD_LOGIN|0x00|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 {{rcomlink|RCMD_ENABLE_SSL}} and {{rcomlink|RCMD_GET_VERSION}}, any other commands will be ignored until you are logged in. 
The bot will either: a) respond back with {{rcomlink|RCMD_LOGIN_OK}}, or b) respond back with {{rcomlink|RCMD_LOGIN_FAILED}} and an informational message.

{{rcom|RCMD_QUERY_STREAM|0x02|None}}
The bot will reply with {{rcomlink|RCMD_STREAM_INFO}}.

{{rcom|RCMD_ENABLE_SSL|0x03|None}}
The bot will either: a) respond back with {{rcomlink|RCMD_ENABLE_SSL_ACK}} and then call SSL_accept(), or b) reply with {{rcomlink|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.}}

{{rcom|RCMD_GET_VERSION|0x04|None}}
The bot will reply back with {{rcomlink|RCMD_IRCBOT_VERSION}} or {{rcomlink|RCMD_GENERIC_MSG}} if it is a v4 or previous bot that doesn't support the command.

===Request System Commands===
{{rcom|RCMD_REQ_LOGOUT|0x10|None}}
The bot will reply with {{rcomlink|RCMD_REQ_LOGOUT_ACK}} if you were the active DJ and were successfully logged out, or with {{rcomlink|RCMD_GENERIC_ERROR}} and an error message.

RCMD_REQ_LOGIN 
Hex Code: 0x11 
Data Sent with Command:
{| border="1" cellpadding="3" cellspacing="0"
|-
||v1-v4||None
|-
||v5||Optional - 1 byte - unsigned char with request options. Currently the only flag is 0x01 to enable [[Remote_Commands#Find_Support|@find Support]].
|}
The bot will reply with {{rcomlink|RCMD_REQ_LOGIN_ACK}} if you were successfully marked as the active DJ, or with {{rcomlink|RCMD_GENERIC_ERROR}} and an error message.

{{rcom|RCMD_REQ_CURRENT|0x12|None}}
The bot will reply with {{rcomlink|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 {{rcomlink|RCMD_GENERIC_ERROR}} and an error message.

{{rcom|RCMD_SEND_REQ|0x13|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>".

{{rcom|RCMD_REQ|0x14|The request text/filename}}
This will submit a request to the current DJ or AutoDJ.

{{rcom|RCMD_SEND_DED|0x15|The dedication text}}
This makes the bot send all the channels it is on dedication text like "This song is dedicated to <your text>".

{{rcom|RCMD_FIND_RESULTS|0x16|Protobuf RemoteFindResult}}
See [[Remote_Commands#Find Support|Find Support]] for more details.

===Misc Commands===
{{rcom|RCMD_DOSPAM|0x20|None}}
Toggles the global DoSpam flag.

{{rcom|RCMD_DIE|0x21|None}}
Kills the bot.

{{rcom|RCMD_BROADCAST_MSG|0x22|None}}
The bot will send the text you specify to all the channels it is on.

{{rcom|RCMD_RESTART|0x23|None}}
Restarts the bot.

{{rcom|RCMD_REHASH|0x26|None}}
Rehashes the bot.

===Source Control Commands===
Note: Not all [[Plugins#Source_Control_Plugins|Source Plugins]] support all Source Control Commands!
{{rcom|RCMD_SRC_COUNTDOWN|0x30|None}}
Makes the Source Plugin count you in, just like !autodj-stop

{{rcom|RCMD_SRC_FORCE_OFF|0x31|None}}
Makes the Source Plugin stop playing immediately, just like !autodj-force

{{rcom|RCMD_SRC_FORCE_ON|0x32|None}}
Makes the Source Plugin start playing immediately, just like !autodj-play

{{rcom|RCMD_SRC_NEXT|0x33|None}}
Makes the Source Plugin skip the current song, just like !next

{{rcom|RCMD_SRC_RELOAD|0x34|None}}
Scan for new songs, just like !autodj-reload

{{rcom|RCMD_SRC_GET_SONG|0x35|None}}
Replies with {{rcomlink|RCMD_GENERIC_MSG}} containing the filename of the song the Source Plugin is currently playing, or {{rcomlink|RCMD_GENERIC_ERROR}} if the Source Plugin isn't playing anything currently.

{{rcom|RCMD_SRC_RATE_SONG|0x36|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)

{{rcom|RCMD_SRC_STATUS|0x37|None}}
Replies with {{rcomlink|RCMD_GENERIC_MSG}} containing either "playing", "connecting", or "stopped" if a Source Plugin is loaded. Or {{rcomlink|RCMD_GENERIC_ERROR}} if one isn't.

{{rcom|RCMD_SRC_GET_NAME|0x38|None}}
Replies with {{rcomlink|RCMD_GENERIC_MSG}} containing the name of your source plugin (AutoDJ, SimpleDJ, SAM, etc.) if one is loaded. Or {{rcomlink|RCMD_GENERIC_ERROR}} if not.

===User Info/Sharing Commands===
{{rcom|RCMD_GETUSERINFO|0x40|A RadioBot username or hostmask}}
Replies with {{rcomlink|RCMD_USERINFO}} containing user info or {{rcomlink|RCMD_USERNOTFOUND}} if no matching user was found. This can also return a {{rcomlink|RCMD_GENERIC_ERROR}} if the user isn't a high enough level to use this command.

==Commands from Server to Client==
===Login/Control Commands===
{{rcom|RCMD_LOGIN_FAILED|0x00|An error message}}
Sent if you try to log in with an invalid user/pass or if there is another login error. (reply to {{rcomlink|RCMD_LOGIN}})

RCMD_LOGIN_OK 
Hex Code: 0x01 
Data Sent with Command:
{| border="1" cellpadding="3" cellspacing="0"
|-
||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 {{rcomlink|RCMD_LOGIN}})

{{rcom|RCMD_ENABLE_SSL_ACK|0x03|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.

{{rcom|RCMD_IRCBOT_VERSION|0x04|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===
{{rcom|RCMD_REQ_LOGOUT_ACK|0x10|None}}
Sent if you were logged out of the Request System successfully.

{{rcom|RCMD_REQ_LOGIN_ACK|0x11|None}}
Sent if you were logged in to the Request System successfully.

{{rcom|RCMD_REQ_INCOMING|0x12|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

{{rcom|RCMD_STREAM_INFO|0x13|A STREAM_INFO structure (see the Structures section above)}}
Reply to {{rcomlink|RCMD_QUERY_STREAM}}

{{rcom|RCMD_FIND_QUERY|0x14|Protobuf RemoteFindQuery}}
See [[Remote_Commands#Find Support|Find Support]] for more details.

===User Info/Sharing Commands===
{{rcom|RCMD_USERINFO|0x40|An IBM_USEREXTENDED structure}}
Reply to {{rcomlink|RCMD_GETUSERINFO}}

{{rcom|RCMD_USERNOTFOUND|0x41|None}}
Reply to {{rcomlink|RCMD_GETUSERINFO}}

===Generic Reply Commands===
{{rcom|RCMD_GENERIC_MSG|0xFE|A status message, usually indicating success. Put the text into a status box}}

{{rcom|RCMD_GENERIC_ERROR|0xFF|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 [https://code.google.com/p/protobuf/ Google Protocol Buffers]. 
The .proto file for @find support is [[File:remote_protobuf.proto|here]]. 
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. 

{{radiobot_programming}}