V600-TCP Interface
From Newsbin
Version 6 TCP Interface
Track discussion on expanding the interface in the Discussion Tab
Contents |
Introduction
The Newsbin TCP Command Interface is designed to provide a method for allowing external programs to control certain aspects of Newsbin operation. The selection of TCP as the interface mechanism was for a number of reasons:
- It could be done without programs needing to know any details of the Newsbin internal structure.
- It was independent of any particular programming language
- It was easy to implement!
The Newsbin TCP Command Interface was first introduced in the Newsbin 4.33 series, and the first stable version was in Newsbin 4.33B6. The Newsbin 5 series also supports this interface, although some of the commands supported are different to reflect the way that Newsbin 5 operates. It is also intended that Newsbin 5 will eventually support a much richer command set than the Newsbin 4.33 series.
Significant enhancements are being considered for Version 6 for potential remote control from iPhone, iPad, and Android devices, as well as remote computers.
Connecting to the Interface
NewsBin listens on port 118 on localhost (127.0.0.1). It is not accessible to any process not running directly on your computer.
To connect from an application external to the host machine, a tunneling program needs to be running. A simple open source program is available here. For encrypting your connections, WinSSHD is a good SSH Server that is free for non-commercial personal use.
Successful commands have a 200 return. Errors have a 400 status return.
The easiest way to connect to this interface to see how it works is to:
Go to the Start Menu Select the option run a Command Prompt Type in the command "TELNET 127.0.0.1 118" (without the quotes) and press OK This should start up the Windows Telnet client and result in a message of the form: 200 Newsbin Server being displayed. At this point you can type in commands and see what happens.
Command Summary
The following is a summary list of the commands, and an indication of which versions of newsbin support particular commands. More details on each command is given in the next section.
| Command | Implemented | Proposed | Description |
|---|---|---|---|
| BWL | X | Bandwidth Limiter | |
| CLEAR | X | Clear Post List | |
| CLOSE | X | Close | |
| COMPRESS | X | Compress Spools | |
| FILE | X | Load File | |
| GetSection | X | Get INI file section | |
| GetVar | X | Get INI file variable | |
| PAUSE | X | Pause Downloads | |
| QUIT | X | Close Connection | |
| SetVar | X | Set INI file variable | |
| START | X | Start Header Download | |
| STOP | X | Stop Header Download | |
| UPDATE | X | Update Headers | |
| Downloads | X | New commands for remote administration. Switches include Clear, Count, List, Lock, Unlock. Read more on forum |
Command Reference
Commands are not case sensitive. They are entered using standard DOS/Windows conventions for end of line (CR/LF) (also often written as /r/n). All commands return a response code followed by descriptive text. As far as the response codes are concerned, then anything 400 or higher is an error. Good results will range from 200-299 though only 200 is used today.
The following is a full list of the commands available in alphabetical order. Where a particular command is only available with specific version of Newsbin this is indicated. Any item that is enclosed in square brackets is optional. Items separated by the '|' character indicates alternatives. Items in italics are logical items (e.g. variable names).
Bandwidth Limiter
Command: BWL [ON|OFF]
Turn bandwidth limiter on or off. If the bandwidth liniter is already in the state you have requested then the command will have no effect. Returns:
200 BW Limiter On 200 BW Limiter Off
Clear
Command: CLEAR
Clearing Post list and Memory
Returns:
200 Clear
Close
Command: CLOSE
Gracefully shuts down Newsbin, saves any current download list and configuration changes
Returns:
200 Newsbin Exiting
Compress
Command: COMPRESS
Newsbin 4.33B6/B8 only Compress all spools. Note that in this context the term "Compress" simply means remove any wasted space or headers that have expired. If you are using NTFS filing system it can still be advantageous to turn on Windows level compression which will typically reduce the space occupied by headers by 50% or more. Would allow external app to initiate auto compress at 4:00am or something.
Returns: DIR>200 Compress Started Then proceeds to list progress i.e. Server: newserver - newsgroup" for each server and each group that has any previously downloaded headers in the spool files.y downloaded headers in the spool files.
Import NZB File
Command: FILE [\path\filename.ext]
Provide a .NZB filename and path. Newsbin will parse and load into the Post List.
Returns:
200 OK
Get NBI Section
Command: GetSection [section <section>]
Newsbin 5 only Returns a section of the NBI. The basic format of a good response will always be: 200 Section List Follows contents of the section . So a command of the form: GetSection Servers might return data of the form: 200 Section List Follows NTLWorld Astraweb Astraweb_Europe Giganews Giganews2 Astraweb_Test If you type an invalid section name, then the response will be: 401 GetSection - Section not Found
Get NBI Variable
Command: GetVar [section.name]
Newsbin 5 only Returns a string that represents the configuration variable. Example:
"Getvar nh:priority" "Getvar nh:address" Returns:
Pause
Command: PAUSE [ON|OFF]
Pause downloads queued in the Download List. With Newsbin 4 the files are paused immediately. With Newsbin 5 each download thread is paused when it completes the current chunk it is working on so it can be several seconds before the pause takes full effect..
Returns:
200 Download Paused 200 Download Resumed
Save Configuration
Commnad: SAVE
Newsbin 5 only Saves the configuration file. This would typically be used after using a series of SetVar commands to store or update values in the configuration file.
Returns:
200 Config Saved
Set NBI Variable
Command: SetVar [section:name:value]
Newsbin 5 only Lets you set any individual value in the current Newsbin configuration (.NBI) file Example: "SetVar nh:address:test.newshosting.com"
You aren't limited to existing sections either. If you want to store your own variables in the NBI you can.
"SetVar Itimpi:saveinterval:50" "Save"
"GetVar Itimpi:saveinterval" The format of the results is: NNN Text\r\n value1\r\n value2\r\n ... .\r\n GetVar will only return one result, setvar returns nothing but the response.
Start
Command: START
Newsbin 4.33B6/B8 only Same as hitting the start button. Starts header download in manual mode or starts header and file download in automatic mode. Works on all groups in the group list with a check mark next to it.
Returns:
200 START
Stop
Command: STOP
Newsbin 4.33B6/B8 only Same as hitting the stop button. Stops and header downloads that is in progress. Does notaffect any file downloads.
Returns:
200 Stop
Update
Commnad: UPDATE [groupname]
Newsbin 5 only Updates the headers for all enabled groups if no groupname specified, and the specified group if groupname is given
Returns:
200 Header Update Commencing
Downloads
This is one of the new commands to remotely manage the your downloads.
Downloads Lock is to be used before making changes to the list, otherwise the index might change between performing List command and necessary actions. Lock also freezes the GUI until the Unlock command is performed.
Downloads Clear is used to clear the downloads list if you must.
Downloads Count is used to get a total count of unexpanded sets or files.
Downloads List # # is used to get the list of unexpanded sets or files. The first # is the lowest number to show, starting with 0. The second # is the highest number line to show, not to exceed the value of sets returned from the Count command minus 1 becuase the index starts at 0 (zero).
Downloads Unlock is used to unlock the list after making changes to list, and also unfreeze the Newsbin GUI.
More TCP commands are still planned for implementation. A list of proposed features can be read here or discussed here.
Change History
The following is the history of changes:
| Date | Version | Change Description |
|---|---|---|
| July 2005 | 1.0 | First Version by Itimpi (Copyright © 2005 David J Walker, used with permission) |
| October 2005 | 1.1 | Major update following Newsbin 5.0 reaching General Release status |
| February 2011 | 2.0 | Copy from Itimpi's original document. Begin brainstorming expanded functionality |
