diff --git a/doc/aria2c.1.asciidoc b/doc/aria2c.1.asciidoc index 8053b19e4..05a5d6018 100644 --- a/doc/aria2c.1.asciidoc +++ b/doc/aria2c.1.asciidoc @@ -755,8 +755,8 @@ Metalink Specific Options protocol. Default: 'true' -JSON-RPC/XML-RPC Options -~~~~~~~~~~~~~~~~~~~~~~~~ +RPC Options +~~~~~~~~~~~ [[aria2_optref_enable_rpc]]*--enable-rpc*[='true'|'false']:: Enable JSON-RPC/XML-RPC server. It is strongly recommended to set username @@ -1056,8 +1056,8 @@ connections. Save error/unfinished downloads to FILE on exit. You can pass this output file to aria2c with *<>* option on restart. Please note that - downloads added by *<>* and - *<>* + downloads added by *<>* and + *<>* RPC method and whose metadata could not be saved as a file are not saved. [[aria2_optref_stop]]*--stop*=SEC:: @@ -1141,7 +1141,7 @@ download can contain multiple files. If number of files is more than one, file path is first one. In other words, this is the value of path key of first struct whose selected key is true in the response of -*<>* +*<>* RPC method. If you want to get all file paths, consider to use JSON-RPC/XML-RPC. Please note that file path may change during download in HTTP because of @@ -1583,8 +1583,23 @@ host=localhost, protocol=http, dl_speed=32000, last_updated=1222491640, status=O host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR -------------------------------------------------------------------------------- -XML-RPC INTERFACE ------------------ +RPC INTERFACE +------------- + +aria2 provides both JSON-RPC and XML-RPC and they basically have the +same functionality. + +The request path of JSON-RPC interface is '/jsonrpc'. +The request path of XML-RPC interface is '/rpc'. + +The implemented JSON-RPC is based on http://groups.google.com/group/json-rpc/web/json-rpc-2-0[JSON-RPC 2.0 Specification (2010-03-26)] and supports HTTP POST and GET (JSONP). + +The JSON-RPC interface does not support notification. It also +does not support floating point number. The character encoding must be +UTF-8. + +When reading following document for JSON-RPC, interpret struct as JSON +object. Terminology ~~~~~~~~~~~ @@ -1602,7 +1617,7 @@ Methods All code examples come from Python2.7 interpreter. -[[aria2_xmlrpc_aria2_addUri]] +[[aria2_rpc_aria2_addUri]] *aria2.addUri* ('uris[, options[, position]]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1615,15 +1630,30 @@ BitTorrent Magnet URI, 'uris' must have only one element and it should be BitTorrent Magnet URI. URIs in 'uris' must point to the same file. If you mix other URIs which point to another file, aria2 does not complain but download may fail. 'options' is of type struct and its -members are a pair of option name and value. See *<>* below for +members are a pair of option name and value. See *<>* below for more details. If 'position' is given as an integer starting from 0, the new download is inserted at 'position' in the waiting queue. If 'position' is not given or 'position' is larger than the size of the queue, it is appended at the end of the queue. This method returns GID of registered download. -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +The following example adds \http://example.org/file to aria2: + +------------------------------------------------------------------ +>>> 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"}' +------------------------------------------------------------------ + +XML-RPC Example ++++++++++++++++ The following example adds \http://example.org/file to aria2: @@ -1637,7 +1667,8 @@ The following example adds \http://example.org/file to aria2: The following example adds 2 sources and some options: -------------------------------------------------------------------------- ->>> s.aria2.addUri(['http://example.org/file'], dict(dir="/tmp")) +>>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'], + dict(dir="/tmp")) '2' -------------------------------------------------------------------------- @@ -1649,7 +1680,7 @@ waiting downloads: '3' --------------------------------------------------------------- -[[aria2_xmlrpc_aria2_addTorrent]] +[[aria2_rpc_aria2_addTorrent]] *aria2.addTorrent* ('torrent[, uris[, options[, position]]]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1657,7 +1688,7 @@ Description +++++++++++ This method adds BitTorrent download by uploading .torrent file. If -you want to add BitTorrent Magnet URI, use *<>* method +you want to add BitTorrent Magnet URI, use *<>* method instead. '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. For single file @@ -1665,7 +1696,7 @@ 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. 'options' is of type struct and its members are a pair of option name -and value. See *<>* below for more details. If 'position' is +and value. See *<>* below for more details. If 'position' is given as an integer starting from 0, the new download is inserted at 'position' in the waiting queue. If 'position' is not given or 'position' is larger than the size of the queue, it is appended at the @@ -1679,8 +1710,23 @@ If the file cannot be saved successfully, the downloads added by this method are not saved by *<>*. -Example -+++++++ +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"}' +--------------------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ The following example adds local file file.torrent to aria2: @@ -1691,7 +1737,7 @@ The following example adds local file file.torrent to aria2: '6' --------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_addMetalink]] +[[aria2_rpc_aria2_addMetalink]] *aria2.addMetalink* ('metalink[, options[, position]]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1701,7 +1747,7 @@ Description 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 *<>* below for more details. If +option name and value. See *<>* below for more details. If 'position' is given as an integer starting from 0, the new download is inserted at 'position' in the waiting queue. If 'position' is not given or 'position' is larger than the size of the queue, it is @@ -1716,8 +1762,23 @@ If the file cannot be saved successfully, the downloads added by this method are not saved by *<>*. -Example -+++++++ +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]}) +>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) +>>> c.read() +'{"id":"qwer","jsonrpc":"2.0","result":["8"]}' +----------------------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ The following example adds local file file.meta4 to aria2: @@ -1728,7 +1789,7 @@ The following example adds local file file.meta4 to aria2: ['8'] -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_remove]] +[[aria2_rpc_aria2_remove]] *aria2.remove* ('gid') ^^^^^^^^^^^^^^^^^^^^^^ @@ -1740,8 +1801,22 @@ 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. -Example -+++++++ +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']}) +>>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq) +>>> c.read() +'{"id":"qwer","jsonrpc":"2.0","result":"3"}' +----------------------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ The following example removes download whose GID is "3": @@ -1752,7 +1827,7 @@ The following example removes download whose GID is "3": '3' -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_forceRemove]] +[[aria2_rpc_aria2_forceRemove]] *aria2.forceRemove* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1760,11 +1835,11 @@ Description +++++++++++ This method removes the download denoted by 'gid'. This method -behaves just like *<>* except that this method removes +behaves just like *<>* except that this method removes download without any action which takes time such as contacting BitTorrent tracker. -[[aria2_xmlrpc_aria2_pause]] +[[aria2_rpc_aria2_pause]] *aria2.pause* ('gid') ^^^^^^^^^^^^^^^^^^^^^ @@ -1775,20 +1850,20 @@ This method pauses the download denoted by 'gid'. 'gid' is of type string. The status of paused download becomes "paused". If the download is active, the download is placed on the first position of waiting queue. As long as the status is "paused", the download is not -started. To change status to "waiting", use *<>* method. +started. To change status to "waiting", use *<>* method. This method returns GID of paused download. -[[aria2_xmlrpc_aria2_pauseAll]] +[[aria2_rpc_aria2_pauseAll]] *aria2.pauseAll* () ^^^^^^^^^^^^^^^^^^^ Description +++++++++++ -This method is equal to calling *<>* for every active/waiting +This method is equal to calling *<>* for every active/waiting download. This methods returns "OK" for success. -[[aria2_xmlrpc_aria2_forcePause]] +[[aria2_rpc_aria2_forcePause]] *aria2.forcePause* ('pid') ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1796,21 +1871,21 @@ Description +++++++++++ This method pauses the download denoted by 'gid'. This method -behaves just like *<>* except that this method pauses +behaves just like *<>* except that this method pauses download without any action which takes time such as contacting BitTorrent tracker. -[[aria2_xmlrpc_aria2_forcePauseAll]] +[[aria2_rpc_aria2_forcePauseAll]] *aria2.forcePauseAll* () ^^^^^^^^^^^^^^^^^^^^^^^^ Description +++++++++++ -This method is equal to calling *<>* for every +This method is equal to calling *<>* for every active/waiting download. This methods returns "OK" for success. -[[aria2_xmlrpc_aria2_unpause]] +[[aria2_rpc_aria2_unpause]] *aria2.unpause* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^ @@ -1822,17 +1897,17 @@ This method changes the status of the download denoted by 'gid' from 'gid' is of type string. This method returns GID of unpaused download. -[[aria2_xmlrpc_aria2_unpauseAll]] +[[aria2_rpc_aria2_unpauseAll]] *aria2.unpauseAll* () ^^^^^^^^^^^^^^^^^^^^^ Description +++++++++++ -This method is equal to calling *<>* for every active/waiting +This method is equal to calling *<>* for every active/waiting download. This methods returns "OK" for success. -[[aria2_xmlrpc_aria2_tellStatus]] +[[aria2_rpc_aria2_tellStatus]] *aria2.tellStatus* ('gid[, keys]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1844,7 +1919,7 @@ This method returns download progress of the download denoted by 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, *<>*("1", ["gid", "status"]) +transfers. For example, *<>*("1", ["gid", "status"]) returns 'gid' and 'status' key. The response is of type struct and it contains following keys. The value type is string. @@ -1940,7 +2015,7 @@ dir:: files:: Returns the list of files. The element of list is the same struct - used in *<>* method. + used in *<>* method. bittorrent:: @@ -1976,8 +2051,61 @@ bittorrent:: name in info dictionary. name.utf-8 is used if available. -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +The following example gets information about download whose GID is +"1": + +--------------------------------------------------------------------------- +>>> import urllib2, json +>>> from pprint import pprint +>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', +... 'method':'aria2.tellStatus', 'params':['1']}) +>>> 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'bitfield': u'0000000000', + u'completedLength': u'901120', + u'connections': u'1', + u'dir': u'/downloads', + u'downloadSpeed': u'15158', + u'files': [{u'index': u'1', + u'length': u'34896138', + u'path': u'/downloads/file', + u'selected': u'true', + u'uris': [{u'status': u'used', + u'uri': u'http://example.org/file'}]}], + u'gid': u'1', + 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']]}) +>>> 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'totalLength': u'34896138'}} +-------------------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ The following example gets information about download whose GID is "1": @@ -2018,7 +2146,7 @@ interested in: {'completedLength': '34896138', 'gid': '1', 'totalLength': '34896138'} -------------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getUris]] +[[aria2_rpc_aria2_getUris]] *aria2.getUris* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^ @@ -2038,8 +2166,24 @@ status:: 'used' if the URI is already used. 'waiting' if the URI is waiting in the queue. -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +-------------------------------------------------------------------- +>>> import urllib2, json +>>> from pprint import pprint +>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', +... 'method':'aria2.getUris', 'params':['1']}) +>>> 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 @@ -2050,7 +2194,7 @@ Example [{'status': 'used', 'uri': 'http://example.org/file'}] -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getFiles]] +[[aria2_rpc_aria2_getFiles]] *aria2.getFiles* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2083,10 +2227,30 @@ selected:: uris:: Returns the list of URI for this file. The element of list is the - same struct used in *<>* method. + same struct used in *<>* method. -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +--------------------------------------------------------------------- +>>> import urllib2, json +>>> from pprint import pprint +>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', +... 'method':'aria2.getFiles', 'params':['1']}) +>>> 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'index': u'1', + u'length': u'34896138', + u'path': u'/downloads/file', + u'selected': u'true', + u'uris': [{u'status': u'used', + u'uri': u'http://example.org/file'}]}]} +--------------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ -------------------------------------------------------------------------- >>> import xmlrpclib @@ -2102,7 +2266,7 @@ Example 'uri': 'http://example.org/file'}]}] -------------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getPeers]] +[[aria2_rpc_aria2_getPeers]] *aria2.getPeers* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2153,8 +2317,40 @@ seeder:: "true" is this client is a seeder. Otherwise "false". -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +----------------------------------------------------------------------- +>>> import urllib2, json +>>> from pprint import pprint +>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', +... 'method':'aria2.getPeers', 'params':['1']}) +>>> 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'amChoking': u'true', + u'bitfield': u'ffffffffffffffffffffffffffffffffffffffff', + u'downloadSpeed': u'10602', + u'ip': u'10.0.0.9', + u'peerChoking': u'false', + u'peerId': u'aria2%2F1%2E10%2E5%2D%87%2A%EDz%2F%F7%E6', + u'port': u'6881', + u'seeder': u'true', + u'uploadSpeed': u'0'}, + {u'amChoking': u'false', + u'bitfield': u'ffffeff0fffffffbfffffff9fffffcfff7f4ffff', + u'downloadSpeed': u'8654', + u'ip': u'10.0.0.30', + u'peerChoking': u'false', + u'peerId': u'bittorrent client758', + u'port': u'37842', + u'seeder': u'false', + u'uploadSpeed': u'6890'}]} +----------------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ -------------------------------------------------------------------------- >>> import xmlrpclib @@ -2182,7 +2378,7 @@ Example 'uploadSpeed': '6890'}] -------------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getServers]] +[[aria2_rpc_aria2_getServers]] *aria2.getServers* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2215,8 +2411,26 @@ servers:: Download speed (byte/sec) -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +----------------------------------------------------------------------- +>>> import urllib2, json +>>> from pprint import pprint +>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', +... 'method':'aria2.getServers', 'params':['1']}) +>>> 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'index': u'1', + 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 @@ -2230,7 +2444,7 @@ Example 'uri': 'http://example.org/file'}]}] -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_tellActive]] +[[aria2_rpc_aria2_tellActive]] *aria2.tellActive* ('[keys]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2239,10 +2453,10 @@ Description This method returns the list of active downloads. The response is of type array and its element is the same struct returned by -*<>* method. For 'keys' parameter, please refer to -*<>* method. +*<>* method. For 'keys' parameter, please refer to +*<>* method. -[[aria2_xmlrpc_aria2_tellWaiting]] +[[aria2_rpc_aria2_tellWaiting]] *aria2.tellWaiting* ('offset, num, [keys]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2253,7 +2467,7 @@ 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 *<>* method. +parameter, please refer to *<>* method. If offset is a positive integer, this method returns downloads in the range of ['offset', 'offset'+'num'). @@ -2269,9 +2483,9 @@ in this order. aria2.tellWaiting(0, 1) returns aria2.tellWaiting(-1, 2) returns ["C", "B"]. The response is of type array and its element is the same struct -returned by *<>* method. +returned by *<>* method. -[[aria2_xmlrpc_aria2_tellStopped]] +[[aria2_rpc_aria2_tellStopped]] *aria2.tellStopped* ('offset, num, [keys]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2281,15 +2495,15 @@ Description 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 *<>* method. +For 'keys' parameter, please refer to *<>* method. -'offset' and 'num' have the same semantics as *<>* +'offset' and 'num' have the same semantics as *<>* method. The response is of type array and its element is the same struct -returned by *<>* method. +returned by *<>* method. -[[aria2_xmlrpc_aria2_changePosition]] +[[aria2_rpc_aria2_changePosition]] *aria2.changePosition* ('gid, pos, how') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2312,8 +2526,25 @@ 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 -+++++++ +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']}) +>>> 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: @@ -2325,7 +2556,7 @@ front of the waiting queue: 0 -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_changeUri]] +[[aria2_rpc_aria2_changeUri]] *aria2.changeUri* ('gid, fileIndex, delUris, addUris[, position]') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2350,8 +2581,25 @@ 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 -+++++++ +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']]}) +>>> 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": @@ -2363,7 +2611,7 @@ whose index is "1" and belongs to the download whose GID is "2": [0, 1] -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getOption]] +[[aria2_rpc_aria2_getOption]] *aria2.getOption* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2374,8 +2622,29 @@ 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 -+++++++ +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']}) +>>> 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'allow-overwrite': u'false', + u'allow-piece-length-change': u'false', + 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": @@ -2392,7 +2661,7 @@ The following example gets options of the download whose GID is "1": .... -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_changeOption]] +[[aria2_rpc_aria2_changeOption]] *aria2.changeOption* ('gid, options') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2405,8 +2674,26 @@ and the available options are: *<>*, *<>*, *<>* and *<>*. This method returns "OK" for success. -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +The following example sets +*<>* 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'}]}) +>>> 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 to "20K" for @@ -2419,7 +2706,7 @@ the download whose GID is "1". 'OK' -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getGlobalOption]] +[[aria2_rpc_aria2_getGlobalOption]] *aria2.getGlobalOption* () ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2430,9 +2717,9 @@ This method returns global options. The response is of type struct. Its key is the name of option. The value type is string. Because global options are used as a template for the options of newly added download, the response contains keys returned by -*<>* method. +*<>* method. -[[aria2_xmlrpc_aria2_changeGlobalOption]] +[[aria2_rpc_aria2_changeGlobalOption]] *aria2.changeGlobalOption* ('options') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2447,7 +2734,7 @@ change log file. To stop logging, give empty string("") as a parameter value. Note that log file is always opened in append mode. This method returns "OK" for success. -[[aria2_xmlrpc_aria2_purgeDownloadResult]] +[[aria2_rpc_aria2_purgeDownloadResult]] *aria2.purgeDownloadResult* () ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2457,7 +2744,7 @@ Description This method purges completed/error/removed downloads to free memory. This method returns "OK". -[[aria2_xmlrpc_aria2_removeDownloadResult]] +[[aria2_rpc_aria2_removeDownloadResult]] *aria2.removeDownloadResult* ('gid') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2467,8 +2754,25 @@ Description This method removes completed/error/removed download denoted by 'gid' from memory. This method returns "OK" for success. -Example -+++++++ +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']}) +>>> 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". @@ -2480,7 +2784,7 @@ whose GID is "1". 'OK' -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getVersion]] +[[aria2_rpc_aria2_getVersion]] *aria2.getVersion* () ^^^^^^^^^^^^^^^^^^^^^ @@ -2498,8 +2802,31 @@ enabledFeatures:: List of enabled features. Each feature name is of type string. -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +------------------------------------------------------------------ +>>> import urllib2, json +>>> from pprint import pprint +>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', +... 'method':'aria2.getVersion'}) +>>> 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'enabledFeatures': [u'Async DNS', + u'BitTorrent', + u'Firefox3 Cookie', + u'GZip', + u'HTTPS', + u'Message Digest', + u'Metalink', + u'XML-RPC'], + u'version': u'1.11.0'}} +------------------------------------------------------------------ + +XML-RPC Example ++++++++++++++++ -------------------------------------------------------------------- >>> import xmlrpclib @@ -2515,10 +2842,10 @@ Example 'Message Digest', 'Metalink', 'XML-RPC'], - 'version': '1.10.5'} + 'version': '1.11.0'} -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_getSessionInfo]] +[[aria2_rpc_aria2_getSessionInfo]] *aria2.getSessionInfo* () ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2532,8 +2859,23 @@ sessionId:: Session ID, which is generated each time when aria2 is invoked. -Example -+++++++ +JSON-RPC Example +++++++++++++++++ + +------------------------------------------------------------------------ +>>> import urllib2, json +>>> from pprint import pprint +>>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer', +... 'method':'aria2.getSessionInfo'}) +>>> 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'sessionId': u'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'}} +------------------------------------------------------------------------ + +XML-RPC Example ++++++++++++++++ -------------------------------------------------------------------- >>> import xmlrpclib @@ -2542,7 +2884,7 @@ Example {'sessionId': 'cd6a3bc6a1de28eb5bfa181e5f6b916d44af31a9'} -------------------------------------------------------------------- -[[aria2_xmlrpc_aria2_shutdown]] +[[aria2_rpc_aria2_shutdown]] *aria2.shutdown* () ^^^^^^^^^^^^^^^^^^^ @@ -2551,18 +2893,18 @@ Description This method shutdowns aria2. This method returns "OK". -[[aria2_xmlrpc_aria2_forceShutdown]] +[[aria2_rpc_aria2_forceShutdown]] *aria2.forceShutdown* () ^^^^^^^^^^^^^^^^^^^^^^^^ Description +++++++++++ -This method shutdowns aria2. This method behaves like *<>* +This method shutdowns aria2. This method behaves like *<>* except that any actions which takes time such as contacting BitTorrent tracker are skipped. This method returns "OK". -[[aria2_xmlrpc_system_multicall]] +[[aria2_rpc_system_multicall]] *system.multicall* ('methods') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2578,8 +2920,43 @@ 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 -+++++++ +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', +... 'method':'system.multicall', +... 'params':[[{'methodName':'aria2.addUri', +... 'params':[['http://example.org']]}, +... {'methodName':'aria2.addTorrent', +... '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']]} +--------------------------------------------------------------------------------------------------- + +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']]}, +... {'jsonrpc':'2.0', 'id':'asdf', +... 'method':'aria2.addTorrent', +... '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'}] +---------------------------------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ In the following example, we add 2 downloads. First one is \http://example.org/file and second one is file.torrent: @@ -2598,10 +2975,13 @@ In the following example, we add 2 downloads. First one is Error Handling ~~~~~~~~~~~~~~ -In case of error, aria2 returns faultCode=1 and the error message in +In JSON-RPC, aria2 returns JSON object which contains error code in +code and the error message in message. + +In XML-RPC, aria2 returns faultCode=1 and the error message in faultString. -[[aria2_xmlrpc_options]] +[[aria2_rpc_options]] Options ~~~~~~~ @@ -2611,6 +2991,16 @@ File>>* subsection for complete list of options. In the option struct, name element is option name(without preceding "--") and value element is argument as string. +JSON-RPC Example +++++++++++++++++ + +---------------------------------------------- +{'split':'1', 'http-proxy':'http://proxy/'} +---------------------------------------------- + +XML-RPC Example ++++++++++++++++ + ------------------------------------------------- @@ -2631,6 +3021,16 @@ 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. +JSON-RPC Example +++++++++++++++++ + +------------------------------------------------------------- +{'header':['Accept-Language: ja', 'Accept-Charset: utf-8']} +------------------------------------------------------------- + +XML-RPC Example ++++++++++++++++ + --------------------------------------------------------------- @@ -2659,6 +3059,57 @@ header option has 2 values, so it uses a list: '1' -------------------------------------------------------------------------- +JSON-RPC using HTTP GET +~~~~~~~~~~~~~~~~~~~~~~~ + +The JSON-RPC interface also supports request via HTTP GET. +The encoding scheme in GET parameters is based on http://groups.google.com/group/json-rpc/web/json-rpc-over-http[JSON-RPC over HTTP Specification (2008-1-15(RC1))]. +The encoding of GET parameters are follows: + +-------------------------------------------------------------- +/jsonrpc?method=METHOD_NAME&id=ID¶ms=BASE64_ENCODED_PARAMS +-------------------------------------------------------------- + +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: + +--------------------------------------------------------- +/jsonrpc?method=aria2.tellStatus&id=foo¶ms=WyIzIl0%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: + +------------------------------------------------------------- +['3'] --(Base64)--> WyIzIl0= --(Percent Encode)--> WyIzIl0%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 +------------------------------------------------------------------------- + +For Batch request, 'method' and 'id' parameter must not be specified. +Whole request must be specified in 'params' parameter. For example, +Batch request + +------------------------------------------------------------- +[{'jsonrpc':'2.0', 'id':'qwer', 'method':'aria2.getVersion'}, + {'jsonrpc':'2.0', 'id':'asdf', 'method':'aria2.tellActive'}] +------------------------------------------------------------- + +will be encoded like this: + +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +/jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Sample XML-RPC Client Code ~~~~~~~~~~~~~~~~~~~~~~~~~~