mirror of https://github.com/aria2/aria2
2009-05-26 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
Documented XML-RPC API in man page. * doc/aria2c.1.txtpull/1/head
Tatsuhiro Tsujikawa
parent
a933438401
commit
4c1ed46094
|
|
@ -1,3 +1,8 @@
|
||||||
|
2009-05-26 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
|
||||||
|
|
||||||
|
Documented XML-RPC API in man page.
|
||||||
|
* doc/aria2c.1.txt
|
||||||
|
|
||||||
2009-05-24 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
|
2009-05-24 Tatsuhiro Tsujikawa <t-tujikawa@users.sourceforge.net>
|
||||||
|
|
||||||
Fixed g++-4.4 compiler warning: dereferencing type-punned pointer
|
Fixed g++-4.4 compiler warning: dereferencing type-punned pointer
|
||||||
|
|
|
||||||
260
doc/aria2c.1
260
doc/aria2c.1
|
|
@ -1,13 +1,13 @@
|
||||||
'\" t
|
'\" t
|
||||||
.\" Title: aria2c
|
.\" Title: aria2c
|
||||||
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
|
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
|
||||||
.\" Generator: DocBook XSL Stylesheets v1.74.3 <http://docbook.sf.net/>
|
.\" Generator: DocBook XSL Stylesheets v1.75.0 <http://docbook.sf.net/>
|
||||||
.\" Date: 05/23/2009
|
.\" Date: 05/26/2009
|
||||||
.\" Manual: [FIXME: manual]
|
.\" Manual: [FIXME: manual]
|
||||||
.\" Source: [FIXME: source]
|
.\" Source: [FIXME: source]
|
||||||
.\" Language: English
|
.\" Language: English
|
||||||
.\"
|
.\"
|
||||||
.TH "ARIA2C" "1" "05/23/2009" "[FIXME: source]" "[FIXME: manual]"
|
.TH "ARIA2C" "1" "05/26/2009" "[FIXME: source]" "[FIXME: manual]"
|
||||||
.\" -----------------------------------------------------------------
|
.\" -----------------------------------------------------------------
|
||||||
.\" * set default formatting
|
.\" * set default formatting
|
||||||
.\" -----------------------------------------------------------------
|
.\" -----------------------------------------------------------------
|
||||||
|
|
@ -2044,6 +2044,260 @@ host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR
|
||||||
.if n \{\
|
.if n \{\
|
||||||
.RE
|
.RE
|
||||||
.\}
|
.\}
|
||||||
|
.SH "XML-RPC INTERFACE"
|
||||||
|
.SS "Terminology"
|
||||||
|
.PP
|
||||||
|
GID
|
||||||
|
.RS 4
|
||||||
|
GID(or gid) is the key to manage each download\&. Each download has an unique GID\&. Currently GID looks like an integer, but don\(cqt treat it as integer because it may be changed to another type in the future release\&.
|
||||||
|
.RE
|
||||||
|
.SS "Methods"
|
||||||
|
.sp
|
||||||
|
\fBaria2\&.addUri\fR \fIuris[, options]\fR
|
||||||
|
.sp
|
||||||
|
This method adds new HTTP(S)/FTP download\&. \fIuris\fR is of type array and its element is URI which is of type string\&. URI should be percent\-encoded\&. \fIoptions\fR is of type struct and its members are a pair of option name and value\&. See \fBOptions\fR below for more details\&. This method returns GID of registered download\&.
|
||||||
|
.sp
|
||||||
|
\fBaria2\&.addTorrent\fR \fItorrent[, uris[, options]]\fR
|
||||||
|
.sp
|
||||||
|
This method adds BitTorrent download by uploading \&.torrent file\&. \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\&. Note that \fIuris\fR is ignored if specified torrent is a multi\-file torrent\&. \fIoptions\fR is of type struct and its members are a pair of option name and value\&. See \fBOptions\fR below for more details\&. This method returns GID of registered download\&.
|
||||||
|
.sp
|
||||||
|
\fBaria2\&.addMetalink\fR \fImetalink[, options]\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\&. This method returns GID of registered download\&.
|
||||||
|
.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\&.tellStatus\fR \fIgid\fR
|
||||||
|
.sp
|
||||||
|
This method returns download progress of the download denoted by \fIgid\fR\&. \fIgid\fR is of type string\&. The response is of type struct and it contains following keys\&. The value type is string\&.
|
||||||
|
.PP
|
||||||
|
gid
|
||||||
|
.RS 4
|
||||||
|
GID of this download\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
status
|
||||||
|
.RS 4
|
||||||
|
"active" for currently downloading/seeding entry\&. "waiting" for the entry in the queue; download is not started\&. "error" for the stopped download because of error\&. "complete" for the stopped and completed download\&. "removed" for the download removed by user\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
totalLength
|
||||||
|
.RS 4
|
||||||
|
Total length of this download in bytes\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
completedLength
|
||||||
|
.RS 4
|
||||||
|
Completed length of this download in bytes\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
bitfield
|
||||||
|
.RS 4
|
||||||
|
Hexadecimal representation of the download progress\&. The highest bit corresponds to piece index 0\&. The set bits indicate the piece is available and unset bits indicate the piece is missing\&. The spare bits at the end are set to zero\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
downloadSpeed
|
||||||
|
.RS 4
|
||||||
|
Download speed of this download measured in bytes/sec\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
uploadSpeed
|
||||||
|
.RS 4
|
||||||
|
Upload speed of this download measured in bytes/sec\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
infoHash
|
||||||
|
.RS 4
|
||||||
|
InfoHash\&. BitTorrent only\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
pieceLength
|
||||||
|
.RS 4
|
||||||
|
Piece length in bytes\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
numPieces
|
||||||
|
.RS 4
|
||||||
|
The number of pieces\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
connections
|
||||||
|
.RS 4
|
||||||
|
The number of peers/servers the client has connected to\&.
|
||||||
|
.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
|
||||||
|
uri
|
||||||
|
.RS 4
|
||||||
|
URI
|
||||||
|
.RE
|
||||||
|
.sp
|
||||||
|
\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
|
||||||
|
index
|
||||||
|
.RS 4
|
||||||
|
Index of file\&. Starting with 1\&. This is the same order with the files in multi\-file torrent\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
path
|
||||||
|
.RS 4
|
||||||
|
File path\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
length
|
||||||
|
.RS 4
|
||||||
|
File size in bytes\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
selected
|
||||||
|
.RS 4
|
||||||
|
"true" if this file is selected by
|
||||||
|
\fB\-\-select\-file\fR
|
||||||
|
option\&. If
|
||||||
|
\fB\-\-select\-file\fR
|
||||||
|
is not specified or this is single torrent or no torrent download, this value is always "true"\&. Otherwise "false"\&.
|
||||||
|
.RE
|
||||||
|
.sp
|
||||||
|
\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
|
||||||
|
peerId
|
||||||
|
.RS 4
|
||||||
|
Percent\-encoded peer ID\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
ip
|
||||||
|
.RS 4
|
||||||
|
IP address of the peer\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
port
|
||||||
|
.RS 4
|
||||||
|
Port number of the peer\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
bitfield
|
||||||
|
.RS 4
|
||||||
|
Hexadecimal representation of the download progress of the peer\&. The highest bit corresponds to piece index 0\&. The set bits indicate the piece is available and unset bits indicate the piece is missing\&. The spare bits at the end are set to zero\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
amChoking
|
||||||
|
.RS 4
|
||||||
|
"true" if this client is choking the peer\&. Otherwise "false"\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
peerChoking
|
||||||
|
.RS 4
|
||||||
|
"true" if the peer is choking this client\&. Otherwise "false"\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
downloadSpeed
|
||||||
|
.RS 4
|
||||||
|
Download speed (byte/sec) that this client obtains from the peer\&.
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
uploadSpeed
|
||||||
|
.RS 4
|
||||||
|
Upload speed(byte/sec) that this client uploads to the peer\&.
|
||||||
|
.RE
|
||||||
|
.sp
|
||||||
|
\fBaria2\&.tellActive\fR
|
||||||
|
.sp
|
||||||
|
This method returns the list of active downloads\&. The respose is of type array and its element is the same struct returned by \fBaria2\&.tellStatus\fR method\&.
|
||||||
|
.sp
|
||||||
|
\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 \fBmax\-download\-limit\fR and \fBmax\-upload\-limit\fR\&. This method returns "OK" for success\&.
|
||||||
|
.sp
|
||||||
|
\fBaria2\&.changeGlobalOption\fR \fIoptions\fR
|
||||||
|
.sp
|
||||||
|
This method changes global options dynamically\&. \fIoptions\fR is of type struct and the available options are \fBmax\-overall\-download\-limit\fR and \fBmax\-overall\-upload\-limit\fR\&. This method returns "OK" for success\&.
|
||||||
|
.sp
|
||||||
|
\fBaria2\&.purgeDownloadResult\fR
|
||||||
|
.sp
|
||||||
|
This method purges completed/error/removed downloads to free memory\&. This method returns "OK"\&.
|
||||||
|
.SS "Error Handling"
|
||||||
|
.sp
|
||||||
|
In case of error, aria2 returns faultCode=1 and the error message in faultString\&.
|
||||||
|
.SS "Options"
|
||||||
|
.sp
|
||||||
|
Same options for \fB\-i\fR list are available\&. See \fBInput File\fR subsection for complete list of options\&.
|
||||||
|
.sp
|
||||||
|
In the option struct, name element is option name(without preceeding "\-\-") and value element is argument as string\&.
|
||||||
|
.sp
|
||||||
|
.if n \{\
|
||||||
|
.RS 4
|
||||||
|
.\}
|
||||||
|
.nf
|
||||||
|
<struct>
|
||||||
|
<member>
|
||||||
|
<name>split</name>
|
||||||
|
<value><string>1</string></value>
|
||||||
|
</member>
|
||||||
|
<member>
|
||||||
|
<name>http\-proxy</name>
|
||||||
|
<value><string>http://proxy/</string></value>
|
||||||
|
</member>
|
||||||
|
</struct>
|
||||||
|
.fi
|
||||||
|
.if n \{\
|
||||||
|
.RE
|
||||||
|
.\}
|
||||||
|
.sp
|
||||||
|
\fBheader\fR and \fBindex\-out\fR option are allowed multiple times in command\-line\&. Since name should be unique in struct(many XML\-RPC library implementation uses hash or dict for struct), single string is not enough\&. To overcome this situation, they can take array as value as well as string\&.
|
||||||
|
.sp
|
||||||
|
.if n \{\
|
||||||
|
.RS 4
|
||||||
|
.\}
|
||||||
|
.nf
|
||||||
|
<struct>
|
||||||
|
<member>
|
||||||
|
<name>header</name>
|
||||||
|
<value>
|
||||||
|
<array>
|
||||||
|
<data>
|
||||||
|
<value><string>Accept\-Language: ja</string></value>
|
||||||
|
<value><string>Accept\-Charset: utf\-8</string></value>
|
||||||
|
</data>
|
||||||
|
</array>
|
||||||
|
</value>
|
||||||
|
</member>
|
||||||
|
</struct>
|
||||||
|
.fi
|
||||||
|
.if n \{\
|
||||||
|
.RE
|
||||||
|
.\}
|
||||||
|
.SS "Sample XML\-RPC Client Code"
|
||||||
|
.sp
|
||||||
|
The following Ruby script adds \fIhttp://localhost/aria2\&.tar\&.bz2\fR to aria2c operated on localhost with option \fB\-\-dir\fR=\fI/downloads\fR and prints its reponse\&.
|
||||||
|
.sp
|
||||||
|
.if n \{\
|
||||||
|
.RS 4
|
||||||
|
.\}
|
||||||
|
.nf
|
||||||
|
#!/usr/bin/env ruby
|
||||||
|
|
||||||
|
require \'xmlrpc/client\'
|
||||||
|
require \'pp\'
|
||||||
|
|
||||||
|
client=XMLRPC::Client\&.new2("http://localhost:6800/rpc")
|
||||||
|
|
||||||
|
options={ "dir" => "/downloads" }
|
||||||
|
result=client\&.call("aria2\&.addUri", [ "http://localhost/aria2\&.tar\&.bz2" ], options)
|
||||||
|
|
||||||
|
pp result
|
||||||
|
.fi
|
||||||
|
.if n \{\
|
||||||
|
.RE
|
||||||
|
.\}
|
||||||
.SH "EXAMPLE"
|
.SH "EXAMPLE"
|
||||||
.SS "HTTP/FTP Segmented Download"
|
.SS "HTTP/FTP Segmented Download"
|
||||||
.sp
|
.sp
|
||||||
|
|
|
||||||
|
|
@ -2389,6 +2389,355 @@ ignored.</p></div>
|
||||||
host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR</tt></pre>
|
host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR</tt></pre>
|
||||||
</div></div>
|
</div></div>
|
||||||
</div>
|
</div>
|
||||||
|
<h2 id="_xml_rpc_interface">XML-RPC INTERFACE</h2>
|
||||||
|
<div class="sectionbody">
|
||||||
|
<h3 id="_terminology">Terminology</h3><div style="clear:left"></div>
|
||||||
|
<div class="dlist"><dl>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
GID
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
GID(or gid) is the key to manage each download. Each download has an
|
||||||
|
unique GID. Currently GID looks like an integer, but don’t treat it
|
||||||
|
as integer because it may be changed to another type in the future
|
||||||
|
release.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
</dl></div>
|
||||||
|
<h3 id="_methods">Methods</h3><div style="clear:left"></div>
|
||||||
|
<div class="paragraph"><p><strong>aria2.addUri</strong> <em>uris[, options]</em></p></div>
|
||||||
|
<div class="paragraph"><p>This method adds new HTTP(S)/FTP download. <em>uris</em> is of type array
|
||||||
|
and its element is URI which is of type string. URI should be
|
||||||
|
percent-encoded. <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.
|
||||||
|
This method returns GID of registered download.</p></div>
|
||||||
|
<div class="paragraph"><p><strong>aria2.addTorrent</strong> <em>torrent[, uris[, options]]</em></p></div>
|
||||||
|
<div class="paragraph"><p>This method adds BitTorrent download by uploading .torrent file.
|
||||||
|
<em>torrent</em> is of type base64 which contains Base64-encoded .torrent
|
||||||
|
file. <em>uris</em> is of type array and its element is URI which is of type
|
||||||
|
string. <em>uris</em> is used for Web-seeding. Note that <em>uris</em> is ignored if
|
||||||
|
specified torrent is a multi-file torrent. <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. This method returns GID of
|
||||||
|
registered download.</p></div>
|
||||||
|
<div class="paragraph"><p><strong>aria2.addMetalink</strong> <em>metalink[, options]</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
|
||||||
|
option name and value. See <strong>Options</strong> below for more details. This
|
||||||
|
method returns GID of registered download.</p></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.tellStatus</strong> <em>gid</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. The response is of type struct and it
|
||||||
|
contains following keys. The value type is string.</p></div>
|
||||||
|
<div class="dlist"><dl>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
gid
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
GID of this download.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
status
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
"active" for currently downloading/seeding entry. "waiting" for the
|
||||||
|
entry in the queue; download is not started. "error" for the stopped
|
||||||
|
download because of error. "complete" for the stopped and completed
|
||||||
|
download. "removed" for the download removed by user.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
totalLength
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Total length of this download in bytes.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
completedLength
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Completed length of this download in bytes.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
bitfield
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Hexadecimal representation of the download progress. The highest bit
|
||||||
|
corresponds to piece index 0. The set bits indicate the piece is
|
||||||
|
available and unset bits indicate the piece is missing. The spare
|
||||||
|
bits at the end are set to zero.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
downloadSpeed
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Download speed of this download measured in bytes/sec.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
uploadSpeed
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Upload speed of this download measured in bytes/sec.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
infoHash
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
InfoHash. BitTorrent only.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
pieceLength
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Piece length in bytes.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
numPieces
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
The number of pieces.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
connections
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
The number of peers/servers the client has connected to.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
</dl></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>
|
||||||
|
<div class="dlist"><dl>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
uri
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
URI
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
</dl></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>
|
||||||
|
<div class="dlist"><dl>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
index
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Index of file. Starting with 1. This is the same order with the
|
||||||
|
files in multi-file torrent.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
path
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
File path.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
length
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
File size in bytes.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
selected
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
"true" if this file is selected by <strong>--select-file</strong> option. If
|
||||||
|
<strong>--select-file</strong> is not specified or this is single torrent or no
|
||||||
|
torrent download, this value is always "true". Otherwise "false".
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
</dl></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
|
||||||
|
following keys. The value type is string.</p></div>
|
||||||
|
<div class="dlist"><dl>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
peerId
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Percent-encoded peer ID.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
ip
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
IP address of the peer.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
port
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Port number of the peer.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
bitfield
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Hexadecimal representation of the download progress of the peer. The
|
||||||
|
highest bit corresponds to piece index 0. The set bits indicate the
|
||||||
|
piece is available and unset bits indicate the piece is missing. The
|
||||||
|
spare bits at the end are set to zero.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
amChoking
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
"true" if this client is choking the peer. Otherwise "false".
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
peerChoking
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
"true" if the peer is choking this client. Otherwise "false".
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
downloadSpeed
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Download speed (byte/sec) that this client obtains from the peer.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt class="hdlist1">
|
||||||
|
uploadSpeed
|
||||||
|
</dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Upload speed(byte/sec) that this client uploads to the peer.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
</dl></div>
|
||||||
|
<div class="paragraph"><p><strong>aria2.tellActive</strong></p></div>
|
||||||
|
<div class="paragraph"><p>This method returns the list of active downloads. The respose 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.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>max-download-limit</strong> and <strong>max-upload-limit</strong>.
|
||||||
|
This method returns "OK" for success.</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-overall-download-limit</strong> and
|
||||||
|
<strong>max-overall-upload-limit</strong>. This method returns "OK" for success.</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>
|
||||||
|
<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>
|
||||||
|
<h3 id="_options_2">Options</h3><div style="clear:left"></div>
|
||||||
|
<div class="paragraph"><p>Same options for <strong>-i</strong> list are available. See <strong>Input File</strong> subsection
|
||||||
|
for complete list of options.</p></div>
|
||||||
|
<div class="paragraph"><p>In the option struct, name element is option name(without preceeding
|
||||||
|
"--") and value element is argument as string.</p></div>
|
||||||
|
<div class="listingblock">
|
||||||
|
<div class="content">
|
||||||
|
<pre><tt><struct>
|
||||||
|
<member>
|
||||||
|
<name>split</name>
|
||||||
|
<value><string>1</string></value>
|
||||||
|
</member>
|
||||||
|
<member>
|
||||||
|
<name>http-proxy</name>
|
||||||
|
<value><string>http://proxy/</string></value>
|
||||||
|
</member>
|
||||||
|
</struct></tt></pre>
|
||||||
|
</div></div>
|
||||||
|
<div class="paragraph"><p><strong>header</strong> and <strong>index-out</strong> option are allowed multiple times in
|
||||||
|
command-line. Since name should be unique in struct(many XML-RPC
|
||||||
|
library implementation uses hash or dict for struct), single string is
|
||||||
|
not enough. To overcome this situation, they can take array as value
|
||||||
|
as well as string.</p></div>
|
||||||
|
<div class="listingblock">
|
||||||
|
<div class="content">
|
||||||
|
<pre><tt><struct>
|
||||||
|
<member>
|
||||||
|
<name>header</name>
|
||||||
|
<value>
|
||||||
|
<array>
|
||||||
|
<data>
|
||||||
|
<value><string>Accept-Language: ja</string></value>
|
||||||
|
<value><string>Accept-Charset: utf-8</string></value>
|
||||||
|
</data>
|
||||||
|
</array>
|
||||||
|
</value>
|
||||||
|
</member>
|
||||||
|
</struct></tt></pre>
|
||||||
|
</div></div>
|
||||||
|
<h3 id="_sample_xml_rpc_client_code">Sample XML-RPC Client Code</h3><div style="clear:left"></div>
|
||||||
|
<div class="paragraph"><p>The following Ruby script adds <em>http://localhost/aria2.tar.bz2</em> to
|
||||||
|
aria2c operated on localhost with option <strong>--dir</strong>=<em>/downloads</em> and
|
||||||
|
prints its reponse.</p></div>
|
||||||
|
<div class="listingblock">
|
||||||
|
<div class="content">
|
||||||
|
<pre><tt>#!/usr/bin/env ruby
|
||||||
|
|
||||||
|
require 'xmlrpc/client'
|
||||||
|
require 'pp'
|
||||||
|
|
||||||
|
client=XMLRPC::Client.new2("http://localhost:6800/rpc")
|
||||||
|
|
||||||
|
options={ "dir" => "/downloads" }
|
||||||
|
result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options)
|
||||||
|
|
||||||
|
pp result</tt></pre>
|
||||||
|
</div></div>
|
||||||
|
</div>
|
||||||
<h2 id="_example">EXAMPLE</h2>
|
<h2 id="_example">EXAMPLE</h2>
|
||||||
<div class="sectionbody">
|
<div class="sectionbody">
|
||||||
<h3 id="_http_ftp_segmented_download">HTTP/FTP Segmented Download</h3><div style="clear:left"></div>
|
<h3 id="_http_ftp_segmented_download">HTTP/FTP Segmented Download</h3><div style="clear:left"></div>
|
||||||
|
|
@ -2780,7 +3129,7 @@ files in the program, then also delete it here.</p></div>
|
||||||
</div>
|
</div>
|
||||||
<div id="footer">
|
<div id="footer">
|
||||||
<div id="footer-text">
|
<div id="footer-text">
|
||||||
Last updated 2009-05-23 00:00:58 JST
|
Last updated 2009-05-26 23:15:48 JST
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</body>
|
</body>
|
||||||
|
|
|
||||||
278
doc/aria2c.1.txt
278
doc/aria2c.1.txt
|
|
@ -1017,6 +1017,284 @@ host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=O
|
||||||
host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR
|
host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR
|
||||||
--------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
XML-RPC INTERFACE
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Terminology
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
GID::
|
||||||
|
|
||||||
|
GID(or gid) is the key to manage each download. Each download has an
|
||||||
|
unique GID. Currently GID looks like an integer, but don't treat it
|
||||||
|
as integer because it may be changed to another type in the future
|
||||||
|
release.
|
||||||
|
|
||||||
|
Methods
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
*aria2.addUri* 'uris[, options]'
|
||||||
|
|
||||||
|
This method adds new HTTP(S)/FTP download. 'uris' is of type array
|
||||||
|
and its element is URI which is of type string. URI should be
|
||||||
|
percent-encoded. 'options' is of type struct and its members are a
|
||||||
|
pair of option name and value. See *Options* below for more details.
|
||||||
|
This method returns GID of registered download.
|
||||||
|
|
||||||
|
*aria2.addTorrent* 'torrent[, uris[, options]]'
|
||||||
|
|
||||||
|
This method adds BitTorrent download by uploading .torrent file.
|
||||||
|
'torrent' is of type base64 which contains Base64-encoded .torrent
|
||||||
|
file. 'uris' is of type array and its element is URI which is of type
|
||||||
|
string. 'uris' is used for Web-seeding. Note that 'uris' is ignored if
|
||||||
|
specified torrent is a multi-file torrent. 'options' is of type
|
||||||
|
struct and its members are a pair of option name and value. See
|
||||||
|
*Options* below for more details. This method returns GID of
|
||||||
|
registered download.
|
||||||
|
|
||||||
|
*aria2.addMetalink* 'metalink[, options]'
|
||||||
|
|
||||||
|
This method adds Metalink download by uploading .metalink file.
|
||||||
|
'metalink' is of type base64 which contains Base64-encoded .metalink
|
||||||
|
file. 'options' is of type struct and its members are a pair of
|
||||||
|
option name and value. See *Options* below for more details. This
|
||||||
|
method returns GID of registered download.
|
||||||
|
|
||||||
|
*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.tellStatus* 'gid'
|
||||||
|
|
||||||
|
This method returns download progress of the download denoted by
|
||||||
|
'gid'. 'gid' is of type string. The response is of type struct and it
|
||||||
|
contains following keys. The value type is string.
|
||||||
|
|
||||||
|
gid::
|
||||||
|
|
||||||
|
GID of this download.
|
||||||
|
|
||||||
|
status::
|
||||||
|
|
||||||
|
"active" for currently downloading/seeding entry. "waiting" for the
|
||||||
|
entry in the queue; download is not started. "error" for the stopped
|
||||||
|
download because of error. "complete" for the stopped and completed
|
||||||
|
download. "removed" for the download removed by user.
|
||||||
|
|
||||||
|
totalLength::
|
||||||
|
|
||||||
|
Total length of this download in bytes.
|
||||||
|
|
||||||
|
completedLength::
|
||||||
|
|
||||||
|
Completed length of this download in bytes.
|
||||||
|
|
||||||
|
bitfield::
|
||||||
|
|
||||||
|
Hexadecimal representation of the download progress. The highest bit
|
||||||
|
corresponds to piece index 0. The set bits indicate the piece is
|
||||||
|
available and unset bits indicate the piece is missing. The spare
|
||||||
|
bits at the end are set to zero.
|
||||||
|
|
||||||
|
downloadSpeed::
|
||||||
|
|
||||||
|
Download speed of this download measured in bytes/sec.
|
||||||
|
|
||||||
|
uploadSpeed::
|
||||||
|
|
||||||
|
Upload speed of this download measured in bytes/sec.
|
||||||
|
|
||||||
|
infoHash::
|
||||||
|
|
||||||
|
InfoHash. BitTorrent only.
|
||||||
|
|
||||||
|
pieceLength::
|
||||||
|
|
||||||
|
Piece length in bytes.
|
||||||
|
|
||||||
|
numPieces::
|
||||||
|
|
||||||
|
The number of pieces.
|
||||||
|
|
||||||
|
connections::
|
||||||
|
|
||||||
|
The number of peers/servers the client has connected to.
|
||||||
|
|
||||||
|
*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
|
||||||
|
type struct and it contains following keys. The value type is string.
|
||||||
|
|
||||||
|
uri::
|
||||||
|
|
||||||
|
URI
|
||||||
|
|
||||||
|
*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
|
||||||
|
type struct and it contains following keys. The value type is string.
|
||||||
|
|
||||||
|
index::
|
||||||
|
|
||||||
|
Index of file. Starting with 1. This is the same order with the
|
||||||
|
files in multi-file torrent.
|
||||||
|
|
||||||
|
path::
|
||||||
|
|
||||||
|
File path.
|
||||||
|
|
||||||
|
length::
|
||||||
|
|
||||||
|
File size in bytes.
|
||||||
|
|
||||||
|
selected::
|
||||||
|
|
||||||
|
"true" if this file is selected by *--select-file* option. If
|
||||||
|
*--select-file* is not specified or this is single torrent or no
|
||||||
|
torrent download, this value is always "true". Otherwise "false".
|
||||||
|
|
||||||
|
|
||||||
|
*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
|
||||||
|
is of type array and its element is of type struct and it contains
|
||||||
|
following keys. The value type is string.
|
||||||
|
|
||||||
|
peerId::
|
||||||
|
|
||||||
|
Percent-encoded peer ID.
|
||||||
|
|
||||||
|
ip::
|
||||||
|
|
||||||
|
IP address of the peer.
|
||||||
|
|
||||||
|
port::
|
||||||
|
|
||||||
|
Port number of the peer.
|
||||||
|
|
||||||
|
bitfield::
|
||||||
|
|
||||||
|
Hexadecimal representation of the download progress of the peer. The
|
||||||
|
highest bit corresponds to piece index 0. The set bits indicate the
|
||||||
|
piece is available and unset bits indicate the piece is missing. The
|
||||||
|
spare bits at the end are set to zero.
|
||||||
|
|
||||||
|
amChoking::
|
||||||
|
|
||||||
|
"true" if this client is choking the peer. Otherwise "false".
|
||||||
|
|
||||||
|
peerChoking::
|
||||||
|
|
||||||
|
"true" if the peer is choking this client. Otherwise "false".
|
||||||
|
|
||||||
|
downloadSpeed::
|
||||||
|
|
||||||
|
Download speed (byte/sec) that this client obtains from the peer.
|
||||||
|
|
||||||
|
uploadSpeed::
|
||||||
|
|
||||||
|
Upload speed(byte/sec) that this client uploads to the peer.
|
||||||
|
|
||||||
|
*aria2.tellActive*
|
||||||
|
|
||||||
|
This method returns the list of active downloads. The respose is of
|
||||||
|
type array and its element is the same struct returned by
|
||||||
|
*aria2.tellStatus* method.
|
||||||
|
|
||||||
|
*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
|
||||||
|
and the available options are *max-download-limit* and *max-upload-limit*.
|
||||||
|
This method returns "OK" for success.
|
||||||
|
|
||||||
|
*aria2.changeGlobalOption* 'options'
|
||||||
|
|
||||||
|
This method changes global options dynamically. 'options' is of type
|
||||||
|
struct and the available options are *max-overall-download-limit* and
|
||||||
|
*max-overall-upload-limit*. This method returns "OK" for success.
|
||||||
|
|
||||||
|
*aria2.purgeDownloadResult*
|
||||||
|
|
||||||
|
This method purges completed/error/removed downloads to free memory.
|
||||||
|
This method returns "OK".
|
||||||
|
|
||||||
|
Error Handling
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
In case of error, aria2 returns faultCode=1 and the error message in
|
||||||
|
faultString.
|
||||||
|
|
||||||
|
Options
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
Same options for *-i* list are available. See *Input File* subsection
|
||||||
|
for complete list of options.
|
||||||
|
|
||||||
|
In the option struct, name element is option name(without preceeding
|
||||||
|
"--") and value element is argument as string.
|
||||||
|
|
||||||
|
-------------------------------------------------
|
||||||
|
<struct>
|
||||||
|
<member>
|
||||||
|
<name>split</name>
|
||||||
|
<value><string>1</string></value>
|
||||||
|
</member>
|
||||||
|
<member>
|
||||||
|
<name>http-proxy</name>
|
||||||
|
<value><string>http://proxy/</string></value>
|
||||||
|
</member>
|
||||||
|
</struct>
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
*header* and *index-out* option are allowed multiple times in
|
||||||
|
command-line. Since name should be unique in struct(many XML-RPC
|
||||||
|
library implementation uses hash or dict for struct), single string is
|
||||||
|
not enough. To overcome this situation, they can take array as value
|
||||||
|
as well as string.
|
||||||
|
|
||||||
|
---------------------------------------------------------------
|
||||||
|
<struct>
|
||||||
|
<member>
|
||||||
|
<name>header</name>
|
||||||
|
<value>
|
||||||
|
<array>
|
||||||
|
<data>
|
||||||
|
<value><string>Accept-Language: ja</string></value>
|
||||||
|
<value><string>Accept-Charset: utf-8</string></value>
|
||||||
|
</data>
|
||||||
|
</array>
|
||||||
|
</value>
|
||||||
|
</member>
|
||||||
|
</struct>
|
||||||
|
---------------------------------------------------------------
|
||||||
|
|
||||||
|
Sample XML-RPC Client Code
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The following Ruby script adds 'http://localhost/aria2.tar.bz2' to
|
||||||
|
aria2c operated on localhost with option *--dir*='/downloads' and
|
||||||
|
prints its reponse.
|
||||||
|
|
||||||
|
----------------------------------------------
|
||||||
|
#!/usr/bin/env ruby
|
||||||
|
|
||||||
|
require 'xmlrpc/client'
|
||||||
|
require 'pp'
|
||||||
|
|
||||||
|
client=XMLRPC::Client.new2("http://localhost:6800/rpc")
|
||||||
|
|
||||||
|
options={ "dir" => "/downloads" }
|
||||||
|
result=client.call("aria2.addUri", [ "http://localhost/aria2.tar.bz2" ], options)
|
||||||
|
|
||||||
|
pp result
|
||||||
|
----------------------------------------------
|
||||||
|
|
||||||
EXAMPLE
|
EXAMPLE
|
||||||
-------
|
-------
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue