IrateDev.ExternalControlProto History
Hide minor edits - Show changes to output
Changed lines 4-5 from:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported.
to:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. It has basic passwording support and the ability to only allow connections from localhost to allow a level of security.
Changed lines 16-17 from:
to:
* Robin - 30/3/2005: Added ''skiptounrated'' function
Added lines 113-117:
!!!Skip to the next unrated song
:type:''skiptounrated''
Skips to the next unrated song. The irate-client will respond with a trackinfo XML element of the new song. Skipping the player when it is paused will unpause it. If there are no unrated tracks on the playlist, then it behaves just like ''skip''.
Changed line 3 from:
!!!Robin Sheat - 17/9/2003 - First Draft
to:
!!!Robin Sheat
Changed line 46 from:
This is a more secure, but also more complex, method. The challenge returned by the irate-client will be a sequence of characters that should be appended to the plaintext password. This resulting string should then be hashed using [=MD5=], and sent.
to:
This is a more secure, but also more complex, method. The challenge returned by the irate-client will be a sequence of characters that should be appended to the plaintext password. This resulting string should then be hashed using [=MD5=], and sent. Note that the [=MD5=] is hex encoded, not base64 like is also common.
Changed line 49 from:
Four responses are valid from the irate-client.
to:
Four responses are valid from the irate-client, plus the same responses to invalid XML in the last section.
Added line 15:
* Robin - 21/8/2003: Added section on authorisation.
Changed line 22 from:
If passwords are turned off, then this section can be safely ignored. If a client wishes to determine if passwords are required, it should just issue any command. It will either get the expected reply, indicating no password is needed. Otherwise it will receive a ''password-required'' response (see below).
to:
If passwords are turned off, then this section can be safely ignored. If a client wishes to determine if passwords are required, it should just issue any command. It will either get the expected reply, indicating no password is needed. Otherwise it will receive a ''login-required'' response (see below).
Added lines 66-69:
!!!Login required
:type:''login-required''
This results from any command being issued without the ''type'' attribute being set to ''login''.
:type:''login-required''
This results from any command being issued without the ''type'' attribute being set to ''login''.
Added lines 24-25:
The XML element names are the same as defined below, ''Command'' for remote app -> irate-client, ''[=IrateClient=]'' for irate-client -> remote app communications.
Changed line 28 from:
!!Plaintext authorisation
to:
!!!Plaintext authorisation
Changed line 34 from:
!!Digest authorisation (MD5)
to:
!!!Digest authorisation ([=MD5=])
Changed lines 45-64 from:
This is a more secure, but also more complex, method. The challenge returned by the irate-client will be a sequence of characters that should be appended to the plaintext password. This resulting string should then be hashed using MD5, and sent.
to:
This is a more secure, but also more complex, method. The challenge returned by the irate-client will be a sequence of characters that should be appended to the plaintext password. This resulting string should then be hashed using [=MD5=], and sent.
!!!Authorisation responses
Four responses are valid from the irate-client.
!!!Login success
:type:''login-success''
After this, the remote app can begin using the commands below.
!!!Login failure
:type:''login-failure''
Generally an incorrect password. The connection will be dropped after this is sent.
!!!Login protocol error
:type:''login-protocol-error''
This is sent if the irate-client gets confused by the input. Something along the lines of a digest password getting sent without a challenge, or a challenge being requested twice will cause this. The connection will be dropped after this.
!!!Format not implemented
:type:''login-format-not-implemented''
This is sent to allow future extension of the login method. It is sent if the ''format'' attribute contains an unknown string. The irate-client treats this as though nothing happened, allowing the remote app to try a different method.
!!!Authorisation responses
Four responses are valid from the irate-client.
!!!Login success
:type:''login-success''
After this, the remote app can begin using the commands below.
!!!Login failure
:type:''login-failure''
Generally an incorrect password. The connection will be dropped after this is sent.
!!!Login protocol error
:type:''login-protocol-error''
This is sent if the irate-client gets confused by the input. Something along the lines of a digest password getting sent without a challenge, or a challenge being requested twice will cause this. The connection will be dropped after this.
!!!Format not implemented
:type:''login-format-not-implemented''
This is sent to allow future extension of the login method. It is sent if the ''format'' attribute contains an unknown string. The irate-client treats this as though nothing happened, allowing the remote app to try a different method.
Added lines 19-44:
!!Authorisation
Because there may be times when you don't want everyone to be able to mess with your player, but you do want to be able to remote control it, we need an authorisation system, in this case, password-based.
If passwords are turned off, then this section can be safely ignored. If a client wishes to determine if passwords are required, it should just issue any command. It will either get the expected reply, indicating no password is needed. Otherwise it will receive a ''password-required'' response (see below).
There are two types of login: plaintext and digest.
!!Plaintext authorisation
:type:''login''
:format:''plaintext''
:password:the plaintext password
This is suitable for use in basic scripts, where you don't want to play around with challenge/response, but is less secure. The login XML is simply:
!!Digest authorisation (MD5)
:type:''login''
:format:''digest-md5-getchallenge''
This should be the first request. The irate-client will reply with:
:type:''login-challenge''
:challenge:a string of characters
The remote app should respond with:
:type:''login''
:format:''digest-md5''
:password:the hashed password and challenge as defined below.
This is a more secure, but also more complex, method. The challenge returned by the irate-client will be a sequence of characters that should be appended to the plaintext password. This resulting string should then be hashed using MD5, and sent.
Because there may be times when you don't want everyone to be able to mess with your player, but you do want to be able to remote control it, we need an authorisation system, in this case, password-based.
If passwords are turned off, then this section can be safely ignored. If a client wishes to determine if passwords are required, it should just issue any command. It will either get the expected reply, indicating no password is needed. Otherwise it will receive a ''password-required'' response (see below).
There are two types of login: plaintext and digest.
!!Plaintext authorisation
:type:''login''
:format:''plaintext''
:password:the plaintext password
This is suitable for use in basic scripts, where you don't want to play around with challenge/response, but is less secure. The login XML is simply:
!!Digest authorisation (MD5)
:type:''login''
:format:''digest-md5-getchallenge''
This should be the first request. The irate-client will reply with:
:type:''login-challenge''
:challenge:a string of characters
The remote app should respond with:
:type:''login''
:format:''digest-md5''
:password:the hashed password and challenge as defined below.
This is a more secure, but also more complex, method. The challenge returned by the irate-client will be a sequence of characters that should be appended to the plaintext password. This resulting string should then be hashed using MD5, and sent.
Changed line 4 from:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported. Also, at this stage only one simultanious connection is permitted, as this can lead to a [=DoS=] of the plugin, this will probably change eventually.
to:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported.
Added line 14:
* Robin - 20/8/2003: Added ''invert-pause'', removed comment about one connection at a time, as it is no longer true.
Added lines 51-55:
!!!Toggle pause
:type:''invert-pause''
Toggles the paused state of the player.
:type:''invert-pause''
Toggles the paused state of the player.
Changed line 71 from:
All responses have the XML name ''IrateClient''.
to:
All responses have the XML name ''[=IrateClient=]''.
Changed line 13 from:
* Robin - 19/8/2003: Added link to test program.
to:
* Robin - 19/8/2003: Added link to test program, changed the XML element cases to match the rest of iRATE. ['''Note:''' This may break existing programs.]. Fixed a documentation bug regarding the XML element name for responses.
Changed line 21 from:
All commands have the XML name ''command''.
to:
All commands have the XML name ''Command''.
Changed line 71 from:
All responses have the XML name ''irate''.
to:
All responses have the XML name ''IrateClient''.
Changed line 8 from:
A Perl test program for this can be found [[Attach:irate-control.pl here]]. It provides a reference for other programs.
to:
A Perl test program for this can be found [[Attach:irate-control-pl here]]. It provides a reference for other programs.
Changed line 8 from:
A Perl test program for this can be found [[attach:irate-control.pl here]]. It provides a reference for other programs.
to:
A Perl test program for this can be found [[Attach:irate-control.pl here]]. It provides a reference for other programs.
Changed lines 6-7 from:
'''''Robin: Until all the security things are in, it will probably be locked to localhost, after that it will default to it, but allow being opened up.'''''
to:
For the purposes of this, the two components are labled irate-client (effectively the server in this situation), and remote app (effectively the client).
Changed line 8 from:
to:
A Perl test program for this can be found [[attach:irate-control.pl here]]. It provides a reference for other programs.
Changed lines 12-13 from:
* Robin - 18/8/2003: Added notes on reponses to improper XML, disconnect command
to:
* Robin - 18/8/2003: Added notes on reponses to improper XML, disconnect command, plugin added to iRATE CVS.
* Robin - 19/8/2003: Added link to test program.
* Robin - 19/8/2003: Added link to test program.
Changed lines 53-54 from:
Skips to the next song. The irate-client will respond with a trackinfo XML element of the new song. '''''[What happens if you skip a paused player? Does it unpause?]'''''
to:
Skips to the next song. The irate-client will respond with a trackinfo XML element of the new song. Skipping the player when it is paused will unpause it.
Changed line 13 from:
* Robin - 18/8/2003: Added notes on reponses to improper XML
to:
* Robin - 18/8/2003: Added notes on reponses to improper XML, disconnect command
Added lines 67-70:
!!!Disconnect
:type:''disconnect''
A polite way of requesting a disconnect. Generally has the same effect as just dropping the connection, but nicer. The irate-client silently closes the connection.
:type:''disconnect''
A polite way of requesting a disconnect. Generally has the same effect as just dropping the connection, but nicer. The irate-client silently closes the connection.
Added lines 11-14:
!!Revision History:
* Robin - 17/8/2003: First draft
* Robin - 18/8/2003: Added notes on reponses to improper XML
* Robin - 17/8/2003: First draft
* Robin - 18/8/2003: Added notes on reponses to improper XML
Added lines 85-102:
!!Invalid commands
If invalid XML (i.e. something that is not really XML), or an XML element with an invalid name is received, an invalid-command XML response is sent, and the connection is broken.
If an XML element with a correct name, but invalid command is received, an unknown-command response is sent, and the connection remains open.
In these, the ''fatal'' attribute tells the client whether or not the connection will be broken. Not strictly necessary, but polite.
!!!Invalid-command response
:type:''error''
:errorcondition:''invalid-command''
:fatal:''1''
Connection dropped.
!!!Unknown-command response
:type:''error''
:errorcondition:''unknown-command''
:fatal:''0''
Connection not dropped.
If invalid XML (i.e. something that is not really XML), or an XML element with an invalid name is received, an invalid-command XML response is sent, and the connection is broken.
If an XML element with a correct name, but invalid command is received, an unknown-command response is sent, and the connection remains open.
In these, the ''fatal'' attribute tells the client whether or not the connection will be broken. Not strictly necessary, but polite.
!!!Invalid-command response
:type:''error''
:errorcondition:''invalid-command''
:fatal:''1''
Connection dropped.
!!!Unknown-command response
:type:''error''
:errorcondition:''unknown-command''
:fatal:''0''
Connection not dropped.
Changed line 4 from:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported. Also, at this stage only one simultanious connection is permitted, as this can lead to a DoS of the plugin, this will probably change eventually.
to:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported. Also, at this stage only one simultanious connection is permitted, as this can lead to a [=DoS=] of the plugin, this will probably change eventually.
Changed line 7 from:
'''''Until all the security things are in, it will probably be locked to localhost, after that it will default to it, but allow being opened up.'''''
to:
'''''Robin: Until all the security things are in, it will probably be locked to localhost, after that it will default to it, but allow being opened up.'''''
Changed lines 6-7 from:
Taras: We should also check hostname of incoming ip to be "localhost".
to:
'''''Taras: We should also check hostname of incoming ip to be "localhost".'''''[[<<]]
'''''Until all the security things are in, it will probably be locked to localhost, after that it will default to it, but allow being opened up.'''''
'''''Until all the security things are in, it will probably be locked to localhost, after that it will default to it, but allow being opened up.'''''
Added lines 6-7:
Taras: We should also check hostname of incoming ip to be "localhost".
Changed line 74 from:
This returns the above information on the track, which is in response to the requests above. Note that this packet is not send automatically on events such as track change. The client should query every so often if it requires that information. This may change in the future.
to:
This returns the above information on the track, which is in response to the requests above. Note that this packet is not send automatically on events such as track change. The remote app should query every so often if it requires that information. This may change in the future.
Changed line 4 from:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported. Also, at this stage only one simultanious connection is permitted, as this can lead to a DoS of the plugin, this will probably change eventually also.
to:
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported. Also, at this stage only one simultanious connection is permitted, as this can lead to a DoS of the plugin, this will probably change eventually.
Changed line 3 from:
!!!Robin Sheat - 17/9/2003
to:
!!!Robin Sheat - 17/9/2003 - First Draft
Changed line 14 from:
All commands have the XML name ```command'''.
to:
All commands have the XML name ''command''.
Changed lines 1-77 from:
to:
![[http://irate.sf.net iRATE]] External Control Plugin
!!Protocol definition
!!!Robin Sheat - 17/9/2003
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported. Also, at this stage only one simultanious connection is permitted, as this can lead to a DoS of the plugin, this will probably change eventually also.
For the purposes of this, the two components are labled irate-client (effectively the server in this situation), and remote app (effectively the client).
!!Connection
The default port that the plugin listens on is 12473. The remote app connects on this port.
!!Commands from the remote app
Once connected, the remote app sends a command to the irate-client. Presently there is no situation where the irate-client will send anything to the remote app unsolicited.
All commands have the XML name ```command'''.
The following lists the attribute names and the value they should be set to to specify the request.
!!!Request current track info
:type:''currenttrack''
The irate-client will respond with a trackinfo XML element detailing the currently playing track. This is documented below.
!!!Request player state
:type:''playerstate''
The irate-client will respond with a playerstate XML element.
!!!Request selected track info
:type:''selectedtrack''
The irate-client will respond with a trackinfo XML element detailing the track that is selected in the UI. In some players, this is always the same as the currently playing track.
!!!Pause the player
:type:''pause''
Pauses playback. No reponse from the irate-client
!!!Unpause the player
:type:''unpause''
Unpauses playback. Note that neither this nor the pause function are toggles. Pausing an already paused player has no effect.
!!!Skip to the next song
:type:''skip''
Skips to the next song. The irate-client will respond with a trackinfo XML element of the new song. '''''[What happens if you skip a paused player? Does it unpause?]'''''
!!!Set rating of playing track
:type:''rateplaying''
:rate:An integer from 0 to 10
Sets the rating of the currently playing track. As this may cause the current track information to change, a trackinfo XML element is returned containing the currently playing track.
!!!Set rating of selected track
:type:''rateselected''
:rate:An integer from 0 to 10
Sets the rating of the currently selected track. A trackinfo XML element is returned that contains the '''currently selected track'''. Note that this may also cause the playing track to change. It is up to the remote app to update itself of that.
!!Irate-client responses
All responses have the XML name ''irate''.
!!!Track info
:type:''trackinfo''
:source:''selected'', ''playing'', or empty.
:title:string containing the track title
:artist:string containing the track artist
:url:string containing the URL the file was downloaded from
:filename:the filename iRATE uses to access the file
:state:the state of the file: ''Broken'', ''Not Downloaded'', ''Missing'', ''Unrated'', or its rating
:rating:the actual rating
:numtimes:number of times played
:lastplayed:when it was last played
This returns the above information on the track, which is in response to the requests above. Note that this packet is not send automatically on events such as track change. The client should query every so often if it requires that information. This may change in the future.
!!!Player state
:type:''playerstate''
:play:1 if playing, 0 if paused.
!!Protocol definition
!!!Robin Sheat - 17/9/2003
The protocol is an XML based protocol to allow for extensibility, and to match the rest of iRATE. As it stands, this protocol is experimental. There is no security inherent in the program. I recommend only using it on a firewalled machine. Eventually, passwording and binding to a specific interface will be supported. Also, at this stage only one simultanious connection is permitted, as this can lead to a DoS of the plugin, this will probably change eventually also.
For the purposes of this, the two components are labled irate-client (effectively the server in this situation), and remote app (effectively the client).
!!Connection
The default port that the plugin listens on is 12473. The remote app connects on this port.
!!Commands from the remote app
Once connected, the remote app sends a command to the irate-client. Presently there is no situation where the irate-client will send anything to the remote app unsolicited.
All commands have the XML name ```command'''.
The following lists the attribute names and the value they should be set to to specify the request.
!!!Request current track info
:type:''currenttrack''
The irate-client will respond with a trackinfo XML element detailing the currently playing track. This is documented below.
!!!Request player state
:type:''playerstate''
The irate-client will respond with a playerstate XML element.
!!!Request selected track info
:type:''selectedtrack''
The irate-client will respond with a trackinfo XML element detailing the track that is selected in the UI. In some players, this is always the same as the currently playing track.
!!!Pause the player
:type:''pause''
Pauses playback. No reponse from the irate-client
!!!Unpause the player
:type:''unpause''
Unpauses playback. Note that neither this nor the pause function are toggles. Pausing an already paused player has no effect.
!!!Skip to the next song
:type:''skip''
Skips to the next song. The irate-client will respond with a trackinfo XML element of the new song. '''''[What happens if you skip a paused player? Does it unpause?]'''''
!!!Set rating of playing track
:type:''rateplaying''
:rate:An integer from 0 to 10
Sets the rating of the currently playing track. As this may cause the current track information to change, a trackinfo XML element is returned containing the currently playing track.
!!!Set rating of selected track
:type:''rateselected''
:rate:An integer from 0 to 10
Sets the rating of the currently selected track. A trackinfo XML element is returned that contains the '''currently selected track'''. Note that this may also cause the playing track to change. It is up to the remote app to update itself of that.
!!Irate-client responses
All responses have the XML name ''irate''.
!!!Track info
:type:''trackinfo''
:source:''selected'', ''playing'', or empty.
:title:string containing the track title
:artist:string containing the track artist
:url:string containing the URL the file was downloaded from
:filename:the filename iRATE uses to access the file
:state:the state of the file: ''Broken'', ''Not Downloaded'', ''Missing'', ''Unrated'', or its rating
:rating:the actual rating
:numtimes:number of times played
:lastplayed:when it was last played
This returns the above information on the track, which is in response to the requests above. Note that this packet is not send automatically on events such as track change. The client should query every so often if it requires that information. This may change in the future.
!!!Player state
:type:''playerstate''
:play:1 if playing, 0 if paused.
Page last modified on March 20, 2005, at 03:06 PM