########################################################################## Quick and dirty documentation on nzbperl's remote control functions. For more information, please visit http://noisybox.net/computers/nzbperl/ ########################################################################## last updated on 8/16/2005 Intro: ~~~~~~ Remote control in nzbperl is accomplished by a simple client/server protocol that operates over TCP sockets. The remote control functions allow a client to obtain information about the current state of the server (nzbperl) and to control the behavior via commands. The primary goal of the remote control features is to facilitate 3rd party add-ons or [web based] UIs. For the purposes of this document, nzbperl should be considered the server, and any peer connecting to it should be considered the client. The CR/LF (carriage return linefeed) sequence may be represented as \r\n in the text below. Protocol: ~~~~~~~~~ With the exception of the server gretting message, all communication in the nzbperl remote control (NRC) protocol consist of a client request and a server response. A transaction consists of a single client request and a single server response, and all messages are in plaintext ASCII. When a TCP connection is first established, the server will send the greeting message. The greeting message is a single CR/LF terminated line in the form: nzbperl version \r\n where is the version of nzbperl running on the server. All remaining messages should follow the client/server request/response transaction model. All client requests consist of a single "line", where a "line" is defined as a series of standard ASCII characters followed by a CR/LF pair. All client command request lines should be in the form: [parameter parameter ..]\r\n Where is desired command and [parameter parameter ..] is 0 or more paramter strings. Obviously, parameters may not contain the CR/LF sequence. When the server receives a message, it will examine the first "word" of the message and interpret it as the "command". The remainder of the line will be considered parameters. Commands are *not* case sensitive, so PING should be handled the same as pINg. The server response message consists of a single line header followed by the message payload contents. The server response header is in the form: \r\n where is the ASCII representation of a decimal number that corresponds to the length of the message payload. It should be noted that this length value will include *all* bytes in the payload, including any \r\n combinations. All server responses will contain a terminating \r\n sequence for readability, and clients must not use the terminating \r\n for message delineation (the length value must be used instead). Sample session and transactions: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following sample session shows the nzbperl client/server protocol in action. Each line will be prefixed with a C: or S: to indicate client and server, respectively. Descriptive actions that are not part of the transaction are indicated in square brackets [shown like this]. Blank lines between transactions are only for readability. C: [connects to server] S: nzbperl version 0.6.6\r\n C: ping echo this message please\r\n S: 32\r\n S: PONG! echo this message please\r\n C: summary\r\n S: 387\r\n S: \r\n S: \r\n S: 0\r\n S: \r\n S: 70\r\n S: 575.85M\r\n S: \r\n S: 2\r\n S: \r\n S: 0\r\n S: 3.92M\r\n S: \r\n S: \r\n S: unlimited\r\n S: 115KBps\r\n S: 115KBps\r\n S: \r\n S: \r\n C: quit\r\n S: 17\r\n S: Nice having ya.\r\n S: [disconnects client] Security/Authentication: ~~~~~~~~~~~~~~~~~~~~~~~~ * NOTE: IN THE CURRENT FORM, THERE IS ABSOLUTELY NO SECURITY! * USE THESE FEATURES AT YOUR OWN RISK AND FIREWALL APPROPRIATELY! (a shared-secret challenge/response mechanism will likely be built later) Commands: ~~~~~~~~~ - ping [] The "ping" comamnd pings the server to ensure that it's still alive and listenting. It can be used as a simple heartbeat mechanism. Any message parameter will be echoed back to the client. - quit Tells the server that client wish to quit. The server will respond with an approval message and immediately close the client's connection. - keys Sends a series of keystrokes to nzbperl to be processed as though they were pressed at the console. can be any sequence of characters, and nzbperl will process them in order. - summary Asks nzbperl to send a summary document that provides an overview of the current status. The response is in XML format... TODO: Describe response document... - enqueue The enqueue command can be used to tell nzbperl to add another file to its queue of remaining nzb files to process. If nzbperl detects that the has already been processed, it will provide a negative response. Misc: ~~~~~ (This needs to be organized) All client requests are handled by the same thread that handles part downloading. As such, bandwidth throttling will effect the speed of client/server transactions. Similarly, client request processing will effect the download speed (although hopefully it's negligible).