diff --git a/doc/manual-src/en/aria2c.rst b/doc/manual-src/en/aria2c.rst index 31b8e8f7..c073ab53 100644 --- a/doc/manual-src/en/aria2c.rst +++ b/doc/manual-src/en/aria2c.rst @@ -1135,6 +1135,17 @@ Advanced Options save BitTorrent seeding which is recognized as completed state. Default: ``false`` +.. option:: --gid= + + Set GID manually. aria2 identifies each download by the ID called + GID. The GID must be hex string of 16 characters, thus [0-9a-zA-Z] + are allowed and leading zeros must not be stripped. The GID all 0 is + reserved and must not be used. The GID must be unique, otherwise + error is reported and the download is not added. This option is + useful when restoring the sessions saved using + :option:`--save-session <--save-session>` option. If this option is + not used, new GID is generated by aria2. + .. option:: --hash-check-only[=true|false] If ``true`` is given, after hash check using @@ -1817,8 +1828,8 @@ For example, the content of uri.txt is:: If aria2 is executed with ``-i uri.txt -d /tmp`` options, then ``file.iso`` is saved as ``/iso_images/file.img`` and it is downloaded -from \http://server/file.iso and \http://mirror/file.iso. The file -``bar`` is downloaded from \http://foo/bar and saved as ``/tmp/bar``. +from ``http://server/file.iso`` and ``http://mirror/file.iso``. The file +``bar`` is downloaded from ``http://foo/bar`` and saved as ``/tmp/bar``. In some cases, :option:`out <-o>` parameter has no effect. See note of :option:`--out <-o>` @@ -1908,11 +1919,14 @@ 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. Please note that GID is session local and not persisted - when aria2 exits. + unique GID. GID is stored in 64 bits binary data in aria2. For RPC + access, it is represented in hex string of 16 characters (e.g., + ``2089b05ecca3d829``). Normally, aria2 generates this GID for each + download, but the user can specify GID manually using :option:`--gid + <--gid>` option. When querying download by GID, you can specify the + prefix of GID as long as it is a unique prefix among others. Methods ~~~~~~~ @@ -1922,10 +1936,6 @@ All code examples come from Python2.7 interpreter. .. function:: 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 @@ -1938,53 +1948,42 @@ All code examples come from Python2.7 interpreter. *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. - + **JSON-RPC Example** - - - The following example adds \http://example.org/file to aria2:: - + + The following example adds ``http://example.org/file``:: + >>> import urllib2, json >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', ... 'method':'aria2.addUri', ... 'params':[['http://example.org/file']]}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> c.read() - '{"id":"qwer","jsonrpc":"2.0","result":"1"}' - - + '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}' + **XML-RPC Example** - - - The following example adds \http://example.org/file to aria2:: - + + The following example adds ``http://example.org/file``:: + >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') >>> s.aria2.addUri(['http://example.org/file']) - '1' - - + '2089b05ecca3d829' + The following example adds 2 sources and some options:: - + >>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'], dict(dir="/tmp")) - '2' - - + 'd2703803b52216d1' + The following example adds a download and insert it to the front of waiting downloads:: - + >>> s.aria2.addUri(['http://example.org/file'], {}, 0) - '3' - - + 'ca3d829cee549a4d' .. function:: aria2.addTorrent(torrent[, uris[, options[, position]]]) - - - - This method adds BitTorrent download by uploading ".torrent" file. If you want to add BitTorrent Magnet URI, use :func:`aria2.addUri` method instead. *torrent* is of type base64 which contains @@ -2009,39 +2008,32 @@ All code examples come from Python2.7 interpreter. successfully or :option:`--rpc-save-upload-metadata` is ``false``, the downloads added by this method are not saved by :option:`--save-session`. - + + The following examples add local file ``file.torrent``. + **JSON-RPC Example** - - - The following example adds local file file.torrent to aria2:: - + + :: + >>> import urllib2, json, base64 >>> torrent = base64.b64encode(open('file.torrent').read()) >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf', ... 'method':'aria2.addTorrent', 'params':[torrent]}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> c.read() - '{"id":"asdf","jsonrpc":"2.0","result":"6"}' - - + '{"id":"asdf","jsonrpc":"2.0","result":"2089b05ecca3d829"}' + **XML-RPC Example** - - - The following example adds 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' - - + '2089b05ecca3d829' .. function:: aria2.addMetalink(metalink[, options[, position]]) - - - - 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 @@ -2060,216 +2052,169 @@ All code examples come from Python2.7 interpreter. successfully or :option:`--rpc-save-upload-metadata` is ``false``, the downloads added by this method are not saved by :option:`--save-session`. - + + The following examples add local file file.meta4. + **JSON-RPC Example** - - - The following example adds local file file.meta4 to aria2:: - + + :: + >>> import urllib2, json, base64 >>> metalink = base64.b64encode(open('file.meta4').read()) >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.addMetalink', 'params':[metalink]}) + ... 'method':'aria2.addMetalink', + ... 'params':[metalink]}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> c.read() - '{"id":"qwer","jsonrpc":"2.0","result":["8"]}' - - + '{"id":"qwer","jsonrpc":"2.0","result":["2089b05ecca3d829"]}' + **XML-RPC Example** - - - The following example adds 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'] - - + ['2089b05ecca3d829'] .. function:: 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 + first. The status of removed download becomes ``removed``. This method returns GID of removed download. - + + The following examples remove download GID#2089b05ecca3d829. + **JSON-RPC Example** - - - The following example removes download whose GID is "3":: - + + :: + >>> import urllib2, json >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.remove', 'params':['3']}) + ... 'method':'aria2.remove', + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> c.read() - '{"id":"qwer","jsonrpc":"2.0","result":"3"}' - - + '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}' + **XML-RPC Example** - - - The following example removes download whose GID is "3":: - + + :: + >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') - >>> s.aria2.remove('3') - '3' - - + >>> s.aria2.remove('2089b05ecca3d829') + '2089b05ecca3d829' .. function:: aria2.forceRemove(gid) - - - - This method removes the download denoted by *gid*. This method behaves just like :func:`aria2.remove` except that this method removes download without any action which takes time such as contacting BitTorrent tracker. - .. function:: 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 + 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 :func:`aria2.unpause` method. + waiting queue. As long as the status is ``paused``, the download is not + started. To change status to ``waiting``, use :func:`aria2.unpause` method. This method returns GID of paused download. - .. function:: aria2.pauseAll() - - - - This method is equal to calling :func:`aria2.pause` for every active/waiting - download. This methods returns ``"OK"`` for success. - + download. This methods returns ``OK`` for success. .. function:: aria2.forcePause(pid) - - - - This method pauses the download denoted by *gid*. This method behaves just like :func:`aria2.pause` except that this method pauses download without any action which takes time such as contacting BitTorrent tracker. - .. function:: aria2.forcePauseAll() - - - - This method is equal to calling :func:`aria2.forcePause` for every - active/waiting download. This methods returns ``"OK"`` for success. - + active/waiting download. This methods returns ``OK`` for success. .. function:: 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. + ``paused`` to ``waiting``. This makes the download eligible to restart. *gid* is of type string. This method returns GID of unpaused download. - .. function:: aria2.unpauseAll() - - - - This method is equal to calling :func:`aria2.unpause` for every active/waiting - download. This methods returns ``"OK"`` for success. - + download. This methods returns ``OK`` for success. .. function:: 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 specified, the response contains only keys in *keys* array. If *keys* 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, ``aria2.tellStatus("1", ["gid", "status"])`` + transfers. For example, ``aria2.tellStatus("2089b05ecca3d829", ["gid", "status"])`` returns *gid* and 'status' key. 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. ``"paused"`` for the - paused entry. ``"error"`` for the stopped download because of - error. ``"complete"`` for the stopped and completed download. ``"removed"`` + ``active`` for currently downloading/seeding entry. ``waiting`` for the + entry in the queue; download is not started. ``paused`` for the + paused entry. ``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. - + ``uploadLength`` Uploaded 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. When download has not started yet, this key will not be included in the response. - + ``downloadSpeed`` Download speed of this download measured in bytes/sec. - + ``uploadSpeed`` Upload speed of this download measured in bytes/sec. - + ``infoHash`` InfoHash. BitTorrent only. - + ``numSeeders`` The number of seeders the client has connected to. BitTorrent only. - + ``pieceLength`` Piece length in bytes. - + ``numPieces`` The number of pieces. - + ``connections`` The number of peers/servers the client has connected to. - + ``errorCode`` The last error code occurred in this download. The value is of type string. The error codes are defined in `EXIT STATUS`_ section. This value is only available for stopped/completed downloads. - + ``followedBy`` List of GIDs which are generated by the consequence of this download. For example, when aria2 downloaded Metalink file, it @@ -2277,59 +2222,57 @@ All code examples come from Python2.7 interpreter. option). This value is useful to track these auto generated downloads. If there is no such downloads, this key will not be included in the response. - + ``belongsTo`` GID of a parent download. Some downloads are a part of another download. For example, if a file in Metalink has BitTorrent resource, the download of ".torrent" is a part of that file. If this download has no parent, this key will not be included in the response. - + ``dir`` Directory to save files. This key is not available for stopped downloads. - + ``files`` Returns the list of files. The element of list is the same struct used in :func:`aria2.getFiles` method. - - + ``bittorrent`` Struct which contains information retrieved from .torrent file. BitTorrent only. It contains following keys. - + ``announceList`` List of lists of announce URI. If ".torrent" file contains announce and no announce-list, announce is converted to announce-list format. - + ``comment`` - The comment for the torrent. comment.utf-8 is used if available. - + The comment for the torrent. ``comment.utf-8`` is used if available. + ``creationDate`` The creation time of the torrent. The value is an integer since the Epoch, measured in seconds. - + ``mode`` - File mode of the torrent. The value is either 'single' or 'multi'. - + File mode of the torrent. The value is either ``single`` or ``multi``. + ``info`` Struct which contains data from Info dictionary. It contains following keys. - + ``name`` - name in info dictionary. name.utf-8 is used if available. - + name in info dictionary. ``name.utf-8`` is used if available. + **JSON-RPC Example** - - - The following example gets information about download whose GID is - "1":: - + + The following example gets information about download GID#2089b05ecca3d829:: + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.tellStatus', 'params':['1']}) + ... 'method':'aria2.tellStatus', + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', @@ -2346,42 +2289,39 @@ All code examples come from Python2.7 interpreter. u'selected': u'true', u'uris': [{u'status': u'used', u'uri': u'http://example.org/file'}]}], - u'gid': u'1', + u'gid': u'2089b05ecca3d829', u'numPieces': u'34', u'pieceLength': u'1048576', u'status': u'active', u'totalLength': u'34896138', u'uploadLength': u'0', u'uploadSpeed': u'0'}} - - + The following example gets information specifying keys you are interested in:: - + >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', ... 'method':'aria2.tellStatus', - ... 'params':['1', ['gid', - ... 'totalLength', - ... 'completedLength']]}) + ... 'params':['2089b05ecca3d829', + ... ['gid', + ... 'totalLength', + ... 'completedLength']]}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': {u'completedLength': u'5701632', - u'gid': u'1', + u'gid': u'2089b05ecca3d829', u'totalLength': u'34896138'}} - - + **XML-RPC Example** - - - The following example gets information about download whose GID is - "1":: - + + The following example gets information about download GID#2089b05ecca3d829:: + >>> import xmlrpclib >>> from pprint import pprint >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') - >>> r = s.aria2.tellStatus('1') + >>> r = s.aria2.tellStatus('2089b05ecca3d829') >>> pprint(r) {'bitfield': 'ffff80', 'completedLength': '34896138', @@ -2396,88 +2336,75 @@ All code examples come from Python2.7 interpreter. 'selected': 'true', 'uris': [{'status': 'used', 'uri': 'http://example.org/file'}]}], - 'gid': '1', + 'gid': '2089b05ecca3d829', 'numPieces': '17', 'pieceLength': '2097152', 'status': 'complete', 'totalLength': '34896138', 'uploadLength': '0', 'uploadSpeed': '0'} - - + The following example gets information specifying keys you are interested in:: - - >>> r = s.aria2.tellStatus('1', ['gid', 'totalLength', 'completedLength']) + + >>> r = s.aria2.tellStatus('2089b05ecca3d829', ['gid', 'totalLength', 'completedLength']) >>> pprint(r) - {'completedLength': '34896138', 'gid': '1', 'totalLength': '34896138'} - - + {'completedLength': '34896138', 'gid': '2089b05ecca3d829', 'totalLength': '34896138'} .. function:: 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 - + ``status`` 'used' if the URI is already used. 'waiting' if the URI is waiting in the queue. - + **JSON-RPC Example** :: - + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.getUris', 'params':['1']}) + ... 'method':'aria2.getUris', + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [{u'status': u'used', u'uri': u'http://example.org/file'}]} - - + **XML-RPC Example** :: - + >>> import xmlrpclib >>> from pprint import pprint >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') - >>> r = s.aria2.getUris('1') + >>> r = s.aria2.getUris('2089b05ecca3d829') >>> pprint(r) [{'status': 'used', 'uri': 'http://example.org/file'}] - - .. function:: 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. - + ``completedLength`` Completed length of this file in bytes. Please note that it is possible that sum of completedLength is less than completedLength in @@ -2488,23 +2415,24 @@ All code examples come from Python2.7 interpreter. in :func:`aria2.tellStatus` takes into account of partially completed piece. - + ``selected`` - ``"true"`` if this file is selected by :option:`--select-file` option. If + ``true`` if this file is selected by :option:`--select-file` option. If :option:`--select-file` is not specified or this is single torrent or no - torrent download, this value is always ``"true"``. Otherwise ``"false"``. - + torrent download, this value is always ``true``. Otherwise ``false``. + ``uris`` Returns the list of URI for this file. The element of list is the same struct used in :func:`aria2.getUris` method. - + **JSON-RPC Example** :: - + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.getFiles', 'params':['1']}) + ... 'method':'aria2.getFiles', + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', @@ -2516,15 +2444,14 @@ All code examples come from Python2.7 interpreter. u'selected': u'true', u'uris': [{u'status': u'used', u'uri': u'http://example.org/file'}]}]} - - + **XML-RPC Example** :: - + >>> import xmlrpclib >>> from pprint import pprint >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') - >>> r = s.aria2.getFiles('1') + >>> r = s.aria2.getFiles('2089b05ecca3d829') >>> pprint(r) [{'index': '1', 'length': '34896138', @@ -2533,57 +2460,52 @@ All code examples come from Python2.7 interpreter. 'selected': 'true', 'uris': [{'status': 'used', 'uri': 'http://example.org/file'}]}] - - .. function:: 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"``. - + ``true`` if this client is choking the peer. Otherwise ``false``. + ``peerChoking`` - ``"true"`` if the peer is choking this client. Otherwise ``"false"``. - + ``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. - + Upload speed(byte/sec) that this client uploads to the peer. + ``seeder`` - ``"true"`` is this client is a seeder. Otherwise ``"false"``. - + ``true`` is this client is a seeder. Otherwise ``false``. + **JSON-RPC Example** :: - + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.getPeers', 'params':['1']}) + ... 'method':'aria2.getPeers', + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', @@ -2606,15 +2528,14 @@ All code examples come from Python2.7 interpreter. u'port': u'37842', u'seeder': u'false', u'uploadSpeed': u'6890'}]} - - + **XML-RPC Example** :: - + >>> import xmlrpclib >>> from pprint import pprint >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') - >>> r = s.aria2.getPeers('1') + >>> r = s.aria2.getPeers('2089b05ecca3d829') >>> pprint(r) [{'amChoking': 'true', 'bitfield': 'ffffffffffffffffffffffffffffffffffffffff', @@ -2634,43 +2555,38 @@ All code examples come from Python2.7 interpreter. 'port': '37842', 'seeder': 'false, 'uploadSpeed': '6890'}] - - .. function:: 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 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. - + ``servers`` The list of struct which contains following keys. - + ``uri`` URI originally added. - + ``currentUri`` This is the URI currently used for downloading. If redirection is involved, currentUri and uri may differ. - + ``downloadSpeed`` Download speed (byte/sec) - + **JSON-RPC Example** :: - + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.getServers', 'params':['1']}) + ... 'method':'aria2.getServers', + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', @@ -2679,139 +2595,110 @@ All code examples come from Python2.7 interpreter. u'servers': [{u'currentUri': u'http://example.org/file', u'downloadSpeed': u'10467', u'uri': u'http://example.org/file'}]}]} - - + **XML-RPC Example** :: - + >>> import xmlrpclib >>> from pprint import pprint >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') - >>> r = s.aria2.getServers('1') + >>> r = s.aria2.getServers('2089b05ecca3d829') >>> pprint(r) [{'index': '1', 'servers': [{'currentUri': 'http://example.org/dl/file', 'downloadSpeed': '20285', 'uri': 'http://example.org/file'}]}] - - .. function:: 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 :func:`aria2.tellStatus` method. For *keys* parameter, please refer to :func:`aria2.tellStatus` method. - .. function:: 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 the download waiting at the front. *num* is of type integer and specifies the number of downloads to be returned. For *keys* parameter, please refer to :func:`aria2.tellStatus` method. - + If *offset* is a positive integer, this method returns downloads in the range of [*offset*, *offset* + *num*). - + *offset* can be a negative integer. *offset* == -1 points last download in the waiting queue and *offset* == -2 points the download before the last download, and so on. The downloads in the response are in reversed order. - + For example, imagine that three downloads "A","B" and "C" are waiting - in this order. aria2.tellWaiting(0, 1) returns - ["A"]. aria2.tellWaiting(1, 2) returns ["B", "C"]. - aria2.tellWaiting(-1, 2) returns ["C", "B"]. - + in this order. ``aria2.tellWaiting(0, 1)`` returns + ``["A"]``. ``aria2.tellWaiting(1, 2)`` returns ``["B", "C"]``. + ``aria2.tellWaiting(-1, 2)`` returns ``["C", "B"]``. + The response is of type array and its element is the same struct returned by :func:`aria2.tellStatus` method. - .. function:: 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 type integer and specifies the number of downloads to be returned. For *keys* parameter, please refer to :func:`aria2.tellStatus` method. - + *offset* and *num* have the same semantics as :func:`aria2.tellWaiting` method. - + The response is of type array and its element is the same struct returned by :func:`aria2.tellStatus` method. - .. function:: 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 - ``"POS_SET"``, it moves the download to a position relative to the - beginning of the queue. If *how* is ``"POS_CUR"``, it moves the download - to a position relative to the current position. If *how* is ``"POS_END"``, + ``POS_SET``, it moves the download to a position relative to the + beginning of the queue. If *how* is ``POS_CUR``, it moves the download + to a position relative to the current position. If *how* 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. - - 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). - + + For example, if GID#2089b05ecca3d829 is placed in position 3, + ``aria2.changePosition('2089b05ecca3d829', -1, 'POS_CUR')`` will + change its position to 2. Additional + ``aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET')`` will + change its position to 0(the beginning of the queue). + + The following examples move the download GID#2089b05ecca3d829 to the + front of the waiting queue. + **JSON-RPC Example** - - - The following example moves the download whose GID is "3" to the - front of the waiting queue:: - + + :: + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', ... 'method':'aria2.changePosition', - ... 'params':['3', 0, 'POS_SET']}) + ... 'params':['2089b05ecca3d829', 0, 'POS_SET']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': 0} - - + **XML-RPC 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') + >>> s.aria2.changePosition('2089b05ecca3d829', 0, 'POS_SET') 0 - - .. function:: 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 list of string. A download can contain multiple files and URIs are @@ -2829,57 +2716,55 @@ All code examples come from Python2.7 interpreter. 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. - + + The following examples add 1 URI ``http://example.org/file`` to the + file whose index is ``1`` and belongs to the download + GID#2089b05ecca3d829. + **JSON-RPC 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 urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', ... 'method':'aria2.changeUri', - ... 'params':['2', 1, [], ['http://example.org/file']]}) + ... 'params':['2089b05ecca3d829', 1, [], + ['http://example.org/file']]}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [0, 1]} - - + **XML-RPC 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']) + >>> s.aria2.changeUri('2089b05ecca3d829', 1, [], + ['http://example.org/file']) [0, 1] - - .. function:: 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. Note that this method does not return options which have no default value and have not been set by the command-line options, configuration files or RPC methods. - + + The following examples get options of the download + GID#2089b05ecca3d829. + **JSON-RPC Example** - - - The following example gets options of the download whose GID is "1":: - + + :: + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', - ... 'method':'aria2.getOption', 'params':['1']}) + ... 'method':'aria2.getOption', + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', @@ -2889,43 +2774,35 @@ All code examples come from Python2.7 interpreter. u'always-resume': u'true', u'async-dns': u'true', ... - - + **XML-RPC 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') + >>> r = s.aria2.getOption('2089b05ecca3d829') >>> pprint(r) {'allow-overwrite': 'false', 'allow-piece-length-change': 'false', 'always-resume': 'true', 'async-dns': 'true', .... - - .. function:: 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. The following options are available for active downloads: - + * :option:`bt-max-peers <--bt-max-peers>` * :option:`bt-request-peer-speed-limit <--bt-request-peer-speed-limit>` * :option:`bt-remove-unselected-file <--bt-remove-unselected-file>` * :option:`force-save <--force-save>` * :option:`max-download-limit <--max-download-limit>` * :option:`max-upload-limit <-u>` - + For waiting or paused downloads, in addition to the above options, options listed in `Input File`_ subsection are available, except for following options: @@ -2935,45 +2812,37 @@ All code examples come from Python2.7 interpreter. :option:`pause <--pause>`, :option:`piece-length <--piece-length>` and :option:`rpc-save-upload-metadata <--rpc-save-upload-metadata>` option. - This method returns ``"OK"`` for success. - + This method returns ``OK`` for success. + + The following examples set :option:`max-download-limit + <--max-download-limit>` option to ``20K`` for the download + GID#2089b05ecca3d829. + **JSON-RPC Example** - - - The following example sets - :option:`max-download-limit <--max-download-limit>` option to ``"20K"`` for - the download whose GID is "1":: - + + :: + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', ... 'method':'aria2.changeOption', - ... 'params':['1', {'max-download-limit':'10K'}]}) + ... 'params':['2089b05ecca3d829', + ... {'max-download-limit':'10K'}]}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'} - - + **XML-RPC Example** - - - The following example sets - :option:`max-download-limit <--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'}) + >>> s.aria2.changeOption('2089b05ecca3d829', {'max-download-limit':'20K'}) 'OK' - - .. function:: 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. Note that this method does not return options which have no default @@ -2981,18 +2850,13 @@ All code examples come from Python2.7 interpreter. files or RPC methods. Because global options are used as a template for the options of newly added download, the response contains keys returned by :func:`aria2.getOption` method. - .. function:: aria2.changeGlobalOption(options) - - - - This method changes global options dynamically. *options* is of type struct. The following options are available: - + * :option:`download-result <--download-result>` * :option:`log <-l>` * :option:`log-level <--log-level>` @@ -3003,7 +2867,7 @@ All code examples come from Python2.7 interpreter. * :option:`save-cookies <--save-cookies>` * :option:`save-session <--save-session>` * :option:`server-stat-of <--server-stat-of>` - + In addition to them, options listed in `Input File`_ subsection are available, except for following options: :option:`checksum <--checksum>`, @@ -3011,41 +2875,36 @@ All code examples come from Python2.7 interpreter. :option:`out <-o>`, :option:`pause <--pause>` and :option:`select-file <--select-file>`. - + Using :option:`log <-l>` 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. - + returns ``OK`` for success. .. function:: aria2.getGlobalStat() - - - - This method returns global statistics such as overall download and upload speed. The response is of type struct and contains following keys. The value type is string. - + ``downloadSpeed`` Overall download speed (byte/sec). - + ``uploadSpeed`` Overall upload speed(byte/sec). - + ``numActive`` The number of active downloads. - + ``numWaiting`` The number of waiting downloads. - + ``numStopped`` The number of stopped downloads. - + **JSON-RPC Example** :: - + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', @@ -3059,11 +2918,10 @@ All code examples come from Python2.7 interpreter. u'numStopped': u'0', u'numWaiting': u'0', u'uploadSpeed': u'0'}} - - + **XML-RPC Example** :: - + >>> import xmlrpclib >>> from pprint import pprint >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') @@ -3074,75 +2932,56 @@ All code examples come from Python2.7 interpreter. 'numStopped': '0', 'numWaiting': '0', 'uploadSpeed': '0'} - - .. function:: aria2.purgeDownloadResult() - - - - This method purges completed/error/removed downloads to free memory. - This method returns ``"OK"``. - + This method returns ``OK``. .. function:: aria2.removeDownloadResult(gid) - - - - This method removes completed/error/removed download denoted by *gid* - from memory. This method returns ``"OK"`` for success. - + from memory. This method returns ``OK`` for success. + + The following examples remove the download result of the download + GID#2089b05ecca3d829. + **JSON-RPC Example** - - - The following example removes the download result of the download - whose GID is "1":: - + + :: + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', ... 'method':'aria2.removeDownloadResult', - ... 'params':['1']}) + ... 'params':['2089b05ecca3d829']}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'OK'} - - + **XML-RPC Example** - - - The following example removes the download result of the download - whose GID is "1":: - + + :: + >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') - >>> s.aria2.removeDownloadResult('1') + >>> s.aria2.removeDownloadResult('2089b05ecca3d829') 'OK' - - .. function:: 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. - + ``version`` Version number of the program in string. - + ``enabledFeatures`` List of enabled features. Each feature name is of type string. - + **JSON-RPC Example** :: - + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', @@ -3160,11 +2999,10 @@ All code examples come from Python2.7 interpreter. u'Metalink', u'XML-RPC'], u'version': u'1.11.0'}} - - + **XML-RPC Example** :: - + >>> import xmlrpclib >>> from pprint import pprint >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') @@ -3179,24 +3017,18 @@ All code examples come from Python2.7 interpreter. 'Metalink', 'XML-RPC'], 'version': '1.11.0'} - - .. function:: aria2.getSessionInfo() - - - - This method returns session information. The response is of type struct and contains following key. - + ``sessionId`` Session ID, which is generated each time when aria2 is invoked. - + **JSON-RPC Example** :: - + >>> import urllib2, json >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', @@ -3206,44 +3038,27 @@ All code examples come from Python2.7 interpreter. {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': {u'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}} - - + **XML-RPC Example** :: - + >>> import xmlrpclib >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc') >>> s.aria2.getSessionInfo() {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'} - - .. function:: aria2.shutdown() - - - - - This method shutdowns aria2. This method returns ``"OK"``. - + This method shutdowns aria2. This method returns ``OK``. .. function:: aria2.forceShutdown() - - - - This method shutdowns :func:`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"``. - + tracker are skipped. This method returns ``OK``. .. function:: 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 contains two keys: ``methodName`` and ``params``. ``methodName`` is the @@ -3252,13 +3067,13 @@ All code examples come from Python2.7 interpreter. 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 examples, we add 2 downloads. First one is + ``http://example.org/file`` and second one is ``file.torrent``. + **JSON-RPC Example** - - - In the following example, we add 2 downloads. First one is - \http://example.org/file and second one is file.torrent:: - + :: + >>> import urllib2, json, base64 >>> from pprint import pprint >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', @@ -3269,11 +3084,10 @@ All code examples come from Python2.7 interpreter. ... 'params':[base64.b64encode(open('file.torrent').read())]}]]}) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) - {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'1'], [u'2']]} - - + {u'id': u'qwer', u'jsonrpc': u'2.0', u'result': [[u'2089b05ecca3d829'], [u'd2703803b52216d1']]} + JSON-RPC also supports Batch request described in JSON-RPC 2.0 Specification:: - + >>> jsonreq = json.dumps([{'jsonrpc':'2.0', 'id':'qwer', ... 'method':'aria2.addUri', ... 'params':[['http://example.org']]}, @@ -3282,16 +3096,12 @@ All code examples come from Python2.7 interpreter. ... 'params':[base64.b64encode(open('file.torrent').read())]}]) >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) >>> pprint(json.loads(c.read())) - [{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'1'}, - {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'2'}] - - + [{u'id': u'qwer', u'jsonrpc': u'2.0', u'result': u'2089b05ecca3d829'}, + {u'id': u'asdf', u'jsonrpc': u'2.0', u'result': u'd2703803b52216d1'}] + **XML-RPC Example** - - - 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) @@ -3299,9 +3109,8 @@ All code examples come from Python2.7 interpreter. >>> mc.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent').read())) >>> r = mc() >>> tuple(r) - ('2', '3') - - + ('2089b05ecca3d829', 'd2703803b52216d1') + Error Handling ~~~~~~~~~~~~~~ @@ -3402,24 +3211,25 @@ The encoding of GET parameters are follows:: The ``method`` and ``id`` are always treated as JSON string and their encoding must be UTF-8. -For example, The encoded string of aria2.tellStatus('3') with id='foo' -looks like this:: +For example, The encoded string of +``aria2.tellStatus('2089b05ecca3d829')`` with ``id='foo'`` looks like +this:: - /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIzIl0%3D + /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D The ``params`` parameter is Base64-encoded JSON array which usually appears in ``params`` attribute in JSON-RPC request object. In the -above example, the params is ['3'], therefore:: +above example, the params is ``["2089b05ecca3d829"]``, therefore:: - ['3'] --(Base64)--> WyIzIl0= --(Percent Encode)--> WyIzIl0%3D + ["2089b05ecca3d829"] --(Base64)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0= + --(Percent Encode)--> WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D The JSON-RPC interface supports JSONP. You can specify the callback -function in 'jsoncallback' parameter:: - - /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIzIl0%3D&jsoncallback=cb +function in ``jsoncallback`` parameter:: + /jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIyMDg5YjA1ZWNjYTNkODI5Il0%3D&jsoncallback=cb For Batch request, ``method`` and ``id`` parameter must not be specified. Whole request must be specified in ``params`` parameter. For example, @@ -3548,12 +3358,13 @@ Console Readout While downloading files, aria2 prints the console readout to tell the progress of the downloads. The console readout is like this:: - [#1 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s] + [#2089b0 400.0KiB/33.2MiB(1%) CN:1 DL:115.7KiB ETA:4m51s] This section describes what these numbers and strings mean. -``#N`` - N means GID, which is an unique ID for each download. +``#NNNNNN`` + The first 6 characters of GID in hex string. GID is an unique ID for + each download. ``X/Y(Z%)`` Completed length, the total file length and its ratio. If