diff --git a/ChangeLog b/ChangeLog index 574f2dfe..33a529a5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2010-10-31 Tatsuhiro Tsujikawa + + Added XML-RPC examples. + * doc/aria2c.1.txt + 2010-10-31 Tatsuhiro Tsujikawa Return empty range if byte-range-resp-spec or instance-length is diff --git a/doc/aria2c.1 b/doc/aria2c.1 index de56915e..48ea7903 100644 --- a/doc/aria2c.1 +++ b/doc/aria2c.1 @@ -2,12 +2,12 @@ .\" Title: aria2c .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 10/30/2010 +.\" Date: 10/31/2010 .\" Manual: Aria2 Manual .\" Source: Aria2 1.10.5 .\" Language: English .\" -.TH "ARIA2C" "1" "10/30/2010" "Aria2 1\&.10\&.5" "Aria2 Manual" +.TH "ARIA2C" "1" "10/31/2010" "Aria2 1\&.10\&.5" "Aria2 Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -2919,7 +2919,7 @@ 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\&. 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: +The following example adds http://example\&.org/file to aria2: .sp .if n \{\ .RS 4 @@ -2934,7 +2934,7 @@ Adding http://example\&.org/file to aria2: .RE .\} .sp -Adding 2 sources and some options: +The following example adds 2 sources and some options: .sp .if n \{\ .RS 4 @@ -2947,7 +2947,7 @@ Adding 2 sources and some options: .RE .\} .sp -Adding a download and insert it to the front of waiting downloads: +The following example adds a download and insert it to the front of waiting downloads: .sp .if n \{\ .RS 4 @@ -2971,7 +2971,7 @@ Adding a download and insert it to the front of waiting downloads: .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 -Adding local file file\&.torrent to aria2: +The following example adds local file file\&.torrent to aria2: .sp .if n \{\ .RS 4 @@ -2997,7 +2997,7 @@ Adding local file file\&.torrent to aria2: .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 -Adding local file file\&.meta4 to aria2: +The following example adds local file file\&.meta4 to aria2: .sp .if n \{\ .RS 4 @@ -3023,7 +3023,7 @@ Adding local file file\&.meta4 to aria2: .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 -Removing download whose GID is \fI3\fR: +The following example removes download whose GID is "3": .sp .if n \{\ .RS 4 @@ -3260,7 +3260,7 @@ name in info dictionary\&. name\&.utf\-8 is used if available\&. .RE .RE .sp -Get information about download whose GID is \fI1\fR: +The following example gets information about download whose GID is "1": .sp .if n \{\ .RS 4 @@ -3295,7 +3295,7 @@ Get information about download whose GID is \fI1\fR: .RE .\} .sp -Get information specifying keys you are interested in: +The following example gets information specifying keys you are interested in: .sp .if n \{\ .RS 4 @@ -3333,6 +3333,21 @@ if the URI is already used\&. \fIwaiting\fR if the URI is waiting in the queue\&. .RE +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> r = s\&.aria2\&.getUris(\*(Aq1\*(Aq) +>>> pprint(r) +[{\*(Aqstatus\*(Aq: \*(Aqused\*(Aq, \*(Aquri\*(Aq: \*(Aqhttp://example\&.org/file\*(Aq}] +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap @@ -3375,6 +3390,26 @@ Returns the list of URI for this file\&. The element of list is the same struct \fBaria2\&.getUris\fR method\&. .RE +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> r = s\&.aria2\&.getFiles(\*(Aq1\*(Aq) +>>> pprint(r) +[{\*(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}]}] +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap @@ -3431,6 +3466,38 @@ seeder .RS 4 "true" is this client is a seeder\&. Otherwise "false"\&. .RE +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> r = s\&.aria2\&.getPeers(\*(Aq1\*(Aq) +>>> pprint(r) +[{\*(AqamChoking\*(Aq: \*(Aqtrue\*(Aq, + \*(Aqbitfield\*(Aq: \*(Aqffffffffffffffffffffffffffffffffffffffff\*(Aq, + \*(AqdownloadSpeed\*(Aq: \*(Aq10602\*(Aq, + \*(Aqip\*(Aq: \*(Aq10\&.0\&.0\&.9\*(Aq, + \*(AqpeerChoking\*(Aq: \*(Aqfalse\*(Aq, + \*(AqpeerId\*(Aq: \*(Aqaria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6\*(Aq, + \*(Aqport\*(Aq: \*(Aq6881\*(Aq, + \*(Aqseeder\*(Aq: \*(Aqtrue\*(Aq, + \*(AquploadSpeed\*(Aq: \*(Aq0\*(Aq}, + {\*(AqamChoking\*(Aq: \*(Aqfalse\*(Aq, + \*(Aqbitfield\*(Aq: \*(Aqffffeff0fffffffbfffffff9fffffcfff7f4ffff\*(Aq, + \*(AqdownloadSpeed\*(Aq: \*(Aq8654\*(Aq, + \*(Aqip\*(Aq: \*(Aq10\&.0\&.0\&.30\*(Aq, + \*(AqpeerChoking\*(Aq: \*(Aqfalse\*(Aq, + \*(AqpeerId\*(Aq: \*(Aqbittorrent client758\*(Aq, + \*(Aqport\*(Aq: \*(Aq37842\*(Aq, + \*(Aqseeder\*(Aq: \*(Aqfalse, + \*(AquploadSpeed\*(Aq: \*(Aq6890\*(Aq}] +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap @@ -3467,6 +3534,24 @@ downloadSpeed Download speed (byte/sec) .RE .RE +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> r = s\&.aria2\&.getServers(\*(Aq1\*(Aq) +>>> pprint(r) +[{\*(Aqindex\*(Aq: \*(Aq1\*(Aq, + \*(Aqservers\*(Aq: [{\*(AqcurrentUri\*(Aq: \*(Aqhttp://example\&.org/dl/file\*(Aq, + \*(AqdownloadSpeed\*(Aq: \*(Aq20285\*(Aq, + \*(Aquri\*(Aq: \*(Aqhttp://example\&.org/file\*(Aq}]}] +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap @@ -3525,6 +3610,21 @@ The response is of type array and its element is the same struct returned by \fB 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 +The following example moves the download whose GID is "3" to the front of the waiting queue: +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> s\&.aria2\&.changePosition(\*(Aq3\*(Aq, 0, \*(AqPOS_SET\*(Aq) +0 +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap @@ -3536,6 +3636,21 @@ For example, if GID#1 is placed in position 3, aria2\&.changePosition(1, \-1, PO .RS 4 .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 +The following example adds 1 URI http://example\&.org/file to the file whose index is "1" and belongs to the download whose GID is "2": +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> s\&.aria2\&.changeUri(\*(Aq2\*(Aq, 1, [], [\*(Aqhttp://example\&.org/file\*(Aq]) +[0, 1] +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap @@ -3547,6 +3662,27 @@ This method removes URIs in \fIdelUris\fR from and appends URIs in \fIaddUris\fR .RS 4 .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 +The following example gets options of the download whose GID is "1": +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> r = s\&.aria2\&.getOption(\*(Aq1\*(Aq) +>>> pprint(r) +{\*(Aqallow\-overwrite\*(Aq: \*(Aqfalse\*(Aq, + \*(Aqallow\-piece\-length\-change\*(Aq: \*(Aqfalse\*(Aq, + \*(Aqalways\-resume\*(Aq: \*(Aqtrue\*(Aq, + \*(Aqasync\-dns\*(Aq: \*(Aqtrue\*(Aq, + \&.\&.\&.\&. +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap @@ -3558,6 +3694,21 @@ This method returns options of the download denoted by \fIgid\fR\&. The response .RS 4 .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 +The following example sets \fBmax\-download\-limit\fR option to "20K" for the download whose GID is "1"\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +>>> import xmlrpclib +>>> s = xmlrpclib\&.ServerProxy(\*(Aqhttp://localhost:6800/rpc\*(Aq) +>>> s\&.aria2\&.changeOption(\*(Aq1\*(Aq, {\*(Aqmax\-download\-limit\*(Aq:\*(Aq20K\*(Aq}) +\*(AqOK\*(Aq +.fi +.if n \{\ +.RE +.\} .RE .sp .it 1 an-trap diff --git a/doc/aria2c.1.html b/doc/aria2c.1.html index b81b14b2..a67effb2 100644 --- a/doc/aria2c.1.html +++ b/doc/aria2c.1.html @@ -3285,7 +3285,8 @@ 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.

