From NNTPGrab

This document describes how any frontend can communicate to the backend over raw sockets. This makes it possible to control the NNTPGrab backend from another host.

The NNTPGrab Core listens on port 5423/tcp.

After making a connection to this port, the NNTPGrab Core replies with the following welcome message:

NNTPGrab Server - API version 20090505 

(where 20090505 is the version number of the protocol. This should match the clients expectations)

The documentation on this wiki is all based on API version 20090505

The NNTPGrab protocol is a line based protocol. Every command should end with the newline character (\n).

When connecting, the client should send one of the following commands before further communication is possible:

MODE LISTENER or MODE COMMAND 

The server should return the following response:

OK 

After this command, the socket is either broadcasting all the signals coming from the NNTPGrab Core or awaiting commands.

When an invalid command is entered, the server will send the response:

INVALID COMMAND 

Contents 1 MODE COMMAND 1.1 CONFIG_GET_AVAIL_SERVERS 1.2 CONFIG_GET_SERVER_INFO 1.3 CONFIG_ADD_SERVER 1.4 CONFIG_DEL_SERVER 1.5 CONFIG_EDIT_SERVER 1.6 CONFIG_GET_OPTS 1.7 CONFIG_SET_OPTS 1.8 CONFIG_GET_FOLDER_LISTING 1.9 SCHEDULAR_START 1.10 SCHEDULAR_STOP 1.11 SCHEDULAR_GET_STATE 1.12 SCHEDULAR_ADD_TASK_TO_QUEUE 1.13 SCHEDULAR_DEL_TASK_FROM_QUEUE 1.14 SCHEDULAR_RESTART_TASK 1.15 SCHEDULAR_SAVE_QUEUE 1.16 SCHEDULAR_FOREACH_TASK 1.17 SCHEDULAR_MOVE_TASK 1.18 SCHEDULAR_MOVE_COLLECTION 2 MODE LISTENER 2.1 CONFIG_CHANGED 2.2 PART_DOWNLOAD_START 2.3 PART_DONE 2.4 PART_FAILED 2.5 TRAFFIC_MONITOR_UPDATE 2.6 PART_PROGRESS_UPDATE 2.7 COLLECTION_ADDED 2.8 COLLECTION_REMOVED 2.9 COLLECTION_MODIFIED 2.10 FILE_ADDED 2.11 FILE_REMOVED 2.12 FILE_DOWNLOAD_STATE_UPDATE 2.13 FILE_STATE_CHANGED 2.14 CONNECTION_CONNECTING 2.15 CONNECTION_CONNECTED 2.16 CONNECTION_DISCONNECT 2.17 SCHEDULAR_STATE_CHANGED 2.18 FATAL_ERROR 2.19 WARNING_MESSAGE 2.20 DEBUG_MESSAGE 2.21 TASK_MOVED 2.22 COLLECTION_MOVED 2.23 PAR2_REPAIR_MESSAGE 2.24 ALL_DOWNLOADS_COMPLETED 2.25 UNPACK_PROGRESS_UPDATE 2.26 UNPACK_MESSAGE_RECEIVED 2.27 UNPACK_WORKING_ARCHIVE_CHANGED 2.28 PAR2_BEGIN_VERIFY 2.29 PAR2_LOAD_PROGRESS_UPDATE 2.30 PAR2_RECOVERY_FILE_LOADED 2.31 PAR2_FILE_LOADED 2.32 PAR2_REPAIR_PROGRESS_UPDATE 2.33 PAR2_REPAIR_FAILURE 2.34 PAR2_REPAIR_SUCCESS 2.35 PAR2_NO_REPAIR_REQUIRED

MODE COMMAND

CONFIG_GET_AVAIL_SERVERS

Returns a list of all the available usenet servers.

Notation:

CONFIG_GET_AVAIL_SERVERS

Response:

NULL

Example:

> CONFIG_GET_AVAIL_SERVERS
< NewsZilla
< NULL

CONFIG_GET_SERVER_INFO

Retrieve information about a specific usenet server. Returns NULL when the given servername isn't found

Notation:

CONFIG_GET_SERVER_INFO 

Response:

NULL
or









NULL

Example:

