NewsBin TCP Interface

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: 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.


^ 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.

With Newsbin 4.33 only a single connection could be opened, but with Newsbin 5 this restriction has been lifted.

Succesful 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:

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 particualr commands.. More details on each command is given in the next section

Command Description Newsbin Versions
4.33B6/B8    5   
BWL Bandwidth Limiter xx
CLEAR Clear Post List x 
CLOSE Close x 
COMPRESS Compress Spools x 
FILE Load File xx
GetSection Get INI file section  x
GetVar Get INI file variable  x
PAUSE Pause Downloads xx
QUIT Close Connection xx
SetVar Set INI file variable  x
START Start Header Download x 
STOP Stop Header Download x 
UPDATE Update Headers  x


^ 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).

^


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

Clearing Post list and Memory

Returns:

200 Clear

^


CLOSE

Gracefully shuts down Newsbin, saves any current download list and configuration changes

Returns:

200 Newsbin Exiting ^

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. ^


FILE \path\filename.ext

Provide a .nzb or .bns filename and path. NewsBin will parse and load into the Post List.

Returns:

200 OK ^

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 ^

GetVar section.name

Newsbin 5 only

Returns a string that represents the configuration variable.

Example:

"Getvar nh:priority"
"Getvar nh:address"
Returns: ^

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

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 ^

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

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

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 [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

^


^ COPYRIGHT and CHANGE HISTORY

Copyright

This document is Copyright 2005 David J Walker

The Newsbin TCP Interface is Copyright 2004-2005 DJI Interprises, LLC. All rights reserved

Change History

The following is the history of changes:

Date Version Changes
July 2005 1.0 First Version
October 2005 1.1 Major update following Newsbin 5.0 reaching General Release status