RPC API reference

From NZBGet
Jump to: navigation, search

Contents

About XML-RPC and JSON-RPC in NZBGet

Status of this document

The document describes methods available in NZBGet version 13.0 and later. The document is updated after a new stable version is out. Current testing version may have methods or fields not described here; these methods or fields may change before getting stable. If you need information for older NZBGet version please see a historical article RPC API reference 0.6.0-12.0.

Protocols

NZBGet supports XML-RPC, JSON-RPC and JSON-P-RPC. RPC-protocols allow to control the program from other applications. Many programming languages have libraries, which make the usage of XML-RPC, JSON-RPC and JSON-P-RPC very simple. The implementations of all three protocols in NZBGet are equal: all methods are identical. You may choose the protocol, which is better supported by your programming language.

The RPC server uses HTTP basic authentication with username and password from server's configuration file. The URL would be something like:

If HTTP basic authentication is somewhat problematic the username/password can also be passed in the URL as the first part of the path:

Security warning: HTTP authentication is not secure. Although the password is encoded using Base64 it is not encrypted. For secure communication use HTTPS (needs to be explicitly enabled in NZBGet settings by user).

Features and limitations

  • Multicalls are supported for XML-RPC and not supported for JSON-RPC.
  • Introspection is not supported.
  • Only positional parameters are supported in JSON-RPC. Named parameters are not supported. Therefore parameter names are ignored but the order of parameters is important. All parameters are mandatory.
  • Each call to JSON-P-RPC has one additional parameter - the name of callback-function. This parameter must be named "callback" and must be passed first (before any other parameters).
  • 64 bit integers are returned in two separate fields Hi and Lo (for example FileSizeHi and FileSizeLo). These fields are unsigned 32 bit integers. Although dynamic languages such as PHP or Python have no problems with these fields the XML-RPC specification does not allow unsigned integers. This may cause troubles in statically typed languages such as Java or C++ if XML-RPC-parser expects only signed integers in 32 bit range. As a solution use JSON-RPC instead (which does allow unsigned integers) instead of XML-RPC.

Program control

Method "version"

Signature:

string version() 

Request the version-string of the program.

Return value: Version string.

Method "shutdown"

Signature:

bool shutdown() 

Shutdown the program.

Return value: Always "True".

Method "reload"

Signature:

bool reload() 

Stop all activities and reinitialize the program. This method must be called after changing of program options for them to have effect.

Return value: Always "True".

Queue and history

Method "listgroups"

Signature:

struct[] listgroups(int NumberOfLogEntries) 

Request for list of downloads (nzb-files). This method returns summary information for each group (nzb-file).

Parameters:

  • NumberOfLogEntries - 15.0 Number of post-processing log-entries (field Log), which should be returned for the top (currently processing) item in post-processing state. Deprecated, must be 0.

Return value: This method returns an array of structures with following fields:

Field Type Description
NZBID int ID of NZB-file.
FirstID int 13.0 Deprecated, use NZBID instead.
LastID int 13.0 Deprecated, use NZBID instead.
NZBFilename string Name of nzb-file, this file was added to queue from. The filename could include fullpath (if client sent it by adding the file to queue).
NZBName string The name of nzb-file without path and extension. Ready for user-friendly output.
NZBNicename string 13.0 Deprecated, use NZBName instead.
Kind string Kind of queue entry: NZB or URL.
URL string URL where the NZB-file was fetched (Kind=NZB) or should be fetched (Kind=URL).
DestDir string Destination directory for output file.
FinalDir string Final destination if set by one of post-processing scripts. Can be set only for items in post-processing state.
Category string Category for group or empty string if none category is assigned.
FileSizeLo int Initial size of all files in group in bytes, Low 32-bits of 64-bit value.
FileSizeHi int Initial size of all files in group in bytes, High 32-bits of 64-bit value.
FileSizeMB int Initial size of all files in group in megabytes.
RemainingSizeLo int Remaining size of all (remaining) files in group in bytes, Low 32-bits of 64-bit value.
RemainingSizeHi int Remaining size of all (remaining) files in group in bytes, High 32-bits of 64-bit value.
RemainingSizeMB int Remaining size of all (remaining) files in group in megabytes.
PausedSizeLo int Size of all paused files in group in bytes, Low 32-bits of 64-bit value.
PausedSizeHi int Size of all paused files in group in bytes, High 32-bits of 64-bit value.
PausedSizeMB int Size of all paused files in group in megabytes.
FileCount int Initial number of files in group.
RemainingFileCount int Remaining (current) number of files in group.
RemainingParCount int Remaining (current) number of par-files in group.
MinPostTime int Date/time when the oldest file in the group was posted to newsgroup (Time is in C/Unix format).
MaxPostTime int Date/time when the newest file in the group was posted to newsgroup (Time is in C/Unix format).
MinPriority int 13.0 Deprecated, use MaxPriority instead.
MaxPriority int Priority of the group. "Max" in the field name has historical reasons.
ActiveDownloads int Number of active downloads in the group. With this filed can be determined what group(s) is (are) being currently downloaded. In most cases only one group is downloaded at a time however more that one group can be downloaded simultaneously when the first group is almost completely downloaded.
Status string Status of the group:
  • QUEUED - queued for download;
  • PAUSED - paused;
  • DOWNLOADING - item is being downloaded;
  • FETCHING - nzb-file is being fetched from URL (Kind=URL);
  • PP_QUEUED - queued for post-processing (completely downloaded);
  • LOADING_PARS - stage of par-check;
  • VERIFYING_SOURCES - stage of par-check;
  • REPAIRING - stage of par-check;
  • VERIFYING_REPAIRED - stage of par-check;
  • RENAMING - processed by par-renamer;
  • UNPACKING - being unpacked;
  • MOVING - moving files from intermediate directory into destination directory;
  • EXECUTING_SCRIPT - executing post-processing script;
  • PP_FINISHED - post-processing is finished, the item is about to be moved to history.
TotalArticles int Total number of articles in all files of the group.
SuccessArticles int Number of successfully downloaded articles.
FailedArticles int Number of failed article downloads.
Health int Current health of the group, in permille. 1000 means 100.0%. The health can go down below this valued during download if more article fails. It can never increase (unless merging of groups). Higher values are better. See forum topic Download health monitoring.
CriticalHealth int Calculated critical health of the group, in permille. 1000 means 100.0%. The critical health is calculated based on the number and size of par-files. Lower values are better.
DownloadedSizeLo int 14.0 Amount of downloaded data for group in bytes, Low 32-bits of 64-bit value.
DownloadedSizeHi int 14.0 Amount of downloaded data for group in bytes, High 32-bits of 64-bit value.
DownloadedSizeMB int 14.0 Amount of downloaded data for group in megabytes.
MessageCount int 15.0 Number of messages stored in the item log. Messages can be retrieved with method loadlog.
DupeKey string Duplicate key. See RSS#Duplicates.
DupeScore int Duplicate score. See RSS#Duplicates.
DupeMode string Duplicate mode. One of SCORE, ALL, FORCE. See RSS#Duplicates.
Parameters array Post-processing parameters for group. See below.
Deleted bool 12.0 Deprecated, use DeleteStatus instead.
ServerStats array Per news-server download statistics. For description see method #history.
ParStatus, UnpackStatus, MoveStatus, ScriptStatus, DeleteStatus, MarkStatus, ScriptStatuses, PostTotalTimeSec, ParTimeSec, RepairTimeSec, UnpackTimeSec string These fields have meaning only for a group which is being currently post-processed. For description see method #history.
PostInfoText string Text with short description of current action in post processor. For example: "Verifying file myfile.rar". Only for a group which is being currently post-processed.
PostStageProgress int Completing of current stage. A number in the range 0..1000. Divide it to 10 to get percent-value. Only for a group which is being currently post-processed.
PostTotalTimeSec int Number of seconds this post-job is being processed (after it first changed the state from PP-QUEUED). Only for a group which is being currently post-processed.
PostStageTimeSec int Number of seconds the current stage is being processed. Only for a group which is being currently post-processed.
Log array 15.0 Array of structs with log-messages. For description of struct see method log. Only for a group which is being currently post-processed. The number of returned entries is limited by parameter NumberOfLogEntries. Deprecated, use method loadlog instead.

Field Parameters is an array of structures with following fields:

Field Type Description
Name string Name of post-processing parameter.
Value string Value of post-processing parameter.

Method "listfiles"

Signature:

struct[] listfiles(int IDFrom, int IDTo, int NZBID) 

Request for file's list of a group (nzb-file).

Parameters:

  • IDFrom - 12.0 Deprecated, must be 0.
  • IDTo - 12.0 Deprecated, must be 0.
  • NZBID - NZBID of the group to be returned.

To get the list of all files from all groups set all parameters to 0.

Return value: This method returns an array of structures with following fields:

Field Type Description
ID int ID of file.
NZBID int ID of NZB-file.
NZBFilename string Name of nzb-file. The filename could include fullpath (if client sent it by adding the file to queue).
NZBName string The name of nzb-file without path and extension. Ready for user-friendly output.
NZBNicename string 12.0 Deprecated, use NZBName instead.
Subject string Subject of article (read from nzb-file).
Filename string Filename parsed from subject. It could be incorrect since the subject not always correct formated. After the first article for file is read, the correct filename is read from article body.
FilenameConfirmed bool "True" if filename was already read from article's body. "False" if the name was parsed from subject. For confirmed filenames the destination file on disk will be exactly as specified in field "filename". For unconfirmed filenames the name could change later.
DestDir string Destination directory for output file.
FileSizeLo int Filesize in bytes, Low 32-bits of 64-bit value.
FileSizeHi int Filesize in bytes, High 32-bits of 64-bit value.
RemainingSizeLo int Remaining size in bytes, Low 32-bits of 64-bit value.
RemainingSizeHi int Remaining size in bytes, High 32-bits of 64-bit value.
Paused bool "True" if file is paused.
PostTime int Date/time when the file was posted to newsgroup (Time is in C/Unix format).
Priority int 13.0 Deprecated, use MaxPriority of the group (method listgroups) instead.
ActiveDownloads int Number of active downloads for the file. With this filed can be determined what file(s) is (are) being currently downloaded.
Progress int 15.0 Download progress, a number in the range 0..1000. Divide it to 10 to get percent-value.

Method "history"

Signature:

struct[] history(bool Hidden) 

Request for list of items in history-list.

Parameters:

  • Hidden - Also return hidden history records. Use this only if you need to see the old (hidden) history records (Kind=DUP). Normal (unhidden) records are always returned.

Return value: This method returns an array of structures with following fields:

Field Type Description
NZBID int ID of NZB-file.
ID int 13.0 Deprecated, use NZBID instead.
Kind string Kind of history item. One of the predefined text constants:
  • NZB for nzb-files;
  • URL for failed URL downloads;
  • DUP for hidden history items.

NOTE: successful URL-downloads result in adding files to download queue, a success-history-item is not created in this case.

NZBFilename string Name of nzb-file, this file was added to queue from. The filename could include fullpath (if client sent it by adding the file to queue).
Name string The name of nzb-file or info-name of URL, without path and extension. Ready for user-friendly output.
NZBNicename string 12.0 Deprecated, use Name instead.
URL string URL.
HistoryTime int Date/time when the file was added to history (Time is in C/Unix format).
DestDir string Destination directory for output files.
FinalDir string Final destination if set by one of post-processing scripts. Can be set only for items in post-processing state.
Category string Category for group or empty string if none category is assigned.
FileSizeLo int Initial size of all files in group in bytes, Low 32-bits of 64-bit value.
FileSizeHi int Initial size of all files in group in bytes, High 32-bits of 64-bit value.
FileSizeMB int Initial size of all files in group in megabytes.
FileCount int Initial number of files in group.
RemainingFileCount int Number of parked files in group. If this number is greater than "0", the history item can be returned to download queue using command "HistoryReturn" of method "editqueue".
MinPostTime int Date/time when the oldest file in the item was posted to newsgroup (Time is in C/Unix format).
MaxPostTime int Date/time when the newest file in the item was posted to newsgroup (Time is in C/Unix format).
TotalArticles int Total number of articles in all files of the group.
SuccessArticles int Number of successfully downloaded articles.
FailedArticles int Number of failed article downloads.
Health int Final health of the group, in permille. 1000 means 100.0%. Higher values are better. See forum topic Download health monitoring.
DownloadedSizeLo int 14.0 Amount of downloaded data for group in bytes, Low 32-bits of 64-bit value.
DownloadedSizeHi int 14.0 Amount of downloaded data for group in bytes, High 32-bits of 64-bit value.
DownloadedSizeMB int 14.0 Amount of downloaded data for group in megabytes.
PostTotalTimeSec int 14.0 Total post-processing time in seconds.
ParTimeSec int 14.0 Par-check time in seconds (incl. verification and repair).
RepairTimeSec int 14.0 Par-repair time in seconds.
UnpackTimeSec int 14.0 Unpack time in seconds.
MessageCount int 15.0 Number of messages stored in the item log. Messages can be retrieved with method loadlog.
DupeKey string Duplicate key. See RSS#Duplicates.
DupeScore int Duplicate score. See RSS#Duplicates.
DupeMode string Duplicate mode. One of SCORE, ALL, FORCE. See RSS#Duplicates.
Status string Total status of the download. One of the predefined text constants such as SUCCESS/ALL or FAILURE/UNPACK, etc. For the complete list see below.
ParStatus string Result of par-check/repair:
  • NONE - par-check wasn't performed;
  • FAILURE - par-check has failed;
  • REPAIR_POSSIBLE - download is damaged, additional par-files were downloaded but the download was not repaired. Either the option ParRepair is disabled or the par-repair was cancelled by option ParTimeLimit;
  • SUCCESS - par-check was successful;
  • MANUAL - download is damaged but was not checked/repaired because option ParCheck is set to Manual.