> CONFIG_GET_SERVER_INFO NewsZilla
< NewsZilla
< newszilla.xs4all.nl
< 119
< 
< 
< 3
< 1
< FALSE
< TRUE
< NULL

CONFIG_ADD_SERVER

Add a new usenet server Returns FALSE when the servername already exists

Notation:

CONFIG_ADD_SERVER \t\t\t\t\t\t\t\t

Response:

TRUE
or
FALSE

Example:

> CONFIG_ADD_SERVER NewsZilla   newszilla.xs4all.nl     119                     3       1       FALSE   TRUE
< TRUE

CONFIG_DEL_SERVER

Remove a usenet server Returns FALSE when the servername isn't known

Notation:

CONFIG_DEL_SERVER 

Response:

TRUE
or
FALSE

Example:

> CONFIG_DEL_SERVER NewsZilla
< TRUE

CONFIG_EDIT_SERVER

Changes the settings of a usenet server Returns FALSE when the servername isn't known

Notation:

CONFIG_EDIT_SERVER \t\t\t\t\t\t\t\t\t

Response:

TRUE
or
FALSE

Example:

> CONFIG_EDIT_SERVER NewsZilla  NewsZilla_IPV6  newszilla6.xs4all.nl    119     my_username     my_pass 3       1       FALSE   TRUE
< TRUE

CONFIG_GET_OPTS

Retrieves the global settings of the NNTPGrab Core

Notation:

CONFIG_GET_OPTS

Response:

NULL

Example:

> CONFIG_GET_OPTS
< /home/test/NNTPGrab/Downloads
< /home/test/NNTPGrab/Temp
< FALSE
< TRUE
< TRUE
< /home/test/NNTPGrab/NZB
< TRUE
< TRUE
< NULL

CONFIG_SET_OPTS

Changes the global settings of the NNTPGrab Core Returns FALSE when one of the new settings are invalid

Notation:

CONFIG_SET_OPTS \t\t\t\t\t\t\t

Response:

TRUE
or
FALSE

Example:

> CONFIG_SET_OPTS /home/test/NNTPGrab/Downloads /home/test/NNTPGrab/Temp        FALSE   TRUE    TRUE    /home/test/NNTPGrab/NZB FALSE   TRUE
< TRUE

CONFIG_GET_FOLDER_LISTING

Retrieves a list containing all the sub-folders which are in the given folder. Each result also contains a TRUE or FALSE mentioning if the sub-folders itself contains sub-folders

Notation:

CONFIG_GET_FOLDER_LISTING 

Response:

FALSE
or
NULL
or
folder1\tTRUE
folderX\tFALSE
NULL

Example:

> CONFIG_GET_FOLDER_LISTING /
< bin        FALSE
< etc        TRUE
< proc       TRUE
< sbin       FALSE
< usr        TRUE
< var        TRUE
< NULL

SCHEDULAR_START

Start the NNTPGrab schedular Returns FALSE when the schedular is already running

Notation:

SCHEDULAR_START

Response:

TRUE
or
FALSE

Example:

> SCHEDULAR_START
< TRUE

SCHEDULAR_STOP

Stop the NNTPGrab schedular Returns FALSE when the schedular is already stopped

Notation:

SCHEDULAR_STOP 

Response:

TRUE
or
FALSE

Example:

> SCHEDULAR_STOP TRUE
< TRUE

SCHEDULAR_GET_STATE

Retrieves the current state of the schedular

Notation:

SCHEDULAR_GET_STATE

Response:

RUNNING
or
STOPPING
or
STOPPED

Example:

> SCHEDULAR_GET_STATE
< STOPPED

SCHEDULAR_ADD_TASK_TO_QUEUE

Add a new task (file) to the download queue When a file contains multiple groups or multiple parts, these need to be split using the | character A part needs to be in the notation ,, The file size is mentioned in bytes and the stamp is an unix timestamp

Notation:

SCHEDULAR_ADD_TASK_TO_QUEUE \t\t\t\t\t\t

Response:

TRUE
or
FALSE 

Example:

> SCHEDULAR_ADD_TASK_TO_QUEUE my collection     my subject      some poster     1199389869      123456789       alt.binaries.boneless|alt.binaries.nl   ,1,500|,2,250
< FALSE The file already exists in the download queue

SCHEDULAR_DEL_TASK_FROM_QUEUE

Removes a task from the download queue

Notation:

SCHEDULAR_DEL_TASK_FROM_QUEUE \t

Response:

TRUE
or
FALSE 

Example:

> SCHEDULAR_DEL_TASK_FROM_QUEUE my collection   my subject
< TRUE

SCHEDULAR_RESTART_TASK

Restarts a task already present in the download queue

Notation:

SCHEDULAR_RESTART_TASK \t

Response:

TRUE
or
FALSE 

Example:

> SCHEDULAR_RESTART my collection       some other subject
< FALSE File is not present in the given collection

SCHEDULAR_SAVE_QUEUE

Saves the download queue. This needs to be done after added new files to the download queue

Notation:

SCHEDULAR_SAVE_QUEUE

Response:

TRUE
or
FALSE 

Example:

> SCHEDULAR_SAVE_QUEUE
< TRUE

SCHEDULAR_FOREACH_TASK

Returns all the collections and tasks present in the download queue

Notation:

SCHEDULAR_FOREACH_TASK

Response:

COLLECTION \t\t\t
\tFILE \t\t\t\t\t\t\t\t\t\t
(this list can be returned multiple times)
NULL

Possible status'es:

WAITING_FOR_DOWNLOAD
DOWNLOADING
WAITING_FOR_DECODE
DECODING
FINISHED_COMPLETE
FINISHED_INCOMPLETE
FINISHED_NO_PARTS_AVAIL
SKIPPED

Example:

> SCHEDULAR_FOREACH_TASK
< COLLECTION my collection   12345678        100     3
<    FILE my_subject some_poster     1199389869      0       1234567 1       100     10      0       WAITING_FOR_DOWNLOAD    alt.binaries.boneless|alt.binaries.nl
<    FILE some_other_subject some poster     1199389900      100     565432  2       50      0       0       alt.binaries.x
< COLLECTION some other collection   626832  200
<    FILE another subject    another poster  1199331624      1583632 200     1       10      0       0       alt.binaries.x
< NULL

SCHEDULAR_MOVE_TASK

Change the position and/or location of a task in the download queue. The collection_name_src can be the same as collection_name_dest. If the position is -1, the file will be added to the end of the queue. If subject is empty, then the position will mean the position of all the collections in the download queue.

Notation:

SCHEDULAR_MOVE_TASK \t\t\t

Response:

TRUE
or
FALSE

Example, change the position of a task within the same collection:

> SCHEDULAR_MOVE_TASK my collection     my subject      my collection   5
< TRUE

Example, move the task to another collection

> SCHEDULAR_MOVE_TASK my collection     my subject      another collection      -1
< FALSE

SCHEDULAR_MOVE_COLLECTION

Change the position of a collection in the download queue. If the new_position is -1, the collection will be moved to the end of the queue.

Notation:

SCHEDULAR_MOVE_COLLECTION \t

Response:

TRUE
or
FALSE

Example

> SCHEDULAR_MOVE_COLLECTION my collection       -1
< TRUE

MODE LISTENER

While in the listener mode, all signals coming from the NNTPGrab Core are automatically broadcasted on the socket. These are the possible messages which the NNTPGrab Core can send.

CONFIG_CHANGED

Something in the configuration has changed

CONFIG_CHANGED

PART_DOWNLOAD_START

The download of a part has just started

PART_DOWNLOAD_START \t\t\t\t

PART_DONE

The download of a part has completed successfully

PART_DONE \t\t\t\t\t

PART_FAILED

