github
/
aria2
mirror of https://github.com/aria2/aria2
1
0
Fork 0
Code Issues Releases Wiki Activity

2010-10-30 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net> 

Added XML-RPC client code example using Python(I have not added
	them for every methods yet). Added -x and -k example.
	* doc/aria2c.1.txt
pull/1/head
Tatsuhiro Tsujikawa 2010-10-30 03:37:58 +00:00
parent e032014466
commit ad76f1b720
4 changed files with 579 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -1,3 +1,9 @@
2010-10-30 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
Added XML-RPC client code example using Python(I have not added
them for every methods yet). Added -x and -k example.
* doc/aria2c.1.txt
2010-10-29 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
Fixed compiler warning with --disable-bittorrent and

279
doc/aria2c.1
View File

@ -2,12 +2,12 @@
.\" Title: aria2c
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 10/22/2010
.\" Date: 10/30/2010
.\" Manual: Aria2 Manual
.\" Source: Aria2 1.10.5
.\" Language: English
.\"
.TH "ARIA2C" "1" "10/22/2010" "Aria2 1\&.10\&.5" "Aria2 Manual"
.TH "ARIA2C" "1" "10/30/2010" "Aria2 1\&.10\&.5" "Aria2 Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@ -2814,51 +2814,139 @@ GID(or gid) is the key to manage each download\&. Each download has an unique GI
.RE
.SS "Methods"
.sp
\fBaria2\&.addUri\fR \fIuris[, options[, position]]\fR
All code examples come from Python2\&.7 interpreter\&.
.sp
This method adds new HTTP(S)/FTP/BitTorrent Magnet URI\&. \fIuris\fR is of type array and its element is URI which is of type string\&. For BitTorrent Magnet URI, \fIuris\fR must have only one element and it should be BitTorrent Magnet URI\&. URIs in \fIuris\fR must point to the same file\&. For example, a file chunkybaconlinux\&.iso is hosted in 2 locations: http://server/chunkybaconlinux\&.iso and http://mirror/chunkybaconlinux\&.iso\&. You can download this iso image using 2 URIs by issuing aria2\&.addUri(["http://server/chunkybaconlinux\&.iso", "http://mirror/chunkybaconlinux\&.iso"])\&. Imagine there is an another file URI, say, http://mirror2/chunkydonutslinux\&.iso, which is different iso image\&. You cannot mix this URI with previous URIs in one aria2\&.addUri command\&. If you do, aria2 does not complain but download may fail\&. \fIoptions\fR is of type struct and its members are a pair of option name and value\&. See \fBOptions\fR below for more details\&. If \fIposition\fR is given as an integer starting from 0, the new download is inserted at \fIposition\fR in the waiting queue\&. If \fIposition\fR is not given or \fIposition\fR is larger than the size of the queue, it is appended at the end of the queue\&. This method returns GID of registered download\&.
\fBaria2\&.addUri\fR (\fIuris[, options[, position]]\fR)
.sp
\fBaria2\&.addTorrent\fR \fItorrent[, uris[, options[, position]]]\fR
This method adds new HTTP(S)/FTP/BitTorrent Magnet URI\&. \fIuris\fR is of type array and its element is URI which is of type string\&. For BitTorrent Magnet URI, \fIuris\fR must have only one element and it should be BitTorrent Magnet URI\&. URIs in \fIuris\fR must point to the same file\&. If you mix other URIs which point to another file, aria2 does not complain but download may fail\&. \fIoptions\fR is of type struct and its members are a pair of option name and value\&. See \fBOptions\fR below for more details\&. If \fIposition\fR is given as an integer starting from 0, the new download is inserted at \fIposition\fR in the waiting queue\&. If \fIposition\fR is not given or \fIposition\fR is larger than the size of the queue, it is appended at the end of the queue\&. This method returns GID of registered download\&.
.sp
Adding http://example\&.org/file to aria2:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> s\&.aria2\&.addUri([\*(Aqhttp://example\&.org/file\*(Aq])
\*(Aq1\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
Adding 2 sources and some options:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> s\&.aria2\&.addUri([\*(Aqhttp://example\&.org/file\*(Aq], dict(dir="/tmp"))
\*(Aq2\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
Adding a download and insert it to the front of waiting downloads:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> s\&.aria2\&.addUri([\*(Aqhttp://example\&.org/file\*(Aq], {}, 0)
\*(Aq3\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
\fBaria2\&.addTorrent\fR (\fItorrent[, uris[, options[, position]]]\fR)
.sp
This method adds BitTorrent download by uploading \&.torrent file\&. If you want to add BitTorrent Magnet URI, use \fBaria2\&.addUri\fR method instead\&. \fItorrent\fR is of type base64 which contains Base64\-encoded \&.torrent file\&. \fIuris\fR is of type array and its element is URI which is of type string\&. \fIuris\fR is used for Web\-seeding\&. For single file torrents, URI can be a complete URI pointing to the resource or if URI ends with /, name in torrent file is added\&. For multi\-file torrents, name and path in torrent are added to form a URI for each file\&. \fIoptions\fR is of type struct and its members are a pair of option name and value\&. See \fBOptions\fR below for more details\&. If \fIposition\fR is given as an integer starting from 0, the new download is inserted at \fIposition\fR in the waiting queue\&. If \fIposition\fR is not given or \fIposition\fR is larger than the size of the queue, it is appended at the end of the queue\&. This method returns GID of registered download\&. Please note that the downloads added by this method are not saved by \fB\-\-save\-session\fR\&.
.sp
\fBaria2\&.addMetalink\fR \fImetalink[, options[, position]]\fR
Adding local file file\&.torrent to aria2:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> s\&.aria2\&.addTorrent(xmlrpclib\&.Binary(open(\*(Aqfile\&.torrent\*(Aq)\&.read()))
\*(Aq6\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
\fBaria2\&.addMetalink\fR (\fImetalink[, options[, position]]\fR)
.sp
This method adds Metalink download by uploading \&.metalink file\&. \fImetalink\fR is of type base64 which contains Base64\-encoded \&.metalink file\&. \fIoptions\fR is of type struct and its members are a pair of option name and value\&. See \fBOptions\fR below for more details\&. If \fIposition\fR is given as an integer starting from 0, the new download is inserted at \fIposition\fR in the waiting queue\&. If \fIposition\fR is not given or \fIposition\fR is larger than the size of the queue, it is appended at the end of the queue\&. This method returns array of GID of registered download\&. Please note that the downloads added by this method are not saved by \fB\-\-save\-session\fR\&.
.sp
\fBaria2\&.remove\fR \fIgid\fR
Adding local file file\&.meta4 to aria2:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> s\&.aria2\&.addMetalink(xmlrpclib\&.Binary(open(\*(Aqfile\&.meta4\*(Aq)\&.read()))
[\*(Aq8\*(Aq]
.fi
.if n \{\
.RE
.\}
.sp
\fBaria2\&.remove\fR (\fIgid\fR)
.sp
This method removes the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. If specified download is in progress, it is stopped at first\&. The status of removed download becomes "removed"\&. This method returns GID of removed download\&.
.sp
\fBaria2\&.forceRemove\fR \fIgid\fR
Removing download whose GID is \fI3\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> s\&.aria2\&.remove(\*(Aq3\*(Aq)
\*(Aq3\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
\fBaria2\&.forceRemove\fR (\fIgid\fR)
.sp
This method removes the download denoted by \fIgid\fR\&. This method behaves just like \fBaria2\&.remove\fR except that this method removes download without any action which takes time such as contacting BitTorrent tracker\&.
.sp
\fBaria2\&.pause\fR \fIgid\fR
\fBaria2\&.pause\fR (\fIgid\fR)
.sp
This method pauses the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. The status of paused download becomes "paused"\&. If the download is active, the download is placed on the first position of waiting queue\&. As long as the status is "paused", the download is not started\&. To change status to "waiting", use \fBaria2\&.unpause\fR method\&. This method returns GID of paused download\&.
.sp
\fBaria2\&.pauseAll\fR
\fBaria2\&.pauseAll\fR ()
.sp
This method is equal to calling \fBaria2\&.pause\fR for every active/waiting download\&. This methods returns "OK" for success\&.
.sp
\fBaria2\&.forcePause\fR \fIpid\fR
\fBaria2\&.forcePause\fR (\fIpid\fR)
.sp
This method pauses the download denoted by \fIgid\fR\&. This method behaves just like \fBaria2\&.pause\fR except that this method pauses download without any action which takes time such as contacting BitTorrent tracker\&.
.sp
\fBaria2\&.forcePauseAll\fR
\fBaria2\&.forcePauseAll\fR ()
.sp
This method is equal to calling \fBaria2\&.forcePause\fR for every active/waiting download\&. This methods returns "OK" for success\&.
.sp
\fBaria2\&.unpause\fR \fIgid\fR
\fBaria2\&.unpause\fR (\fIgid\fR)
.sp
This method changes the status of the download denoted by \fIgid\fR from "paused" to "waiting"\&. This makes the download eligible to restart\&. \fIgid\fR is of type string\&. This method returns GID of unpaused download\&.
.sp
\fBaria2\&.unpauseAll\fR
\fBaria2\&.unpauseAll\fR ()
.sp
This method is equal to calling \fBaria2\&.unpause\fR for every active/waiting download\&. This methods returns "OK" for success\&.
.sp
\fBaria2\&.tellStatus\fR \fIgid[, keys]\fR
\fBaria2\&.tellStatus\fR (\fIgid[, keys]\fR)
.sp
This method returns download progress of the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. \fIkeys\fR is array of string\&. If it is specified, the response contains only keys in \fIkeys\fR array\&. If \fIkeys\fR is empty or not specified, the response contains all keys\&. This is useful when you just want specific keys and avoid unnecessary transfers\&. For example, \fBaria2\&.tellStatus\fR("1", ["gid", "status"]) returns \fIgid\fR and \fIstatus\fR key\&. The response is of type struct and it contains following keys\&. The value type is string\&.
.PP
@ -2994,7 +3082,56 @@ name in info dictionary\&. name\&.utf\-8 is used if available\&.
.RE
.RE
.sp
\fBaria2\&.getUris\fR \fIgid\fR
Get information about download whose GID is \fI1\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> r = s\&.aria2\&.tellStatus(\*(Aq1\*(Aq)
>>> pprint(r)
{\*(Aqbitfield\*(Aq: \*(Aqffff80\*(Aq,
\*(AqcompletedLength\*(Aq: \*(Aq34896138\*(Aq,
\*(Aqconnections\*(Aq: \*(Aq0\*(Aq,
\*(Aqdir\*(Aq: \*(Aq/downloads\*(Aq,
\*(AqdownloadSpeed\*(Aq: \*(Aq0\*(Aq,
\*(AqerrorCode\*(Aq: \*(Aq0\*(Aq,
\*(Aqfiles\*(Aq: [{\*(Aqindex\*(Aq: \*(Aq1\*(Aq,
\*(Aqlength\*(Aq: \*(Aq34896138\*(Aq,
\*(Aqpath\*(Aq: \*(Aq/downloads/file\*(Aq,
\*(Aqselected\*(Aq: \*(Aqtrue\*(Aq,
\*(Aquris\*(Aq: [{\*(Aqstatus\*(Aq: \*(Aqused\*(Aq,
\*(Aquri\*(Aq: \*(Aqhttp://example\&.org/file\*(Aq}]}],
\*(Aqgid\*(Aq: \*(Aq1\*(Aq,
\*(AqnumPieces\*(Aq: \*(Aq17\*(Aq,
\*(AqpieceLength\*(Aq: \*(Aq2097152\*(Aq,
\*(Aqstatus\*(Aq: \*(Aqcomplete\*(Aq,
\*(AqtotalLength\*(Aq: \*(Aq34896138\*(Aq,
\*(AquploadLength\*(Aq: \*(Aq0\*(Aq,
\*(AquploadSpeed\*(Aq: \*(Aq0\*(Aq}
.fi
.if n \{\
.RE
.\}
.sp
Get information specifying keys you are interested in:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> r = s\&.aria2\&.tellStatus(\*(Aq1\*(Aq, [\*(Aqgid\*(Aq, \*(AqtotalLength\*(Aq, \*(AqcompletedLength\*(Aq])
>>> pprint(r)
{\*(AqcompletedLength\*(Aq: \*(Aq34896138\*(Aq, \*(Aqgid\*(Aq: \*(Aq1\*(Aq, \*(AqtotalLength\*(Aq: \*(Aq34896138\*(Aq}
.fi
.if n \{\
.RE
.\}
.sp
\fBaria2\&.getUris\fR (\fIgid\fR)
.sp
This method returns URIs used in the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. The response is of type array and its element is of type struct and it contains following keys\&. The value type is string\&.
.PP
@ -3012,7 +3149,7 @@ if the URI is already used\&.
if the URI is waiting in the queue\&.
.RE
.sp
\fBaria2\&.getFiles\fR \fIgid\fR
\fBaria2\&.getFiles\fR (\fIgid\fR)
.sp
This method returns file list of the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. The response is of type array and its element is of type struct and it contains following keys\&. The value type is string\&.
.PP
@ -3047,7 +3184,7 @@ Returns the list of URI for this file\&. The element of list is the same struct
method\&.
.RE
.sp
\fBaria2\&.getPeers\fR \fIgid\fR
\fBaria2\&.getPeers\fR (\fIgid\fR)
.sp
This method returns peer list of the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. This method is for BitTorrent only\&. The response is of type array and its element is of type struct and it contains following keys\&. The value type is string\&.
.PP
@ -3096,7 +3233,7 @@ seeder
"true" is this client is a seeder\&. Otherwise "false"\&.
.RE
.sp
\fBaria2\&.getServers\fR \fIgid\fR
\fBaria2\&.getServers\fR (\fIgid\fR)
.sp
This method returns currently connected HTTP(S)/FTP servers of the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. The response is of type array and its element is of type struct and it contains following keys\&. The value type is string\&.
.PP
@ -3125,11 +3262,11 @@ Download speed (byte/sec)
.RE
.RE
.sp
\fBaria2\&.tellActive\fR \fI[keys]\fR
\fBaria2\&.tellActive\fR (\fI[keys]\fR)
.sp
This method returns the list of active downloads\&. The response is of type array and its element is the same struct returned by \fBaria2\&.tellStatus\fR method\&. For \fIkeys\fR parameter, please refer to \fBaria2\&.tellStatus\fR method\&.
.sp
\fBaria2\&.tellWaiting\fR \fIoffset, num, [keys]\fR
\fBaria2\&.tellWaiting\fR (\fIoffset, num, [keys]\fR)
.sp
This method returns the list of waiting download, including paused downloads\&. \fIoffset\fR is of type integer and specifies the offset from the download waiting at the front\&. \fInum\fR is of type integer and specifies the number of downloads to be returned\&. For \fIkeys\fR parameter, please refer to \fBaria2\&.tellStatus\fR method\&.
.sp
@ -3141,7 +3278,7 @@ For example, imagine that three downloads "A","B" and "C" are waiting in this or
.sp
The response is of type array and its element is the same struct returned by \fBaria2\&.tellStatus\fR method\&.
.sp
\fBaria2\&.tellStopped\fR \fIoffset, num, [keys]\fR
\fBaria2\&.tellStopped\fR (\fIoffset, num, [keys]\fR)
.sp
This method returns the list of stopped download\&. \fIoffset\fR is of type integer and specifies the offset from the oldest download\&. \fInum\fR is of type integer and specifies the number of downloads to be returned\&. For \fIkeys\fR parameter, please refer to \fBaria2\&.tellStatus\fR method\&.
.sp
@ -3149,37 +3286,37 @@ This method returns the list of stopped download\&. \fIoffset\fR is of type inte
.sp
The response is of type array and its element is the same struct returned by \fBaria2\&.tellStatus\fR method\&.
.sp
\fBaria2\&.changePosition\fR \fIgid, pos, how\fR
\fBaria2\&.changePosition\fR (\fIgid, pos, how\fR)
.sp
This method changes the position of the download denoted by \fIgid\fR\&. \fIpos\fR is of type integer\&. \fIhow\fR is of type string\&. If \fIhow\fR is "POS_SET", it moves the download to a position relative to the beginning of the queue\&. If \fIhow\fR is "POS_CUR", it moves the download to a position relative to the current position\&. If \fIhow\fR is "POS_END", it moves the download to a position relative to the end of the queue\&. If the destination position is less than 0 or beyond the end of the queue, it moves the download to the beginning or the end of the queue respectively\&. The response is of type integer and it is the destination position\&.
.sp
For example, if GID#1 is placed in position 3, aria2\&.changePosition(1, \-1, POS_CUR) will change its position to 2\&. Additional aria2\&.changePosition(1, 0, POS_SET) will change its position to 0(the beginning of the queue)\&.
.sp
\fBaria2\&.changeUri\fR \fIgid, fileIndex, delUris, addUris[, position]\fR
\fBaria2\&.changeUri\fR (\fIgid, fileIndex, delUris, addUris[, position]\fR)
.sp
This method removes URIs in \fIdelUris\fR from and appends URIs in \fIaddUris\fR to download denoted by \fIgid\fR\&. \fIdelUris\fR and \fIaddUris\fR are list of string\&. A download can contain multiple files and URIs are attached to each file\&. \fIfileIndex\fR is used to select which file to remove/attach given URIs\&. \fIfileIndex\fR is 1\-based\&. \fIposition\fR is used to specify where URIs are inserted in the existing waiting URI list\&. \fIposition\fR is 0\-based\&. When \fIposition\fR is omitted, URIs are appended to the back of the list\&. This method first execute removal and then addition\&. \fIposition\fR is the position after URIs are removed, not the position when this method is called\&. When removing URI, if same URIs exist in download, only one of them is removed for each URI in \fIdelUris\fR\&. In other words, there are three URIs "http://example\&.org/aria2" and you want remove them all, you have to specify (at least) 3 "http://example\&.org/aria2" in \fIdelUris\fR\&. This method returns a list which contains 2 integers\&. The first integer is the number of URIs deleted\&. The second integer is the number of URIs added\&.
.sp
\fBaria2\&.getOption\fR \fIgid\fR
\fBaria2\&.getOption\fR (\fIgid\fR)
.sp
This method returns options of the download denoted by \fIgid\fR\&. The response is of type struct\&. Its key is the name of option\&. The value type is string\&.
.sp
\fBaria2\&.changeOption\fR \fIgid, options\fR
\fBaria2\&.changeOption\fR (\fIgid, options\fR)
.sp
This method changes options of the download denoted by \fIgid\fR dynamically\&. \fIgid\fR is of type string\&. \fIoptions\fR is of type struct and the available options are: \fBbt\-max\-peers\fR, \fBbt\-request\-peer\-speed\-limit\fR, \fBmax\-download\-limit\fR and \fBmax\-upload\-limit\fR\&. This method returns "OK" for success\&.
.sp
\fBaria2\&.getGlobalOption\fR
\fBaria2\&.getGlobalOption\fR ()
.sp
This method returns global options\&. The response is of type struct\&. Its key is the name of option\&. The value type is string\&. Because global options are used as a template for the options of newly added download, the response contains keys returned by \fBaria2\&.getOption\fR method\&.
.sp
\fBaria2\&.changeGlobalOption\fR \fIoptions\fR
\fBaria2\&.changeGlobalOption\fR (\fIoptions\fR)
.sp
This method changes global options dynamically\&. \fIoptions\fR is of type struct and the available options are \fBmax\-concurrent\-downloads\fR, \fBmax\-overall\-download\-limit\fR, \fBmax\-overall\-upload\-limit\fR, \fBlog\-level\fR and \fBlog\fR\&. Using \fBlog\fR option, you can dynamically start logging or change log file\&. To stop logging, give empty string("") as a parameter value\&. Note that log file is always opened in append mode\&. This method returns "OK" for success\&.
.sp
\fBaria2\&.purgeDownloadResult\fR
\fBaria2\&.purgeDownloadResult\fR ()
.sp
This method purges completed/error/removed downloads to free memory\&. This method returns "OK"\&.
.sp
\fBaria2\&.getVersion\fR
\fBaria2\&.getVersion\fR ()
.sp
This method returns version of the program and the list of enabled features\&. The response is of type struct and contains following keys\&.
.PP
@ -3193,7 +3330,30 @@ enabledFeatures
List of enabled features\&. Each feature name is of type string\&.
.RE
.sp
\fBaria2\&.getSessionInfo\fR
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> r = s\&.aria2\&.getVersion()
>>> pprint(r)
{\*(AqenabledFeatures\*(Aq: [\*(AqAsync DNS\*(Aq,
\*(AqBitTorrent\*(Aq,
\*(AqFirefox3 Cookie\*(Aq,
\*(AqGZip\*(Aq,
\*(AqHTTPS\*(Aq,
\*(AqMessage Digest\*(Aq,
\*(AqMetalink\*(Aq,
\*(AqXML\-RPC\*(Aq],
\*(Aqversion\*(Aq: \*(Aq1\&.10\&.5\*(Aq}
.fi
.if n \{\
.RE
.\}
.sp
\fBaria2\&.getSessionInfo\fR ()
.sp
This method returns session information\&. The response is of type struct and contains following key\&.
.PP
@ -3202,17 +3362,49 @@ sessionId
Session ID, which is generated each time when aria2 is invoked\&.
.RE
.sp
\fBaria2\&.shutdown\fR
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> s\&.aria2\&.getSessionInfo()
{\*(AqsessionId\*(Aq: \*(Aqcd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9\*(Aq}
.fi
.if n \{\
.RE
.\}
.sp
\fBaria2\&.shutdown\fR ()
.sp
This method shutdowns aria2\&. This method returns "OK"\&.
.sp
\fBaria2\&.forceShutdown\fR
\fBaria2\&.forceShutdown\fR ()
.sp
This method shutdowns aria2\&. This method behaves like \fBaria2\&.shutdown\fR except that any actions which takes time such as contacting BitTorrent tracker are skipped\&. This method returns "OK"\&.
.sp
\fBsystem\&.multicall\fR \fImethods\fR
\fBsystem\&.multicall\fR (\fImethods\fR)
.sp
This methods encapsulates multiple method calls in a single request\&. \fImethods\fR is of type array and its element is struct\&. The struct contains two keys: "methodName" and "params"\&. "methodName" is the method name to call and "params" is array containing parameters to the method\&. This method returns array of responses\&. The element of array will either be a one\-item array containing the return value of each method call or struct of fault element if an encapsulated method call fails\&.
.sp
In the following example, we add 2 downloads\&. First one is http://example\&.org/file and second one is file\&.torrent:
.sp
.if n \{\
.RS 4
.\}
.nf
>>> import xmlrpclib
>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq)
>>> mc = xmlrpclib\&.MultiCall(s)
>>> mc\&.aria2\&.addUri([\*(Aqhttp://example\&.org/file\*(Aq])
>>> mc\&.aria2\&.addTorrent(xmlrpclib\&.Binary(open(\*(Aqfile\&.torrent\*(Aq)\&.read()))
>>> r = mc()
>>> tuple(r)
(\*(Aq2\*(Aq, \*(Aq3\*(Aq)
.fi
.if n \{\
.RE
.\}
.SS "Error Handling"
.sp
In case of error, aria2 returns faultCode=1 and the error message in faultString\&.
@ -3366,6 +3558,25 @@ aria2c "http://host/file\&.zip" "http://mirror/file\&.zip"
.nr an-break-flag 1
.br
.ps +1
\fBDownload a file from 1 host using 2 connections\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
aria2c \-x2 \-k1M "http://host/file\&.zip"
.fi
.if n \{\
.RE
.\}
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBDownload a file from HTTP and FTP servers\fR
.RS 4
.sp

212
doc/aria2c.1.html
View File

@ -3264,28 +3264,41 @@ GID
</dd>
</dl></div>
<h3 id="_methods">Methods</h3><div style="clear:left"></div>
<div class="paragraph"><p><strong>aria2.addUri</strong> <em>uris[, options[, position]]</em></p></div>
<div class="paragraph"><p>All code examples come from Python2.7 interpreter.</p></div>
<div class="paragraph"><p><strong>aria2.addUri</strong> (<em>uris[, options[, position]]</em>)</p></div>
<div class="paragraph"><p>This method adds new HTTP(S)/FTP/BitTorrent Magnet URI. <em>uris</em> is of
type array and its element is URI which is of type string. For
BitTorrent Magnet URI, <em>uris</em> must have only one element and it should
be BitTorrent Magnet URI. URIs in <em>uris</em> must point to the same
file. For example, a file chunkybaconlinux.iso is hosted in 2
locations: http://server/chunkybaconlinux.iso and
http://mirror/chunkybaconlinux.iso. You can download this iso image
using 2 URIs by issuing
aria2.addUri(["http://server/chunkybaconlinux.iso",
"http://mirror/chunkybaconlinux.iso"]). Imagine there is an another
file URI, say, http://mirror2/chunkydonutslinux.iso, which is
different iso image. You cannot mix this URI with previous URIs in
one aria2.addUri command. If you do, aria2 does not complain but
download may fail. <em>options</em> is of type struct and its members are a
pair of option name and value. See <strong>Options</strong> below for more details.
If <em>position</em> is given as an integer starting from 0, the new download
is inserted at <em>position</em> in the waiting queue. If <em>position</em> is not
given or <em>position</em> is larger than the size of the queue, it is
appended at the end of the queue. This method returns GID of
registered download.</p></div>
<div class="paragraph"><p><strong>aria2.addTorrent</strong> <em>torrent[, uris[, options[, position]]]</em></p></div>
be BitTorrent Magnet URI. URIs in <em>uris</em> must point to the same file.
If you mix other URIs which point to another file, aria2 does not
complain but download may fail. <em>options</em> is of type struct and its
members are a pair of option name and value. See <strong>Options</strong> below for
more details. If <em>position</em> is given as an integer starting from 0,
the new download is inserted at <em>position</em> in the waiting queue. If
<em>position</em> is not given or <em>position</em> is larger than the size of the
queue, it is appended at the end of the queue. This method returns
GID of registered download.</p></div>
<div class="paragraph"><p>Adding http://example.org/file to aria2:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; s.aria2.addUri(['http://example.org/file'])
'1'</tt></pre>
</div></div>
<div class="paragraph"><p>Adding 2 sources and some options:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; s.aria2.addUri(['http://example.org/file'], dict(dir="/tmp"))
'2'</tt></pre>
</div></div>
<div class="paragraph"><p>Adding a download and insert it to the front of waiting downloads:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; s.aria2.addUri(['http://example.org/file'], {}, 0)
'3'</tt></pre>
</div></div>
<div class="paragraph"><p><strong>aria2.addTorrent</strong> (<em>torrent[, uris[, options[, position]]]</em>)</p></div>
<div class="paragraph"><p>This method adds BitTorrent download by uploading .torrent file. If
you want to add BitTorrent Magnet URI, use <strong>aria2.addUri</strong> method
instead. <em>torrent</em> is of type base64 which contains Base64-encoded
@ -3302,7 +3315,15 @@ given as an integer starting from 0, the new download is inserted at
end of the queue. This method returns GID of registered download.
Please note that the downloads added by this method are not saved by
<strong>--save-session</strong>.</p></div>
<div class="paragraph"><p><strong>aria2.addMetalink</strong> <em>metalink[, options[, position]]</em></p></div>
<div class="paragraph"><p>Adding local file file.torrent to aria2:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read()))
'6'</tt></pre>
</div></div>
<div class="paragraph"><p><strong>aria2.addMetalink</strong> (<em>metalink[, options[, position]]</em>)</p></div>
<div class="paragraph"><p>This method adds Metalink download by uploading .metalink file.
<em>metalink</em> is of type base64 which contains Base64-encoded .metalink
file. <em>options</em> is of type struct and its members are a pair of
@ -3313,43 +3334,59 @@ given or <em>position</em> is larger than the size of the queue, it is
appended at the end of the queue. This method returns array of GID of
registered download. Please note that the downloads added by this
method are not saved by <strong>--save-session</strong>.</p></div>
<div class="paragraph"><p><strong>aria2.remove</strong> <em>gid</em></p></div>
<div class="paragraph"><p>Adding local file file.meta4 to aria2:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4').read()))
['8']</tt></pre>
</div></div>
<div class="paragraph"><p><strong>aria2.remove</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method removes the download denoted by <em>gid</em>. <em>gid</em> is of type
string. If specified download is in progress, it is stopped at
first. The status of removed download becomes "removed". This method
returns GID of removed download.</p></div>
<div class="paragraph"><p><strong>aria2.forceRemove</strong> <em>gid</em></p></div>
<div class="paragraph"><p>Removing download whose GID is <em>3</em>:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; s.aria2.remove('3')
'3'</tt></pre>
</div></div>
<div class="paragraph"><p><strong>aria2.forceRemove</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method removes the download denoted by <em>gid</em>. This method
behaves just like <strong>aria2.remove</strong> except that this method removes
download without any action which takes time such as contacting
BitTorrent tracker.</p></div>
<div class="paragraph"><p><strong>aria2.pause</strong> <em>gid</em></p></div>
<div class="paragraph"><p><strong>aria2.pause</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method pauses the download denoted by <em>gid</em>. <em>gid</em> is of type
string. The status of paused download becomes "paused". If the
download is active, the download is placed on the first position of
waiting queue. As long as the status is "paused", the download is not
started. To change status to "waiting", use <strong>aria2.unpause</strong> method.
This method returns GID of paused download.</p></div>
<div class="paragraph"><p><strong>aria2.pauseAll</strong></p></div>
<div class="paragraph"><p><strong>aria2.pauseAll</strong> ()</p></div>
<div class="paragraph"><p>This method is equal to calling <strong>aria2.pause</strong> for every active/waiting
download. This methods returns "OK" for success.</p></div>
<div class="paragraph"><p><strong>aria2.forcePause</strong> <em>pid</em></p></div>
<div class="paragraph"><p><strong>aria2.forcePause</strong> (<em>pid</em>)</p></div>
<div class="paragraph"><p>This method pauses the download denoted by <em>gid</em>. This method
behaves just like <strong>aria2.pause</strong> except that this method pauses
download without any action which takes time such as contacting
BitTorrent tracker.</p></div>
<div class="paragraph"><p><strong>aria2.forcePauseAll</strong></p></div>
<div class="paragraph"><p><strong>aria2.forcePauseAll</strong> ()</p></div>
<div class="paragraph"><p>This method is equal to calling <strong>aria2.forcePause</strong> for every
active/waiting download. This methods returns "OK" for success.</p></div>
<div class="paragraph"><p><strong>aria2.unpause</strong> <em>gid</em></p></div>
<div class="paragraph"><p><strong>aria2.unpause</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method changes the status of the download denoted by <em>gid</em> from
"paused" to "waiting". This makes the download eligible to restart.
<em>gid</em> is of type string. This method returns GID of unpaused
download.</p></div>
<div class="paragraph"><p><strong>aria2.unpauseAll</strong></p></div>
<div class="paragraph"><p><strong>aria2.unpauseAll</strong> ()</p></div>
<div class="paragraph"><p>This method is equal to calling <strong>aria2.unpause</strong> for every active/waiting
download. This methods returns "OK" for success.</p></div>
<div class="paragraph"><p><strong>aria2.tellStatus</strong> <em>gid[, keys]</em></p></div>
<div class="paragraph"><p><strong>aria2.tellStatus</strong> (<em>gid[, keys]</em>)</p></div>
<div class="paragraph"><p>This method returns download progress of the download denoted by
<em>gid</em>. <em>gid</em> is of type string. <em>keys</em> is array of string. If it is
specified, the response contains only keys in <em>keys</em> array. If <em>keys</em>
@ -3590,7 +3627,42 @@ name
</dl></div>
</dd>
</dl></div>
<div class="paragraph"><p><strong>aria2.getUris</strong> <em>gid</em></p></div>
<div class="paragraph"><p>Get information about download whose GID is <em>1</em>:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; from pprint import pprint
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; r = s.aria2.tellStatus('1')
&gt;&gt;&gt; pprint(r)
{'bitfield': 'ffff80',
'completedLength': '34896138',
'connections': '0',
'dir': '/downloads',
'downloadSpeed': '0',
'errorCode': '0',
'files': [{'index': '1',
'length': '34896138',
'path': '/downloads/file',
'selected': 'true',
'uris': [{'status': 'used',
'uri': 'http://example.org/file'}]}],
'gid': '1',
'numPieces': '17',
'pieceLength': '2097152',
'status': 'complete',
'totalLength': '34896138',
'uploadLength': '0',
'uploadSpeed': '0'}</tt></pre>
</div></div>
<div class="paragraph"><p>Get information specifying keys you are interested in:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; r = s.aria2.tellStatus('1', ['gid', 'totalLength', 'completedLength'])
&gt;&gt;&gt; pprint(r)
{'completedLength': '34896138', 'gid': '1', 'totalLength': '34896138'}</tt></pre>
</div></div>
<div class="paragraph"><p><strong>aria2.getUris</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method returns URIs used in the download denoted by <em>gid</em>. <em>gid</em>
is of type string. The response is of type array and its element is of
type struct and it contains following keys. The value type is string.</p></div>
@ -3613,7 +3685,7 @@ status
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>aria2.getFiles</strong> <em>gid</em></p></div>
<div class="paragraph"><p><strong>aria2.getFiles</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method returns file list of the download denoted by <em>gid</em>. <em>gid</em>
is of type string. The response is of type array and its element is of
type struct and it contains following keys. The value type is string.</p></div>
@ -3663,7 +3735,7 @@ uris
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>aria2.getPeers</strong> <em>gid</em></p></div>
<div class="paragraph"><p><strong>aria2.getPeers</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method returns peer list of the download denoted by <em>gid</em>. <em>gid</em>
is of type string. This method is for BitTorrent only. The response
is of type array and its element is of type struct and it contains
@ -3745,7 +3817,7 @@ seeder
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>aria2.getServers</strong> <em>gid</em></p></div>
<div class="paragraph"><p><strong>aria2.getServers</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method returns currently connected HTTP(S)/FTP servers of the download denoted by <em>gid</em>. <em>gid</em> is of type string. The response
is of type array and its element is of type struct and it contains
following keys. The value type is string.</p></div>
@ -3795,12 +3867,12 @@ downloadSpeed
</dl></div>
</dd>
</dl></div>
<div class="paragraph"><p><strong>aria2.tellActive</strong> <em>[keys]</em></p></div>
<div class="paragraph"><p><strong>aria2.tellActive</strong> (<em>[keys]</em>)</p></div>
<div class="paragraph"><p>This method returns the list of active downloads. The response is of
type array and its element is the same struct returned by
<strong>aria2.tellStatus</strong> method. For <em>keys</em> parameter, please refer to
<strong>aria2.tellStatus</strong> method.</p></div>
<div class="paragraph"><p><strong>aria2.tellWaiting</strong> <em>offset, num, [keys]</em></p></div>
<div class="paragraph"><p><strong>aria2.tellWaiting</strong> (<em>offset, num, [keys]</em>)</p></div>
<div class="paragraph"><p>This method returns the list of waiting download, including paused
downloads. <em>offset</em> is of type integer and specifies the offset from
the download waiting at the front. <em>num</em> is of type integer and
@ -3818,7 +3890,7 @@ in this order. aria2.tellWaiting(0, 1) returns
aria2.tellWaiting(-1, 2) returns ["C", "B"].</p></div>
<div class="paragraph"><p>The response is of type array and its element is the same struct
returned by <strong>aria2.tellStatus</strong> method.</p></div>
<div class="paragraph"><p><strong>aria2.tellStopped</strong> <em>offset, num, [keys]</em></p></div>
<div class="paragraph"><p><strong>aria2.tellStopped</strong> (<em>offset, num, [keys]</em>)</p></div>
<div class="paragraph"><p>This method returns the list of stopped download. <em>offset</em> is of type
integer and specifies the offset from the oldest download. <em>num</em> is of
type integer and specifies the number of downloads to be returned.
@ -3827,7 +3899,7 @@ For <em>keys</em> parameter, please refer to <strong>aria2.tellStatus</strong> m
method.</p></div>
<div class="paragraph"><p>The response is of type array and its element is the same struct
returned by <strong>aria2.tellStatus</strong> method.</p></div>
<div class="paragraph"><p><strong>aria2.changePosition</strong> <em>gid, pos, how</em></p></div>
<div class="paragraph"><p><strong>aria2.changePosition</strong> (<em>gid, pos, how</em>)</p></div>
<div class="paragraph"><p>This method changes the position of the download denoted by
<em>gid</em>. <em>pos</em> is of type integer. <em>how</em> is of type string. If <em>how</em> is
"POS_SET", it moves the download to a position relative to the
@ -3842,7 +3914,7 @@ destination position.</p></div>
-1, POS_CUR) will change its position to 2. Additional
aria2.changePosition(1, 0, POS_SET) will change its position to 0(the
beginning of the queue).</p></div>
<div class="paragraph"><p><strong>aria2.changeUri</strong> <em>gid, fileIndex, delUris, addUris[, position]</em></p></div>
<div class="paragraph"><p><strong>aria2.changeUri</strong> (<em>gid, fileIndex, delUris, addUris[, position]</em>)</p></div>
<div class="paragraph"><p>This method removes URIs in <em>delUris</em> from and appends URIs in
<em>addUris</em> to download denoted by <em>gid</em>. <em>delUris</em> and <em>addUris</em> are
list of string. A download can contain multiple files and URIs are
@ -3860,23 +3932,23 @@ specify (at least) 3 "http://example.org/aria2" in <em>delUris</em>. This
method returns a list which contains 2 integers. The first integer is
the number of URIs deleted. The second integer is the number of URIs
added.</p></div>
<div class="paragraph"><p><strong>aria2.getOption</strong> <em>gid</em></p></div>
<div class="paragraph"><p><strong>aria2.getOption</strong> (<em>gid</em>)</p></div>
<div class="paragraph"><p>This method returns options of the download denoted by <em>gid</em>. The
response is of type struct. Its key is the name of option. The value type
is string.</p></div>
<div class="paragraph"><p><strong>aria2.changeOption</strong> <em>gid, options</em></p></div>
<div class="paragraph"><p><strong>aria2.changeOption</strong> (<em>gid, options</em>)</p></div>
<div class="paragraph"><p>This method changes options of the download denoted by <em>gid</em>
dynamically. <em>gid</em> is of type string. <em>options</em> is of type struct
and the available options are: <strong>bt-max-peers</strong>,
<strong>bt-request-peer-speed-limit</strong>, <strong>max-download-limit</strong> and
<strong>max-upload-limit</strong>. This method returns "OK" for success.</p></div>
<div class="paragraph"><p><strong>aria2.getGlobalOption</strong></p></div>
<div class="paragraph"><p><strong>aria2.getGlobalOption</strong> ()</p></div>
<div class="paragraph"><p>This method returns global options. The response is of type
struct. Its key is the name of option. The value type is string.
Because global options are used as a template for the options of newly
added download, the response contains keys returned by
<strong>aria2.getOption</strong> method.</p></div>
<div class="paragraph"><p><strong>aria2.changeGlobalOption</strong> <em>options</em></p></div>
<div class="paragraph"><p><strong>aria2.changeGlobalOption</strong> (<em>options</em>)</p></div>
<div class="paragraph"><p>This method changes global options dynamically. <em>options</em> is of type
struct and the available options are <strong>max-concurrent-downloads</strong>,
<strong>max-overall-download-limit</strong>, <strong>max-overall-upload-limit</strong>, <strong>log-level</strong>
@ -3884,10 +3956,10 @@ and <strong>log</strong>. Using <strong>log</strong> option, you can dynamically
change log file. To stop logging, give empty string("") as a parameter
value. Note that log file is always opened in append mode. This method
returns "OK" for success.</p></div>
<div class="paragraph"><p><strong>aria2.purgeDownloadResult</strong></p></div>
<div class="paragraph"><p><strong>aria2.purgeDownloadResult</strong> ()</p></div>
<div class="paragraph"><p>This method purges completed/error/removed downloads to free memory.
This method returns "OK".</p></div>
<div class="paragraph"><p><strong>aria2.getVersion</strong></p></div>
<div class="paragraph"><p><strong>aria2.getVersion</strong> ()</p></div>
<div class="paragraph"><p>This method returns version of the program and the list of enabled
features. The response is of type struct and contains following keys.</p></div>
<div class="dlist"><dl>
@ -3908,7 +3980,24 @@ enabledFeatures
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>aria2.getSessionInfo</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; from pprint import pprint
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; r = s.aria2.getVersion()
&gt;&gt;&gt; pprint(r)
{'enabledFeatures': ['Async DNS',
'BitTorrent',
'Firefox3 Cookie',
'GZip',
'HTTPS',
'Message Digest',
'Metalink',
'XML-RPC'],
'version': '1.10.5'}</tt></pre>
</div></div>
<div class="paragraph"><p><strong>aria2.getSessionInfo</strong> ()</p></div>
<div class="paragraph"><p>This method returns session information.
The response is of type struct and contains following key.</p></div>
<div class="dlist"><dl>
@ -3921,13 +4010,20 @@ sessionId
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>aria2.shutdown</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; s.aria2.getSessionInfo()
{'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}</tt></pre>
</div></div>
<div class="paragraph"><p><strong>aria2.shutdown</strong> ()</p></div>
<div class="paragraph"><p>This method shutdowns aria2. This method returns "OK".</p></div>
<div class="paragraph"><p><strong>aria2.forceShutdown</strong></p></div>
<div class="paragraph"><p><strong>aria2.forceShutdown</strong> ()</p></div>
<div class="paragraph"><p>This method shutdowns aria2. This method behaves like <strong>aria2.shutdown</strong>
except that any actions which takes time such as contacting BitTorrent
tracker are skipped. This method returns "OK".</p></div>
<div class="paragraph"><p><strong>system.multicall</strong> <em>methods</em></p></div>
<div class="paragraph"><p><strong>system.multicall</strong> (<em>methods</em>)</p></div>
<div class="paragraph"><p>This methods encapsulates multiple method calls in a single request.
<em>methods</em> is of type array and its element is struct. The struct
contains two keys: "methodName" and "params". "methodName" is the
@ -3936,6 +4032,19 @@ method. This method returns array of responses. The element of array
will either be a one-item array containing the return value of each
method call or struct of fault element if an encapsulated method call
fails.</p></div>
<div class="paragraph"><p>In the following example, we add 2 downloads. First one is
http://example.org/file and second one is file.torrent:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&gt;&gt;&gt; import xmlrpclib
&gt;&gt;&gt; s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
&gt;&gt;&gt; mc = xmlrpclib.MultiCall(s)
&gt;&gt;&gt; mc.aria2.addUri(['http://example.org/file'])
&gt;&gt;&gt; mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read()))
&gt;&gt;&gt; r = mc()
&gt;&gt;&gt; tuple(r)
('2', '3')</tt></pre>
</div></div>
<h3 id="_error_handling">Error Handling</h3><div style="clear:left"></div>
<div class="paragraph"><p>In case of error, aria2 returns faultCode=1 and the error message in
faultString.</p></div>
@ -4029,6 +4138,11 @@ pprint(r)</tt></pre>
<div class="content">
<pre><tt>aria2c "http://host/file.zip" "http://mirror/file.zip"</tt></pre>
</div></div>
<h4 id="_download_a_file_from_1_host_using_2_connections">Download a file from 1 host using 2 connections</h4>
<div class="listingblock">
<div class="content">
<pre><tt>aria2c -x2 -k1M "http://host/file.zip"</tt></pre>
</div></div>
<h4 id="_download_a_file_from_http_and_ftp_servers">Download a file from HTTP and FTP servers</h4>
<div class="listingblock">
<div class="content">
@ -4423,7 +4537,7 @@ files in the program, then also delete it here.</p></div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated 2010-10-22 22:58:37 JST
Last updated 2010-10-30 00:55:55 JST
</div>
</div>
</body>

213
doc/aria2c.1.txt
View File

@ -1444,30 +1444,44 @@ GID::
Methods
~~~~~~~
*aria2.addUri* 'uris[, options[, position]]'
All code examples come from Python2.7 interpreter.
*aria2.addUri* ('uris[, options[, position]]')
This method adds new HTTP(S)/FTP/BitTorrent Magnet URI. 'uris' is of
type array and its element is URI which is of type string. For
BitTorrent Magnet URI, 'uris' must have only one element and it should
be BitTorrent Magnet URI. URIs in 'uris' must point to the same
file. For example, a file chunkybaconlinux.iso is hosted in 2
locations: \http://server/chunkybaconlinux.iso and
\http://mirror/chunkybaconlinux.iso. You can download this iso image
using 2 URIs by issuing
aria2.addUri(["http://server/chunkybaconlinux.iso",
"http://mirror/chunkybaconlinux.iso"]). Imagine there is an another
file URI, say, \http://mirror2/chunkydonutslinux.iso, which is
different iso image. You cannot mix this URI with previous URIs in
one aria2.addUri command. If you do, aria2 does not complain but
download may fail. 'options' is of type struct and its members are a
pair of option name and value. See *Options* below for more details.
If 'position' is given as an integer starting from 0, the new download
is inserted at 'position' in the waiting queue. If 'position' is not
given or 'position' is larger than the size of the queue, it is
appended at the end of the queue. This method returns GID of
registered download.
be BitTorrent Magnet URI. URIs in 'uris' must point to the same file.
If you mix other URIs which point to another file, aria2 does not
complain but download may fail. 'options' is of type struct and its
members are a pair of option name and value. See *Options* below for
more details. If 'position' is given as an integer starting from 0,
the new download is inserted at 'position' in the waiting queue. If
'position' is not given or 'position' is larger than the size of the
queue, it is appended at the end of the queue. This method returns
GID of registered download.
*aria2.addTorrent* 'torrent[, uris[, options[, position]]]'
Adding \http://example.org/file to aria2:
----------------------------------------------------------
>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addUri(['http://example.org/file'])
'1'
----------------------------------------------------------
Adding 2 sources and some options:
--------------------------------------------------------------------------
>>> s.aria2.addUri(['http://example.org/file'], dict(dir="/tmp"))
'2'
--------------------------------------------------------------------------
Adding a download and insert it to the front of waiting downloads:
---------------------------------------------------------------
>>> s.aria2.addUri(['http://example.org/file'], {}, 0)
'3'
---------------------------------------------------------------
*aria2.addTorrent* ('torrent[, uris[, options[, position]]]')
This method adds BitTorrent download by uploading .torrent file. If
you want to add BitTorrent Magnet URI, use *aria2.addUri* method
@ -1486,7 +1500,15 @@ end of the queue. This method returns GID of registered download.
Please note that the downloads added by this method are not saved by
*--save-session*.
*aria2.addMetalink* 'metalink[, options[, position]]'
Adding local file file.torrent to aria2:
---------------------------------------------------------------------
>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read()))
'6'
---------------------------------------------------------------------
*aria2.addMetalink* ('metalink[, options[, position]]')
This method adds Metalink download by uploading .metalink file.
'metalink' is of type base64 which contains Base64-encoded .metalink
@ -1499,21 +1521,37 @@ appended at the end of the queue. This method returns array of GID of
registered download. Please note that the downloads added by this
method are not saved by *--save-session*.
*aria2.remove* 'gid'
Adding local file file.meta4 to aria2:
--------------------------------------------------------------------
>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.addMetalink(xmlrpclib.Binary(open('file.meta4').read()))
['8']
--------------------------------------------------------------------
*aria2.remove* ('gid')
This method removes the download denoted by 'gid'. 'gid' is of type
string. If specified download is in progress, it is stopped at
first. The status of removed download becomes "removed". This method
returns GID of removed download.
*aria2.forceRemove* 'gid'
Removing download whose GID is '3':
--------------------------------------------------------------------
>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.remove('3')
'3'
--------------------------------------------------------------------
*aria2.forceRemove* ('gid')
This method removes the download denoted by 'gid'. This method
behaves just like *aria2.remove* except that this method removes
download without any action which takes time such as contacting
BitTorrent tracker.
*aria2.pause* 'gid'
*aria2.pause* ('gid')
This method pauses the download denoted by 'gid'. 'gid' is of type
string. The status of paused download becomes "paused". If the
@ -1522,36 +1560,36 @@ waiting queue. As long as the status is "paused", the download is not
started. To change status to "waiting", use *aria2.unpause* method.
This method returns GID of paused download.
*aria2.pauseAll*
*aria2.pauseAll* ()
This method is equal to calling *aria2.pause* for every active/waiting
download. This methods returns "OK" for success.
*aria2.forcePause* 'pid'
*aria2.forcePause* ('pid')
This method pauses the download denoted by 'gid'. This method
behaves just like *aria2.pause* except that this method pauses
download without any action which takes time such as contacting
BitTorrent tracker.
*aria2.forcePauseAll*
*aria2.forcePauseAll* ()
This method is equal to calling *aria2.forcePause* for every
active/waiting download. This methods returns "OK" for success.
*aria2.unpause* 'gid'
*aria2.unpause* ('gid')
This method changes the status of the download denoted by 'gid' from
"paused" to "waiting". This makes the download eligible to restart.
'gid' is of type string. This method returns GID of unpaused
download.
*aria2.unpauseAll*
*aria2.unpauseAll* ()
This method is equal to calling *aria2.unpause* for every active/waiting
download. This methods returns "OK" for success.
*aria2.tellStatus* 'gid[, keys]'
*aria2.tellStatus* ('gid[, keys]')
This method returns download progress of the download denoted by
'gid'. 'gid' is of type string. 'keys' is array of string. If it is
@ -1689,7 +1727,42 @@ bittorrent::
name in info dictionary. name.utf-8 is used if available.
*aria2.getUris* 'gid'
Get information about download whose GID is '1':
--------------------------------------------------------------------
>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.tellStatus('1')
>>> pprint(r)
{'bitfield': 'ffff80',
'completedLength': '34896138',
'connections': '0',
'dir': '/downloads',
'downloadSpeed': '0',
'errorCode': '0',
'files': [{'index': '1',
'length': '34896138',
'path': '/downloads/file',
'selected': 'true',
'uris': [{'status': 'used',
'uri': 'http://example.org/file'}]}],
'gid': '1',
'numPieces': '17',
'pieceLength': '2097152',
'status': 'complete',
'totalLength': '34896138',
'uploadLength': '0',
'uploadSpeed': '0'}
--------------------------------------------------------------------
Get information specifying keys you are interested in:
--------------------------------------------------------------------------
>>> r = s.aria2.tellStatus('1', ['gid', 'totalLength', 'completedLength'])
>>> pprint(r)
{'completedLength': '34896138', 'gid': '1', 'totalLength': '34896138'}
--------------------------------------------------------------------------
*aria2.getUris* ('gid')
This method returns URIs used in the download denoted by 'gid'. 'gid'
is of type string. The response is of type array and its element is of
@ -1704,7 +1777,7 @@ status::
'used' if the URI is already used. 'waiting' if the URI is waiting
in the queue.
*aria2.getFiles* 'gid'
*aria2.getFiles* ('gid')
This method returns file list of the download denoted by 'gid'. 'gid'
is of type string. The response is of type array and its element is of
@ -1734,7 +1807,7 @@ uris::
Returns the list of URI for this file. The element of list is the
same struct used in *aria2.getUris* method.
*aria2.getPeers* 'gid'
*aria2.getPeers* ('gid')
This method returns peer list of the download denoted by 'gid'. 'gid'
is of type string. This method is for BitTorrent only. The response
@ -1780,7 +1853,7 @@ seeder::
"true" is this client is a seeder. Otherwise "false".
*aria2.getServers* 'gid'
*aria2.getServers* ('gid')
This method returns currently connected HTTP(S)/FTP servers of the download denoted by 'gid'. 'gid' is of type string. The response
is of type array and its element is of type struct and it contains
@ -1808,14 +1881,14 @@ servers::
Download speed (byte/sec)
*aria2.tellActive* '[keys]'
*aria2.tellActive* ('[keys]')
This method returns the list of active downloads. The response is of
type array and its element is the same struct returned by
*aria2.tellStatus* method. For 'keys' parameter, please refer to
*aria2.tellStatus* method.
*aria2.tellWaiting* 'offset, num, [keys]'
*aria2.tellWaiting* ('offset, num, [keys]')
This method returns the list of waiting download, including paused
downloads. 'offset' is of type integer and specifies the offset from
@ -1839,7 +1912,7 @@ aria2.tellWaiting(-1, 2) returns ["C", "B"].
The response is of type array and its element is the same struct
returned by *aria2.tellStatus* method.
*aria2.tellStopped* 'offset, num, [keys]'
*aria2.tellStopped* ('offset, num, [keys]')
This method returns the list of stopped download. 'offset' is of type
integer and specifies the offset from the oldest download. 'num' is of
@ -1852,7 +1925,7 @@ method.
The response is of type array and its element is the same struct
returned by *aria2.tellStatus* method.
*aria2.changePosition* 'gid, pos, how'
*aria2.changePosition* ('gid, pos, how')
This method changes the position of the download denoted by
'gid'. 'pos' is of type integer. 'how' is of type string. If 'how' is
@ -1870,7 +1943,7 @@ For example, if GID#1 is placed in position 3, aria2.changePosition(1,
aria2.changePosition(1, 0, POS_SET) will change its position to 0(the
beginning of the queue).
*aria2.changeUri* 'gid, fileIndex, delUris, addUris[, position]'
*aria2.changeUri* ('gid, fileIndex, delUris, addUris[, position]')
This method removes URIs in 'delUris' from and appends URIs in
'addUris' to download denoted by 'gid'. 'delUris' and 'addUris' are
@ -1890,13 +1963,13 @@ method returns a list which contains 2 integers. The first integer is
the number of URIs deleted. The second integer is the number of URIs
added.
*aria2.getOption* 'gid'
*aria2.getOption* ('gid')
This method returns options of the download denoted by 'gid'. The
response is of type struct. Its key is the name of option. The value type
is string.
*aria2.changeOption* 'gid, options'
*aria2.changeOption* ('gid, options')
This method changes options of the download denoted by 'gid'
dynamically. 'gid' is of type string. 'options' is of type struct
@ -1904,7 +1977,7 @@ and the available options are: *bt-max-peers*,
*bt-request-peer-speed-limit*, *max-download-limit* and
*max-upload-limit*. This method returns "OK" for success.
*aria2.getGlobalOption*
*aria2.getGlobalOption* ()
This method returns global options. The response is of type
struct. Its key is the name of option. The value type is string.
@ -1912,7 +1985,7 @@ Because global options are used as a template for the options of newly
added download, the response contains keys returned by
*aria2.getOption* method.
*aria2.changeGlobalOption* 'options'
*aria2.changeGlobalOption* ('options')
This method changes global options dynamically. 'options' is of type
struct and the available options are *max-concurrent-downloads*,
@ -1922,12 +1995,12 @@ change log file. To stop logging, give empty string("") as a parameter
value. Note that log file is always opened in append mode. This method
returns "OK" for success.
*aria2.purgeDownloadResult*
*aria2.purgeDownloadResult* ()
This method purges completed/error/removed downloads to free memory.
This method returns "OK".
*aria2.getVersion*
*aria2.getVersion* ()
This method returns version of the program and the list of enabled
features. The response is of type struct and contains following keys.
@ -1940,7 +2013,24 @@ enabledFeatures::
List of enabled features. Each feature name is of type string.
*aria2.getSessionInfo*
--------------------------------------------------------------------
>>> import xmlrpclib
>>> from pprint import pprint
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> r = s.aria2.getVersion()
>>> pprint(r)
{'enabledFeatures': ['Async DNS',
'BitTorrent',
'Firefox3 Cookie',
'GZip',
'HTTPS',
'Message Digest',
'Metalink',
'XML-RPC'],
'version': '1.10.5'}
--------------------------------------------------------------------
*aria2.getSessionInfo* ()
This method returns session information.
The response is of type struct and contains following key.
@ -1949,17 +2039,24 @@ sessionId::
Session ID, which is generated each time when aria2 is invoked.
*aria2.shutdown*
--------------------------------------------------------------------
>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> s.aria2.getSessionInfo()
{'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}
--------------------------------------------------------------------
*aria2.shutdown* ()
This method shutdowns aria2. This method returns "OK".
*aria2.forceShutdown*
*aria2.forceShutdown* ()
This method shutdowns aria2. This method behaves like *aria2.shutdown*
except that any actions which takes time such as contacting BitTorrent
tracker are skipped. This method returns "OK".
*system.multicall* 'methods'
*system.multicall* ('methods')
This methods encapsulates multiple method calls in a single request.
'methods' is of type array and its element is struct. The struct
@ -1970,6 +2067,20 @@ will either be a one-item array containing the return value of each
method call or struct of fault element if an encapsulated method call
fails.
In the following example, we add 2 downloads. First one is
\http://example.org/file and second one is file.torrent:
----------------------------------------------------------------------
>>> import xmlrpclib
>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
>>> mc = xmlrpclib.MultiCall(s)
>>> mc.aria2.addUri(['http://example.org/file'])
>>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read()))
>>> r = mc()
>>> tuple(r)
('2', '3')
----------------------------------------------------------------------
Error Handling
~~~~~~~~~~~~~~
@ -2073,6 +2184,12 @@ Download a file from 2 different HTTP servers
aria2c "http://host/file.zip" "http://mirror/file.zip"
------------------------------------------------------
Download a file from 1 host using 2 connections
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------------------
aria2c -x2 -k1M "http://host/file.zip"
------------------------------------------------------
Download a file from HTTP and FTP servers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-----------------------------------------------------