-

Adding http://example.org/file to aria2:

+
Example
+

The following example adds http://example.org/file to aria2:

>>> import xmlrpclib
@@ -3293,13 +3294,14 @@ GID of registered download.
>>> s.aria2.addUri(['http://example.org/file']) '1'
-

Adding 2 sources and some options:

+

The following example adds 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:

+

The following example adds a download and insert it to the front of +waiting downloads:

>>> s.aria2.addUri(['http://example.org/file'], {}, 0)
@@ -3323,7 +3325,8 @@ 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
 --save-session.
-

Adding local file file.torrent to aria2:

+
Example
+

The following example adds local file file.torrent to aria2:

>>> import xmlrpclib
@@ -3343,7 +3346,8 @@ given or position 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 --save-session.
-

Adding local file file.meta4 to aria2:

+
Example
+

The following example adds local file file.meta4 to aria2:

>>> import xmlrpclib
@@ -3357,7 +3361,8 @@ method are not saved by --save-sess
 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.
-

Removing download whose GID is 3:

+
Example
+

The following example removes download whose GID is "3":

>>> import xmlrpclib
@@ -3645,7 +3650,9 @@ name
-

Get information about download whose GID is 1:

+
Example
+

The following example gets information about download whose GID is +"1":

>>> import xmlrpclib
@@ -3673,7 +3680,8 @@ name
  'uploadLength': '0',
  'uploadSpeed': '0'}