UnpackStatus string Result of unpack:
  • NONE - unpack wasn't performed, either no archive files were found or the unpack is disabled for that download or globally;
  • FAILURE - unpack has failed;
  • SPACE - unpack has failed due to not enough disk space;
  • PASSWORD - unpack has failed because the password was not provided or was wrong. Only for rar5-archives;
  • SUCCESS - unpack was successful.
UrlStatus string Result of URL-download:
  • NONE - that nzb-file were not fetched from an URL;
  • SUCCESS - that nzb-file was fetched from an URL;
  • FAILURE - the fetching of the URL has failed.
  • SCAN_SKIPPED - The URL was fetched successfully but downloaded file was not nzb-file and was skipped by the scanner;
  • SCAN_FAILURE - The URL was fetched successfully but an error occurred during scanning of the downloaded file. The downloaded file isn't a proper nzb-file. This status usually means the web-server has returned an error page (HTML page) instead of the nzb-file.
ScriptStatus string Accumulated result of all post-processing scripts. One of the predefined text constants: NONE, FAILURE, SUCCESS. Also see field ScriptStatuses.
ScriptStatuses array Status info of each post-processing script. See below.
MoveStatus string Result of moving files from intermediate directory into final directory:
  • NONE - the moving wasn't made because either the option InterDir is not in use or the par-check or unpack have failed;
  • SUCCESS - files were moved successfully;
  • FAILURE - the moving has failed.
DeleteStatus string Indicates if the download was deleted:
  • NONE - not deleted;
  • MANUAL - the download was manually deleted by user;
  • HEALTH- the download was deleted by health check;
  • DUPE - the download was deleted by duplicate check.
  • BAD - 14.0 the download was marked as BAD by a queue-script during download.
MarkStatus string Indicates if the download was marked by user:
  • NONE - not marked;
  • GOOD - the download was marked as good by user using command Mark as good in history dialog;
  • BAD - the download was marked as bad by user using command Mark as bad in history dialog;
Parameters array Post-processing parameters for group. For description of struct see method listgroups.
ServerStats array Per-server article completion statistics. See below.
Log array 13.0 Deprecated, was never really used.

Field Status

Field Status can be set to one of the following values:

  • For history items with Kind=NZB:
Status Description
FAILURE/BAD The download was marked as bad by user using command Mark as bad in history dialog.
SUCCESS/GOOD The download was marked as good by user using command Mark as good in history dialog.
SUCCESS/MARK 15.0 The download was marked as success by user using command Mark as success in history dialog.
DELETED/MANUAL The download was manually deleted by user.
DELETED/DUPE The download was deleted by duplicate check.
FAILURE/PAR The par-check has failed.
FAILURE/UNPACK The unpack has failed and there are no par-files.
FAILURE/MOVE An error has occurred when moving files from intermediate directory into the final destination directory.
WARNING/DAMAGED Par-check is required but is disabled in settings (option ParCheck=Manual).
WARNING/REPAIRABLE Par-check has detected a damage and has downloaded additional par-files but the repair is disabled in settings (option ParRepair=no).
FAILURE/HEALTH Download health is below critical health. No par-check was made (there are no par-files or the download was aborted by health check). No unpack was made (there are no archive files or unpack was disabled for that download or globally or the download was aborted by health check).
WARNING/HEALTH Download health is below 100.0%. No par-check was made (there are no par-files). No unpack was made (there are no archive files or unpack was disabled for that download or globally).
SUCCESS/HEALTH Download was successful, download health is 100.0%. No par-check was made (there are no par-files). No unpack was made (there are no archive files or unpack was disabled for that download or globally).
WARNING/SPACE Unpack has failed due to not enough space on the drive.
WARNING/PASSWORD Unpack has failed because the password was not provided or was wrong.
SUCCESS/ALL Downloaded and par-checked or unpacked successfully. All post-processing scripts were successful. The download is completely OK.
SUCCESS/UNPACK Similar to SUCCESS/ALL but no post-processing scripts were executed. Downloaded and unpacked successfully. Par-check was successful or was not necessary.
SUCCESS/PAR Similar to SUCCESS/ALL but no post-processing scripts were executed. Downloaded and par-checked successfully. No unpack was made (there are no archive files or unpack was disabled for that download or globally).
WARNING/SCRIPT Downloaded successfully. Par-check and unpack were either successful or were not performed. At least one of the post-processing scripts has failed.
  • For history items with Kind=URL:
Status Description
DELETED/MANUAL The download was manually deleted by user.
DELETED/DUPE The download was deleted by duplicate check.
FAILURE/FETCH Fetching of the URL has failed.
WARNING/SKIPPED The URL was fetched successfully but downloaded file was not nzb-file and was skipped by the scanner.
FAILURE/SCAN The URL was fetched successfully but an error occurred during scanning of the downloaded file. The downloaded file isn't a proper nzb-file. This status usually means the web-server has returned an error page (HTML page) instead of the nzb-file.
  • For history items with Kind=DUP:
Status Description
SUCCESS/HIDDEN The hidden history item has status SUCCESS.
FAILURE/HIDDEN The hidden history item has status FAILURE.
DELETED/MANUAL The download was manually deleted by user.
DELETED/DUPE The download was deleted by duplicate check.
FAILURE/BAD The download was marked as bad by user using command Mark as bad in history dialog.
SUCCESS/GOOD The download was marked as good by user using command Mark as good in history dialog.

Method "append"

Signature:

int append(string NZBFilename, string NZBContent, string Category, int Priority, bool AddToTop,
      bool AddPaused, string DupeKey, int DupeScore, string DupeMode)

Add nzb-file or URL to download queue.

Parameters:

  • NZBFilename - name of nzb-file. Server uses the name to build destination directory. This name can contain full path or only filename.
  • Content - content of nzb-file encoded with Base64 (see #Examples) or URL to fetch nzb-file from.
  • Category - category for nzb-file. Can be empty string.
  • Priority - priority for nzb-file. 0 for "normal priority", positive values for high priority and negative values for low priority. Downloads with priorities equal to or greater than 900 are downloaded and post-processed even if the program is in paused state (force mode). Default priorities are: -100 (very low), -50 (low), 0 (normal), 50 (high), 100 (very high), 900 (force).
  • AddToTop - "True" if the file should be added to the top of the download queue or "False" if to the end.
  • AddPaused - "True" if the file should be added in paused state.
  • DupeKey - duplicate key for nzb-file. See RSS#Duplicates.
  • DupeScore - duplicate score for nzb-file. See RSS#Duplicates.
  • DupeMode - duplicate mode for nzb-file. See RSS#Duplicates.

Return value: Positive number representing NZBID of the queue item. 0 and negative numbers represent error codes. Current version uses only error code 0, newer versions may use other error codes for detailed information about error.

Method "editqueue"

Signature:

bool editqueue(string Command, int Offset, string EditText, int[] IDs) 

Edit items in download queue or in history.

Parameters:

  • Command - one of the following commands:
Command Description
FileMoveOffset Move files to Offset relative to the current position in queue.
FileMoveTop Move files to top of queue.
FileMoveBottom Move files to bottom of queue.
FilePause Pause files.
FileResume Resume (unpause) files.
FileDelete Delete files.
FilePauseAllPars Pause only pars (does not affect other files).
FilePauseExtraPars Pause only pars, except main par-file (does not affect other files).
FileSetPriority 13.0 Deprecated, use GroupSetPriority instead.
FileReorder Reorder files in the group. The list of IDs may include files only from one group.
FileSplit Split nzb-file. The list of IDs contains the files to move into new download item.
GroupMoveOffset Move groups to Offset relative to the current position in queue.
GroupMoveTop Move groups to top of queue.
GroupMoveBottom Move groups to bottom of queue.
GroupPause Pause groups.
GroupResume Resume (unpause) groups.
GroupDelete Delete groups and put to history.
GroupDupeDelete Delete groups, put to history and mark as duplicate.
GroupFinalDelete Delete groups without adding to history.
GroupPauseAllPars Pause only pars (does not affect other files).
GroupPauseExtraPars Pause only pars, except main par-file (does not affect other files).
GroupSetPriority Set priority for all files in group. EditText contains priority value.
GroupSetCategory Set category for group. EditText contains category name.
GroupApplyCategory Set or change category for groups and reassign pp-params according to category settings. EditText contains category name.
GroupMerge Merge groups.
GroupSetParameter Set post-processing parameter for group. EditText contains string in form of Paramname=Paramvalue.
GroupSetName Rename group. EditText contains new name.
GroupSetDupeKey Set duplicate key. EditText contains duplicate key. See RSS#Duplicates.
GroupSetDupeScore Set duplicate score. EditText contains duplicate score. See RSS#Duplicates.
GroupSetDupeMode Set duplicate mode. EditText contains one of SCORE, ALL, FORCE. See RSS#Duplicates.
GroupSort 15.0 Sort selected or all groups. Parameter EditText must be one of: name, priority, category, size, left; add character + or - to sort to explicitly define ascending or descending order (for example name-); if none of these characters is used the auto-mode is active: the items are sorted in ascending order first, if nothing changed - they are sorted again in descending order. Parameter IDs contains the list of groups to sort; pass empty array to sort all groups.
PostMoveOffset 13.0 Deprecated, use GroupMoveOffset instead.
PostMoveTop 13.0 Deprecated, use GroupMoveTop instead.
PostMoveBottom 13.0 Deprecated, use GroupMoveBottom instead.
PostDelete Delete post-jobs.
HistoryDelete Hide history items (mark as hidden).
HistoryFinalDelete Delete history items.
HistoryReturn Return history items back to download queue.
HistoryProcess Post-process history items again.
HistoryRedownload Move history items back to download queue for redownload.
HistorySetName 15.0 Rename history item. EditText contains new name.
HistorySetCategory 15.0 Set category for history item. EditText contains category name.
HistorySetParameter Set post-processing parameter for history items. EditText contains string in form of Paramname=Paramvalue.
HistorySetDupeKey Set duplicate key. EditText contains duplicate key. See RSS#Duplicates.
HistorySetDupeScore Set duplicate score. EditText contains duplicate score. See RSS#Duplicates.
HistorySetDupeMode Set duplicate mode. EditText contains one of SCORE, ALL, FORCE. See RSS#Duplicates.
HistorySetDupeBackup Set use as duplicate backup-flag for history items. EditText contains 0 or 1. See RSS#Duplicates.
HistoryMarkBad Mark history item as bad (and download other duplicate). See RSS#Duplicates.
HistoryMarkBad Mark history item as good. See RSS#Duplicates.
HistoryMarkSuccess 15.0 Mark history item as success. See RSS#Duplicates.
  • Offset - offset for commands FileMoveOffset and GroupMoveOffset. For all other commands must be "0".
  • EditText - additional parameter if mentioned in the command description, otherwise an empty string.
  • IDs - array of IDs (as integers).
    • File-commands (FileXXX) need ID of file.
    • All other commands need NZBID.

Return value: "True" on success or "False" on failure.

Method "scan"

Signature:

bool scan() 

Request rescanning of incoming directory for nzb-files.

Return value: Always "True".

Status, logging and statistics

Method "status"

Signature:

struct status() 

Request for current status (summary) information.

Return value: This method returns a structure with following fields:

Field Type Description
RemainingSizeLo int Remaining size of all entries in download queue, in bytes. This field contains the low 32-bits of 64-bit value
RemainingSizeHi int Remaining size of all entries in download queue, in bytes. This field contains the high 32-bits of 64-bit value
RemainingSizeMB int Remaining size of all entries in download queue, in megabytes.
ForcedSizeLo int Remaining size of entries with FORCE priority, in bytes. This field contains the low 32-bits of 64-bit value
ForcedSizeHi int Remaining size of entries with FORCE priority, in bytes. This field contains the high 32-bits of 64-bit value
ForcedSizeMB int Remaining size of entries with FORCE priority, in megabytes.
DownloadedSizeLo int Amount of data downloaded since server start, in bytes. This field contains the low 32-bits of 64-bit value
DownloadedSizeHi int Amount of data downloaded since server start, in bytes. This field contains the high 32-bits of 64-bit value
DownloadedSizeMB int Amount of data downloaded since server start, in megabytes.
ArticleCacheLo int 14.0 Current usage of article cache, in bytes. This field contains the low 32-bits of 64-bit value
ArticleCacheHi int 14.0 Current usage of article cache, in bytes. This field contains the high 32-bits of 64-bit value
ArticleCacheMB int 14.0 Current usage of article cache, in megabytes.
DownloadRate int Current download speed, in Bytes per Second.
AverageDownloadRate int Average download speed since server start, in Bytes per Second.
DownloadLimit int Current download limit, in Bytes per Second. The limit can be changed via method "rate". Be aware of different scales used by the method rate (Kilobytes) and this field (Bytes).
ThreadCount int Number of threads running. It includes all threads, created by the program, not only download-threads.
PostJobCount int Number of Par-Jobs or Post-processing script jobs in the post-processing queue (including current file).
ParJobCount int 12.0 Deprecated, use PostJobCount instead.
UrlCount int Number of URLs in the URL-queue (including current file).
UpTimeSec int Server uptime in seconds.
DownloadTimeSec int Server download time in seconds.
ServerStandBy bool "False" - there are currently downloads running, "True" - no downloads in progress (server paused or all jobs completed).
DownloadPaused bool "True" if download queue is paused via first pause register (soft-pause).
Download2Paused bool 13.0 Deprecated, use DownloadPaused instead.
ServerPaused bool 12.0 Deprecated, use DownloadPaused instead.
PostPaused bool "True" if post-processor queue is currently in paused-state.
ScanPaused bool "True" if the scanning of incoming nzb-directory is currently in paused-state.
ServerTime int Current time on computer running NZBGet. Time is in C/Unix format (number of seconds since 00:00:00 UTC, January 1, 1970).
ResumeTime int Time to resume if set with method "scheduleresume". Time is in C/Unix format.
FeedActive bool "True" if any RSS feed is being fetched right now.
FreeDiskSpaceLo int Free disk space on DestDir, in bytes. This field contains the low 32-bits of 64-bit value
FreeDiskSpaceHi int Free disk space on DestDir, in bytes. This field contains the high 32-bits of 64-bit value
FreeDiskSpaceMB int Free disk space on DestDir, in megabytes.
NewsServers array Status of news-servers. See below.

Field NewsServers is an array of structures with following fields:

Field Type Description
ID int Server number in the configuration file. For example "1" for server defined by options "Server1.Host", "Server1.Port", etc.
Active bool True if server is in active state (enabled). Active doesn't mean that the data is being downloaded from the server right now. This only means the server can be used for download (if there are any download jobs).

Method "log"

Signature:

struct[] log(int IDFrom, int NumberOfEntries) 

This method returns entries from server's screenlog-buffer. The size of this buffer is limited and can be set via option "LogBufferSize" in server's configuration file. Which messages should be saved to screenlog and which should be saved to log-file can be set via server's options InfoTarget, WarningTarget, ErrorTarget and DebugTarget in server's configuration file.

Parameters:

  • IDFrom - The first ID to be returned.
  • NumberOfEntries - Number of entries, which should be returned.

NOTE: only one parameter - either IDFrom or NumberOfEntries - can be specified. The other parameter must be "0".

TIP: If your application stores log-entries between sub-sequential calls to method log(), the usage of parameter IDFrom is recommended, since it reduces the amount of transferred data.

Return value: This method returns an array of structures with following fields:

Field Type Description
ID int ID of log-entry.
Kind string Class of log-entry, one of the following strings: INFO, WARNING, ERROR, DEBUG.
Time int Time in C/Unix format (number of seconds since 00:00:00 UTC, January 1, 1970).
Text string Log-message.

NOTE: if there are no entries for requested criteria, an empty array is returned.

Method "writelog"

Signature:

bool writelog(string Kind, string Text) 

Append log-entry into server's log.

Parameters:

  • Kind - Kind of log-message. Must be one of the following strings: INFO, WARNING, ERROR, DETAIL, DEBUG. Debug-messages are processed by server, only if it was compiled in debug-mode.
  • Text - Text to be added into log.

Return value: Always "True".

Method "loadlog"

15.0 Signature:

struct[] log(in NZBID, int IDFrom, int NumberOfEntries) 

Loads from disk and returns nzb-log for a specific nzb-file.

Parameters:

  • NZBID - id of nzb-file.

For other parameters and return values see method log.

Method "servervolumes"

Signature:

struct[] servervolumes()

Download volume statistics per news-servers.

TODO

Method "resetservervolume"

Signature:

bool resetservervolume(int serverid, string counter);

Reset download volume statistics for a specified news-server.

TODO

Pause and speed limit

Method "rate"

Signature:

bool rate(int Limit) 

Set download speed limit.

Parameters:

  • Limit - new download speed limit in KBytes/second. Value "0" disables speed throttling.

Return value: "True" on success or "False" on failure.

Method "pausedownload"

Signature:

bool pausedownload() 

Pause download queue on server.

Return value: Always "True".

Method "resumedownload"

Signature:

bool resumedownload() 

Resume (previously paused) download queue on server.

Return value: Always "True".

Method "pausepost"

Signature:

bool pausepost() 

Pause post-processing.

Return value: Always "True".

Method "resumepost"

Signature:

bool resumepost() 

Resume (previously paused) post-processing.

Return value: Always "True".

Method "pausescan"

Signature:

bool pausescan() 

Pause scanning of directory with incoming nzb-files.

Return value: Always "True".

Method "resumescan"

Signature:

bool resumescan() 

Resume (previously paused) scanning of directory with incoming nzb-files.

Return value: Always "True".

Method "scheduleresume"

Signature:

bool scheduleresume(int Seconds) 

Schedule resuming of all activities after expiring of wait interval.

Parameters:

  • Seconds - amount of seconds to wait before resuming.

Method "scheduleresume" activates a wait timer. When the timer fires all pausable activities resume: download, post-processing and scan of incoming directory. This method doesn't pause anything, activitiers must be paused before calling this method.

Calling any of methods pausedownload, resumedownload, pausepost, resumepost, pausescan, resumescan deactivates the wait timer.

Return value: Always "True".

Configuration

Method "config"

Signature:

struct[] config() 

Returns current configuration loaded into program. Please note that the configuration file on disk may differ from the loaded configuration. This may occur if the configuration file on disk was changed after the program was launched or the program may become some options passed via command line.

Return value: This method returns an array of structures with following fields:

Field Type Description
Name string Option name.
Value string Option value.

Notes:

  • For options with predefined possible values (yes/no, etc.) the values are returned always in lower case.
  • If the option has variable references (e. g. "${MainDir}/dst") the returned value has all variables substituted ("/home/user/downloads/dst").

Method "loadconfig"

Signature:

struct[] loadconfig() 

Reads configuration file from the disk.

Return value: This method returns an array of structures with following fields:

Field Type Description
Name string Option name.
Value string Option value.

Notes:

  • The option value is returned exactly as it is stored in the configuration file. For example it may contain variable references (e. g. "${MainDir}/dst").

Method "saveconfig"

Signature:

bool saveconfig(struct[] options) 

Saves configuration file to the disk.

Parameters:

  • options - array of structs
Field Type Description
Name string Option name.
Value string Option value.

Return value: "True" on success or "False" on failure.

Method "configtemplates"

Signature:

struct[] configtemplates(bool loadFromDisk) 

Parameters:

  • loadFromDisk - 15.0 "true" - load templates from disk, "false" - give templates loaded on program start.

Returns NZBGet configuration file template and also extracts configuration sections from all post-processing files. This information is for example used by web-interface to build settings page or page "Postprocess" in download details dialog.

Return value: This method returns an array of structures with following fields:

Field Type Description
Name string Post-processing script name. For example "videosort/VideoSort.py". This field is empty in the first record, which holds the config template of the program itself.
DisplayName string Nice script name ready for displaying. For example "VideoSort".
PostScript bool "True" for post-processing scripts.
ScanScript bool "True" for scan scripts.
QueueScript bool "True" for queue scripts.
SchedulerScript bool "True" for scheduler scripts.
Template string Content of the configuration template.

Examples

The most comprehensive example on using JSON-RPC with NZBGet is NZBGets built-in web-interface. Look at the javascript sources in directory webui.

Another comprehensive example is NZBGetWeb - old web-interface written in PHP for NZBGet versions prior 9.0. Look in download section for source code. Take into account that this application is not developed anymore and may not be fully compatible with actual NZBGet versions. Still it's a good source for PHP example.

Two following examples show how to interact with NZBGet from Python using XML-RPC.

Adding file to download queue

NOTE: In this example the method append is called with signature from NZBGet 0.6.0, which had less parameters but is still supported.

TODO: Update to signature v13.

C:\>C:\Programme\Python25\python.exe
Python 2.5.1 (r251:54863, Apr 18 2007, 08:51:08) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from xmlrpclib import ServerProxy
>>> server = ServerProxy('http://nzbget:tegbzn6789@localhost:6789/xmlrpc')
>>> filename="C:\\ubuntu-7.10.nzb"
>>> in_file = open(filename, "r")
>>> nzbcontent = in_file.read()
>>> in_file.close()
>>> from base64 import standard_b64encode
>>> nzbcontent64=standard_b64encode(nzbcontent)
>>> server.append(filename, 'software', False, nzbcontent64)
True
>>>

Obtaining log

C:\>C:\Programme\Python25\python.exe
Python 2.5.1 (r251:54863, Apr 18 2007, 08:51:08) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from xmlrpclib import ServerProxy
>>> server = ServerProxy('http://nzbget:tegbzn6789@localhost:6789/xmlrpc')
>>> server.log(1, 0)
[{'Text': 'nzbget server-mode', 'Kind': 'INFO', 'ID': 1, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [1/131]', 
'Kind': 'INFO', 'ID': 2, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [2/131]', 
'Kind': 'INFO', 'ID': 3, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [3/131]', 
'Kind': 'INFO', 'ID': 4, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [4/131]', 
'Kind': 'INFO', 'ID': 5, 'Time': 1202409509}, 
{'Text': 'Pausing download', 'Kind': 'INFO', 'ID': 6, 'Time': 1202409513}]
>>>
Donation



Get NZBGet at SourceForge.net. Fast, secure and Free Open Source software downloads

Personal tools