NewsBin TCP Interface

Introduction
Connecting to the Interface
Command Summary
Command References
Copyright and Change History

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

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

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

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

Command	Description	Newsbin Versions
4.33B6/B8	5
BWL	Bandwidth Limiter	x	x
CLEAR	Clear Post List	x
CLOSE	Close	x
COMPRESS	Compress Spools	x
FILE	Load File	x	x
GetSection	Get INI file section		x
GetVar	Get INI file variable		x
PAUSE	Pause Downloads	x	x
QUIT	Close Connection	x	x
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

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

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

NewsBin TCP Interface

CONTENTS

^ INTRODUCTION

^ CONNECTING TO THE INTERFACE

^ COMMAND SUMMARY

^ COMMAND REFERENCE

BWL ON | OFF

CLEAR

CLOSE

COMPRESS

FILE \path\filename.ext

GetSection section <section>

GetVar section.name

PAUSE ON | OFF

SAVE

SetVar section:name:value

START

STOP

UPDATE [groupname]

^ COPYRIGHT and CHANGE HISTORY

Copyright

Change History

FILE `\path\filename.ext`

GetSection `section <section>`

GetVar `section.name`

SetVar `section:name:value`

UPDATE `[groupname]`