-

Get information specifying keys you are interested in:

+

The following example gets information specifying keys you are +interested in:

>>> r = s.aria2.tellStatus('1', ['gid', 'totalLength', 'completedLength'])
@@ -3704,6 +3712,16 @@ status
+
Example
+
+
+
>>> import xmlrpclib
+>>> from pprint import pprint
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> r = s.aria2.getUris('1')
+>>> pprint(r)
+[{'status': 'used', 'uri': 'http://example.org/file'}]
+

aria2.getFiles (gid)

Description

This method returns file list of the download denoted by gid. gid @@ -3755,6 +3773,21 @@ uris

+
Example
+
+
+
>>> import xmlrpclib
+>>> from pprint import pprint
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> r = s.aria2.getFiles('1')
+>>> pprint(r)
+[{'index': '1',
+  'length': '34896138',
+  'path': '/downloads/file',
+  'selected': 'true',
+  'uris': [{'status': 'used',
+            'uri': 'http://example.org/file'}]}]
+

aria2.getPeers (gid)

Description

This method returns peer list of the download denoted by gid. gid @@ -3838,6 +3871,33 @@ seeder

+
Example
+
+
+
>>> import xmlrpclib
+>>> from pprint import pprint
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> r = s.aria2.getPeers('1')
+>>> pprint(r)
+[{'amChoking': 'true',
+  'bitfield': 'ffffffffffffffffffffffffffffffffffffffff',
+  'downloadSpeed': '10602',
+  'ip': '10.0.0.9',
+  'peerChoking': 'false',
+  'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6',
+  'port': '6881',
+  'seeder': 'true',
+  'uploadSpeed': '0'},
+ {'amChoking': 'false',
+  'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff',
+  'downloadSpeed': '8654',
+  'ip': '10.0.0.30',
+  'peerChoking': 'false',
+  'peerId': 'bittorrent client758',
+  'port': '37842',
+  'seeder': 'false,
+  'uploadSpeed': '6890'}]
+

aria2.getServers (gid)

Description

This method returns currently connected HTTP(S)/FTP servers of the download denoted by gid. gid is of type string. The response @@ -3889,6 +3949,19 @@ downloadSpeed

+
Example
+
+
+
>>> import xmlrpclib
+>>> from pprint import pprint
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> r = s.aria2.getServers('1')
+>>> pprint(r)
+[{'index': '1',
+  'servers': [{'currentUri': 'http://example.org/dl/file',
+               'downloadSpeed': '20285',
+               'uri': 'http://example.org/file'}]}]
+

aria2.tellActive ([keys])

Description

This method returns the list of active downloads. The response is of @@ -3940,6 +4013,16 @@ destination position.

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

+
Example
+

The following example moves the download whose GID is "3" to the +front of the waiting queue:

+
+
+
>>> import xmlrpclib
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> s.aria2.changePosition('3', 0, 'POS_SET')
+0
+

aria2.changeUri (gid, fileIndex, delUris, addUris[, position])

Description

This method removes URIs in delUris from and appends URIs in @@ -3959,11 +4042,36 @@ specify (at least) 3 "http://example.org/aria2" in delUris. 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.

+
Example
+

The following example adds 1 URI http://example.org/file to the file +whose index is "1" and belongs to the download whose GID is "2":