The download of a part has failed (probably because the part isn't available on the server

PART_FAILED \t\t\t\t\t\t

TRAFFIC_MONITOR_UPDATE

Every second, traffic statistics about the last 10 seconds are given

TRAFFIC_MONITOR_UPDATE \t\t\t\t\t\t\t\t\t\t\t

PART_PROGRESS_UPDATE

Every 10KB of a part download, this message will be sent

PART_PROGRESS_UPDATE \t\t\t\t\t

COLLECTION_ADDED

A new collection was added

COLLECTION_ADDED \t

COLLECTION_REMOVED

A collection was removed

COLLECTION_REMOVED 

COLLECTION_MODIFIED

The poster of a collection was modified

COLLECTION_MODIFIED \t

FILE_ADDED

A file was added to a already existing collection. The argument is a list of newsgroups, separated by the | character

FILE_ADDED \t\t\t\t\t\t\t

FILE_REMOVED

A file was removed from the download queue

FILE_REMOVED \t\t\t

FILE_DOWNLOAD_STATE_UPDATE

The state of a file in the download queue has changed

FILE_DOWNLOAD_STATE_UPDATE \t\t\t\t\t\tt\t\t

FILE_STATE_CHANGED

A file in the download queue was restarted

FILE_STATE_CHANGED \t\t\t\t

CONNECTION_CONNECTING

A new connection is being made to a usenet server

CONNECTION_CONNECTING \t

CONNECTION_CONNECTED

A connection attempt has succeeded

CONNECTION_CONNECTED \t\t

CONNECTION_DISCONNECT

A connection to a usenet server was disconnected

CONNECTION_DISCONNECT \t\t\t

disconnect_type can be any of the following values:

NORMAL
NO_SUCH_HOST
CONNECTION_REFUSED
TOO_MANY_CONNECTIONS
CONNECT_TIMEOUT
READ_ERROR
READ_TIMEOUT
WRITE_ERROR
IDLE_TIMEOUT
INVALID_MSG
LOGIN_FAILURE
ERROR_SSL_INITIALISE
UNEXPECTED

SCHEDULAR_STATE_CHANGED

The state of the schedular has changed

SCHEDULAR_STATE_CHANGED \t

FATAL_ERROR

A fatal error has occured

FATAL_ERROR 

WARNING_MESSAGE

A warning has occured

WARNING_MESSAGE 

DEBUG_MESSAGE

A debug message has been emitted

DEBUG_MESSAGE 

TASK_MOVED

The position of a task in the download queue has changed

TASK_MOVED \t\t\t\t

COLLECTION_MOVED

The position of a collection in the download queue has changed

COLLECTION_MOVED \t\t

PAR2_REPAIR_MESSAGE

The PAR2 repair component has emit a message which can be shown to the user

PAR2_REPAIR_MESSAGE 

ALL_DOWNLOADS_COMPLETED

This message is emit when all the items in the download queue are completed

ALL_DOWNLOADS_COMPLETED

UNPACK_PROGRESS_UPDATE

The unpack component has made some progress

UNPACK_PROGRESS_UPDATE \t\t

UNPACK_MESSAGE_RECEIVED

The unpack component has emit a message. This message mostly is the file which is currently extracted

UNPACK_MESSAGE_RECEIVED \t\t

UNPACK_WORKING_ARCHIVE_CHANGED

The unpack component is now unpacking from a new archive file

UNPACK_WORKING_ARCHIVE_CHANGED \t\t

PAR2_BEGIN_VERIFY

A PAR2 verification (and if necessary repair) has just started

PAR2_BEGIN_VERIFY \t

PAR2_LOAD_PROGRESS_UPDATE

A file is now being verified

PAR2_LOAD_PROGRESS_UPDATE \t\t\t

PAR2_RECOVERY_FILE_LOADED

A PAR2 recovery file has been loaded completely

PAR2_RECOVERY_FILE_LOADED \t\t\t\t

PAR2_FILE_LOADED

A regular file has been loaded completely

PAR2_FILE_LOADED \t\t\t\t\t

The field state can be one of the following values:

MISSING
FOUND
DAMAGED
NO_NEW_BLOCKS_FOUND

PAR2_REPAIR_PROGRESS_UPDATE

A PAR2 repair is now going on

PAR2_REPAIR_PROGRESS_UPDATE \t\t

PAR2_REPAIR_FAILURE

The PAR2 repair has failed because there aren't enough recovery blocks available

PAR2_REPAIR_FAILURE \t\t

PAR2_REPAIR_SUCCESS

The PAR2 repair has completed successfully

PAR2_REPAIR_SUCCESS \t

PAR2_NO_REPAIR_REQUIRED

All the files in the PAR2 set have been verified and no repair is necessary

PAR2_NO_REPAIR_REQUIRED \t