transmission/doc/rpc-spec.txt

259 lines
8.7 KiB
Plaintext

1. Introduction
This document describes a protocol for interacting with Transmission
sessions remotely.
1.1 Terminology
The JSON terminology in RFC 4627 is used. "array" is equivalent
to a benc list; "object" is equivalent to a benc dictionary;
and an object's "keys" are the dictionary's string keys.
2. Message Format
Messages are formatted in a subset of JSON that understands
arrays, maps, strings, and whole numbers with no exponentials --
in short, the subset of JSON easily represented as bencoded data.
Floating-point numbers are represented as strings.
Booleans are represented as integers where 0 is false and 1 is true.
Messages are represented as JSON objects. There are two types:
requests (described in 2.1) and responses (described in 2.2).
2.1. Requests
Requests supports three keys:
(1) A required "method" string telling the name of the method to invoke
(2) An optional "arguments" object of key/value pairs
(3) An optional "tag" integer used by clients to track responses.
If provided by a request, the response MUST include the same tag.
2.2. Responses
Reponses support three keys:
(1) A required "result" string whose value must be "success" on success,
or an error string on failure.
(2) An optional "arguments" object of key/value pairs
(3) An optional "tag" integer as described in 2.1.
2.3. Transport Mechanism
POSTing a JSON-encoded request is the preferred way of communicating
with the Transmission server; however, a simple notation also exists
for sending requests in the query portion of a URL.
The URL notation works as follows:
(1) Any key not "tag" or "method" is assumed to be in "arguments".
(2) The "arguments" key isn't needed, since data isn't nested.
(3) If the entire value in a key/value pair can be parsed as an integer,
it's parsed into a JSON number.
Otherwise, if the value can be parsed as comma-delimited integers,
it's parsed into a JSON array of integers.
Otherwise, the value is treated as a string.
Examples:
?method=torrent-start&ids=1,2
?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
3. Torrent Requests
3.1. Torrent Action Requests
Method name | libtransmission function
--------------------+-------------------------------------------------
"torrent-remove" | tr_torrentRemove
"torrent-start" | tr_torrentStart
"torrent-stop" | tr_torrentStop
"torrent-verify" | tr_torrentVerify
Request arguments: "ids", a list of torrent id integers, sha1 hash strings,
or both. These are the torrents that the request will
be applied to. If "ids" is ommitted, the request is
applied to all torrents.
Response arguments: none
3.2. Torrent List
An overview list of torrents.
Method name: "torrent-list".
Request arguments: none.
Response arguments: "list", an array of objects that contain seven keys:
key | value type
--------------------+-------------------------------------------------
"hashString" | string
"id" | number
"name" | string
"rateDownload" | double
"rateUpload" | double
"ratio" | double
3.3. Torrent Info Requests
Method name: "torrent-info".
Request arguments: 3.1's optional "ids" argument.
Response arguments: "torrent-info", an array of objects based on
libtransmission's tr_info struct but different in the following ways:
(1) the torrent's "id" field is added.
(2) tr_info's "hash" field is omitted.
(3) tr_info's "pieces" field is omitted.
(4) tr_file's only included pieces are "name" and "length".
Note that this is a fairly high-bandwidth request and that its results
don't change. You should try to cache its results instead of re-calling it.
Example Request:
{
"arguments": { "ids": [ 7, 10 ] }
"method": "torrent-info",
"tag": 39693
}
Example Response:
{
"tag": 39693
"result": "success",
"arguments": {
"torrent-info": [
{
"id": 7,
"name": "Ubuntu x86_64 DVD",
"pieceCount": 1209233,
"pieceSize": 4096,
"totalSize": 9803930483,
...
},
{
"id": 10,
"name": "Ubuntu i386 DVD",
"pieceCount": 83943,
"pieceSize": 12345,
"totalSize": 2398480394,
...
}
]
}
}
3.4. Torrent Status Requests
Method name: "torrent-status"
Request arguments: 3.1's optional "ids" argument.
Response arguments: "torrent-status", an array of objects
based on libtransmission's tr_stat struct but different
in the following ways:
(1) tr_info's "hashString" field is added.
3.5. Adding a Torrent
Method name: "torrent-add"
Request arguments:
string | value type & description
-------------------+-------------------------------------------------
"download-dir" | string path to download the torrent to
"filename" | string location of the .torrent file
"metainfo" | string base64-encoded .torrent content
"paused" | boolean if true, don't start the torrent
"peer-limit" | int maximum number of peers
Either "filename" OR "metainfo" must be included.
All other arguments are optional.
Response arguments: on success, a "torrent-added" object in the
form of one of 3.3's tr_info objects.
3.6. Other Torrent Settings
Common arguments:
string | value type & description
---------------------------+-------------------------------------------------
"peer-limit" | int maximum number of peers
"speed-limit-down" | int maximum download speed (in KiB/s)
"speed-limit-down-enabled" | boolean true if the download speed is limited
"speed-limit-up" | int maximum upload speed (in KiB/s)
"speed-limit-up-enabled" | boolean true if the upload speed is limited
3.6.1. Mutators
Method name: "torrent-set"
Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
Response arguments: none
3.6.2. Accessors
Method name: "torrent-get"
Request arguments: none
Response arguments: A "torrents" list of objects containing all
of 3.6's arguments plus the torrent's "id" field.
3.7 File Priorities
Common arguments:
string | value type & description
-------------------+-------------------------------------------------
"files-wanted" | array indices of one or more file to download
"files-unwanted" | array indices of one or more file to not download
"priority-high" | array indices of one or more high-priority files
"priority-low" | array indices of one or more low-priority files
"priority-normal" | array indices of one or more normal-priority files
3.7.1. Mutators
Method name: "torrent-set-priorities"
Request arguments: 3.1's "ids", plus one or more of 3.7's arguments
Response arguments: none
3.7.2. Accessors
Method name: "torrent-get-priorities"
Request arguments: none
Response arguments: A "torrents" list of objects containing all
of 3.7's arguments plus the torrent's "id" int.
4. Session Status Requests
4.1. Session Arguments
string | value type & description
---------------------------+-------------------------------------------------
"encryption" | string "required", "preferred", "tolerated"
"download-dir" | string default path to download torrents
"peer-limit" | int maximum global number of peers
"pex-allowed" | boolean true means allow pex in public torrents
"port" | int port number
"port-forwarding-enabled" | boolean true means enabled.
"speed-limit-down" | int max global download speed (in KiB/s)
"speed-limit-down-enabled" | int max global download speed (in KiB/s)
"speed-limit-up" | int max global upload speed (in KiB/s)
"speed-limit-up-enabled" | int max global upload speed (in KiB/s)
4.2. Mutators
Method name: "session-set"
Request arguments: one or more of 4.1's arguments
Response arguments: none
4.2. Accessors
Method name: "session-get"
Request arguments: none
Response arguments: all of 4.1's arguments