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

Documented JSON-RPC over WebSocket

pull/13/head
Tatsuhiro Tsujikawa 2012-03-21 01:36:29 +09:00
parent 0792540bf2
commit 3e885c57f6
1 changed files with 90 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
doc/aria2c.1.asciidoc
View File

@ -1716,17 +1716,25 @@ host=localhost, protocol=ftp, dl_speed=0, last_updated=1222491632, status=ERROR
RPC INTERFACE RPC INTERFACE
------------- -------------
aria2 provides both JSON-RPC and XML-RPC and they basically have the aria2 provides JSON-RPC over HTTP and XML-RPC over HTTP and they
same functionality. basically have the same functionality. aria2 also provides JSON-RPC
over WebSocket. JSON-RPC over WebSocket uses same method signatures
and response format with JSON-RPC over HTTP, but it additionally has
server-initiated notifications. See *<<_json_rpc_over_websocket,
JSON-RPC over WebSocket>>* section for details.
The request path of JSON-RPC interface is '/jsonrpc'. The request path of JSON-RPC interface (for both over HTTP and over
The request path of XML-RPC interface is '/rpc'. WebSocket) 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 implemented JSON-RPC is based on
http://jsonrpc.org/specification[JSON-RPC 2.0 Specification] and
supports HTTP POST and GET (JSONP). Using WebSocket as a transport is
the original extension of aria2.
The JSON-RPC interface does not support notification. It also The JSON-RPC interface does not support notification in HTTP, but the
does not support floating point number. The character encoding must be RPC server will send the notification in WebSocket. It also does not
UTF-8. support floating point number. The character encoding must be UTF-8.
When reading following document for JSON-RPC, interpret struct as JSON When reading following document for JSON-RPC, interpret struct as JSON
object. object.
@ -3355,6 +3363,80 @@ will be encoded like this:
/jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D /jsonrpc?params=W3sianNvbnJwYyI6ICIyLjAiLCAiaWQiOiAicXdlciIsICJtZXRob2QiOiAiYXJpYTIuZ2V0VmVyc2lvbiJ9LCB7Impzb25ycGMiOiAiMi4wIiwgImlkIjogImFzZGYiLCAibWV0aG9kIjogImFyaWEyLnRlbGxBY3RpdmUifV0%3D
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
JSON-RPC over WebSocket
~~~~~~~~~~~~~~~~~~~~~~~
JSON-RPC over WebSocket uses same method signatures and response
format with JSON-RPC over HTTP. The supported WebSocket version is 13
which is detailed in http://tools.ietf.org/html/rfc6455[RFC 6455].
To send a RPC request to the RPC server, send serialized JSON string
in Text frame. The response from the RPC server is delivered also in
Text frame.
The RPC server will send the notification to the client. The
notification is unidirectional, therefore the client which received
the notification must not respond to it. The method signature of
notification is much like a normal method request but lacks id
key. The value associated by the params key is the data which this
notification carries. The format of this value varies depending on the
notification method. Following notification methods are defined.
[[aria2_rpc_aria2_onDownloadStart]]
*aria2.onDownloadStart* ('event')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This notification will be sent if a download is started.
The 'event' is of type struct and it contains following keys.
The value type is string.
gid::
GID of the download.
[[aria2_rpc_aria2_onDownloadPause]]
*aria2.onDownloadPause* ('event')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This notification will be sent if a download is paused. The 'event'
is the same struct of the 'event' argument of
*<<aria2_rpc_aria2_onDownloadStart, aria2.onDownloadStart>>* method.
[[aria2_rpc_aria2_onDownloadStop]]
*aria2.onDownloadStop* ('event')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This notification will be sent if a download is stopped by the user.
The 'event' is the same struct of the 'event' argument of
*<<aria2_rpc_aria2_onDownloadStart, aria2.onDownloadStart>>* method.
[[aria2_rpc_aria2_onDownloadComplete]]
*aria2.onDownloadComplete* ('event')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This notification will be sent if a download is completed. In
BitTorrent downloads, this notification is sent when the download is
completed and seeding is over. The 'event' is the same struct of the
'event' argument of *<<aria2_rpc_aria2_onDownloadStart,
aria2.onDownloadStart>>* method.
[[aria2_rpc_aria2_onDownloadError]]
*aria2.onDownloadError* ('event')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This notification will be sent if a download is stopped due to error.
The 'event' is the same struct of the 'event' argument of
*<<aria2_rpc_aria2_onDownloadStart, aria2.onDownloadStart>>* method.
[[aria2_rpc_aria2_onBtDownloadComplete]]
*aria2.onBtDownloadComplete* ('event')
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This notification will be sent if a download is completed in
BitTorrent (but seeding may not be over). The 'event' is the same struct
of the 'event' argument of *<<aria2_rpc_aria2_onDownloadStart,
aria2.onDownloadStart>>* method.
Sample XML-RPC Client Code Sample XML-RPC Client Code
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~