+
+
+
>>> import xmlrpclib
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> s.aria2.changeUri('2', 1, [], ['http://example.org/file'])
+[0, 1]
+

aria2.getOption (gid)

Description

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.

+
Example
+

The following example gets options of the download whose GID is "1":

+
+
+
>>> import xmlrpclib
+>>> from pprint import pprint
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> r = s.aria2.getOption('1')
+>>> pprint(r)
+{'allow-overwrite': 'false',
+ 'allow-piece-length-change': 'false',
+ 'always-resume': 'true',
+ 'async-dns': 'true',
+ ....
+

aria2.changeOption (gid, options)

Description

This method changes options of the download denoted by gid @@ -3971,6 +4079,17 @@ dynamically. gid is of type string. options is of type struc 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.

+
Example
+

The following example sets +max-download-limit option to "20K" for +the download whose GID is "1".

+
+
+
>>> import xmlrpclib
+>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
+>>> s.aria2.changeOption('1', {'max-download-limit':'20K'})
+'OK'
+

aria2.getGlobalOption ()

Description

This method returns global options. The response is of type @@ -4013,6 +4132,7 @@ enabledFeatures

+
Example
>>> import xmlrpclib
@@ -4044,6 +4164,7 @@ sessionId
+
Example
>>> import xmlrpclib
@@ -4069,6 +4190,7 @@ 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.
+
Example

In the following example, we add 2 downloads. First one is http://example.org/file and second one is file.torrent:

@@ -4166,7 +4288,7 @@ r = s.aria2.addUri(["http://localhost/aria2.tar.bz2"], {"dir":"/downloads"}) pprint(r)
-

EXAMPLE

+

EXAMPLE

HTTP/FTP Segmented Download

Download a file

@@ -4586,7 +4708,7 @@ files in the program, then also delete it here.

diff --git a/doc/aria2c.1.txt b/doc/aria2c.1.txt index c2f587a2..d875b461 100644 --- a/doc/aria2c.1.txt +++ b/doc/aria2c.1.txt @@ -1473,7 +1473,11 @@ the new download is inserted at 'position' in the waiting queue. If queue, it is appended at the end of the queue. This method returns GID of registered download. -Adding \http://example.org/file to aria2: +Example ++++++++ + +The following example adds \http://example.org/file to aria2: + ---------------------------------------------------------- >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') @@ -1481,13 +1485,16 @@ Adding \http://example.org/file to aria2: '1' ---------------------------------------------------------- -Adding 2 sources and some options: +The following example adds 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: +The following example adds a download and insert it to the front of +waiting downloads: + --------------------------------------------------------------- >>> s.aria2.addUri(['http://example.org/file'], {}, 0) '3' @@ -1517,7 +1524,11 @@ end of the queue. This method returns GID of registered download. Please note that the downloads added by this method are not saved by *<>*. -Adding local file file.torrent to aria2: +Example ++++++++ + +The following example adds local file file.torrent to aria2: + --------------------------------------------------------------------- >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') @@ -1543,7 +1554,11 @@ 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 *<>*. -Adding local file file.meta4 to aria2: +Example ++++++++ + +The following example adds local file file.meta4 to aria2: + -------------------------------------------------------------------- >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') @@ -1563,7 +1578,11 @@ 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. -Removing download whose GID is '3': +Example ++++++++ + +The following example removes download whose GID is "3": + -------------------------------------------------------------------- >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') @@ -1795,7 +1814,12 @@ bittorrent:: name in info dictionary. name.utf-8 is used if available. -Get information about download whose GID is '1': +Example ++++++++ + +The following example gets information about download whose GID is +"1": + -------------------------------------------------------------------- >>> import xmlrpclib >>> from pprint import pprint @@ -1823,7 +1847,9 @@ Get information about download whose GID is '1': 'uploadSpeed': '0'} -------------------------------------------------------------------- -Get information specifying keys you are interested in: +The following example gets information specifying keys you are +interested in: + -------------------------------------------------------------------------- >>> r = s.aria2.tellStatus('1', ['gid', 'totalLength', 'completedLength']) >>> pprint(r) @@ -1850,6 +1876,18 @@ status:: 'used' if the URI is already used. 'waiting' if the URI is waiting in the queue. +Example ++++++++ + +-------------------------------------------------------------------- +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> r = s.aria2.getUris('1') +>>> pprint(r) +[{'status': 'used', 'uri': 'http://example.org/file'}] +-------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_getFiles]] *aria2.getFiles* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1885,6 +1923,23 @@ uris:: Returns the list of URI for this file. The element of list is the same struct used in *<>* method. +Example ++++++++ + +-------------------------------------------------------------------------- +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> r = s.aria2.getFiles('1') +>>> pprint(r) +[{'index': '1', + 'length': '34896138', + 'path': '/downloads/file', + 'selected': 'true', + 'uris': [{'status': 'used', + 'uri': 'http://example.org/file'}]}] +-------------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_getPeers]] *aria2.getPeers* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1936,6 +1991,35 @@ seeder:: "true" is this client is a seeder. Otherwise "false". +Example ++++++++ + +-------------------------------------------------------------------------- +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> r = s.aria2.getPeers('1') +>>> pprint(r) +[{'amChoking': 'true', + 'bitfield': 'ffffffffffffffffffffffffffffffffffffffff', + 'downloadSpeed': '10602', + 'ip': '10.0.0.9', + 'peerChoking': 'false', + 'peerId': 'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6', + 'port': '6881', + 'seeder': 'true', + 'uploadSpeed': '0'}, + {'amChoking': 'false', + 'bitfield': 'ffffeff0fffffffbfffffff9fffffcfff7f4ffff', + 'downloadSpeed': '8654', + 'ip': '10.0.0.30', + 'peerChoking': 'false', + 'peerId': 'bittorrent client758', + 'port': '37842', + 'seeder': 'false, + 'uploadSpeed': '6890'}] +-------------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_getServers]] *aria2.getServers* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1969,6 +2053,21 @@ servers:: Download speed (byte/sec) +Example ++++++++ + +-------------------------------------------------------------------- +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> r = s.aria2.getServers('1') +>>> pprint(r) +[{'index': '1', + 'servers': [{'currentUri': 'http://example.org/dl/file', + 'downloadSpeed': '20285', + 'uri': 'http://example.org/file'}]}] +-------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_tellActive]] *aria2.tellActive* ('[keys]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2051,6 +2150,19 @@ 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). +Example ++++++++ + +The following example moves the download whose GID is "3" to the +front of the waiting queue: + +-------------------------------------------------------------------- +>>> import xmlrpclib +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> s.aria2.changePosition('3', 0, 'POS_SET') +0 +-------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_changeUri]] *aria2.changeUri* ('gid, fileIndex, delUris, addUris[, position]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2076,6 +2188,19 @@ 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. +Example ++++++++ + +The following example adds 1 URI \http://example.org/file to the file +whose index is "1" and belongs to the download whose GID is "2": + +-------------------------------------------------------------------- +>>> import xmlrpclib +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> s.aria2.changeUri('2', 1, [], ['http://example.org/file']) +[0, 1] +-------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_getOption]] *aria2.getOption* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2087,6 +2212,24 @@ 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. +Example ++++++++ + +The following example gets options of the download whose GID is "1": + +-------------------------------------------------------------------- +>>> import xmlrpclib +>>> from pprint import pprint +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> r = s.aria2.getOption('1') +>>> pprint(r) +{'allow-overwrite': 'false', + 'allow-piece-length-change': 'false', + 'always-resume': 'true', + 'async-dns': 'true', + .... +-------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_changeOption]] *aria2.changeOption* ('gid, options') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2100,6 +2243,20 @@ and the available options are: *<>*, *<>*, *<>* and *<>*. This method returns "OK" for success. +Example ++++++++ + +The following example sets +*<>* option to "20K" for +the download whose GID is "1". + +-------------------------------------------------------------------- +>>> import xmlrpclib +>>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') +>>> s.aria2.changeOption('1', {'max-download-limit':'20K'}) +'OK' +-------------------------------------------------------------------- + [[aria2_xmlrpc_aria2_getGlobalOption]] *aria2.getGlobalOption* () ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2156,6 +2313,9 @@ enabledFeatures:: List of enabled features. Each feature name is of type string. +Example ++++++++ + -------------------------------------------------------------------- >>> import xmlrpclib >>> from pprint import pprint @@ -2187,6 +2347,9 @@ sessionId:: Session ID, which is generated each time when aria2 is invoked. +Example ++++++++ + -------------------------------------------------------------------- >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') @@ -2230,6 +2393,9 @@ 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. +Example ++++++++ + In the following example, we add 2 downloads. First one is \http://example.org/file and second one is file.torrent: