transmission/doc/rpc-spec.txt

339 lines
15 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 easily represented
as bencoded data -- arrays, objects, strings, and whole numbers.
Booleans are represented as numbers where 0 is false and 1 is true.
Floating-point numbers are represented as strings.
Messages are formatted as objects. There are two types:
requests (described in 2.1) and responses (described in 2.2).
2.1. Requests
Requests support 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" number 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" number as described in 2.1.
2.3. Transport Mechanism
HTTP POSTing a JSON-encoded request is the preferred way of communicating
with a Transmission RPC 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 treated as an argument.
(2) The "arguments" key isn't needed, since data isn't nested.
(3) If the value in a key/value pair can be parsed as a number, then it is.
Otherwise if it can be parsed as an array of numbers, then it is.
Otherwise, it's parsed 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 numbers, 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 Mutator
Method name: "torrent-set"
Request arguments:
string | value type & description
---------------------------+-------------------------------------------------
"files-wanted" | array indices of file(s) to download
"files-unwanted" | array indices of file(s) to not download
"ids" | array torrent list, as described in 3.1
"peer-limit" | number maximum number of peers
"priority-high" | array indices of high-priority file(s)
"priority-low" | array indices of low-priority file(s)
"priority-normal" | array indices of normal-priority file(s)
"speed-limit-down" | number maximum download speed (in K/s)
"speed-limit-down-enabled" | 'boolean' true if the download speed is limited
"speed-limit-up" | number maximum upload speed (in K/s)
"speed-limit-up-enabled" | 'boolean' true if the upload speed is limited
Response arguments: none
3.3. Torrent Accessors
Method name: "torrent-get".
Request arguments:
string | required? | default | value type & description
-------------+-----------+---------+---------------------------------------
"ids" | no | all | array described in 3.1
"fields" | yes | n/a | number bitwise-or'ed field
| | | values from the table below
Response arguments:
(1) A "fields" number identical to the request's
(2) A "torrents" array of objects, each of which contains the
key/value fields that match the "fields" argument.
See the table below for a complete list.
"fields" value | response | response | source
| value | key |
-------------------+----------+------------------------+-------------
activity, 1 | number | desiredAvailable | tr_stat
| number | eta | tr_stat
| number | peersConnected | tr_stat
| number | peersGettingFromUs | tr_stat
| number | peersSendingToUs | tr_stat
| number | rateDownload | tr_stat
| number | rateUpload | tr_stat
| number | recheckProgress | tr_stat
| number | status | tr_stat
| number | swarmSpeed (K/s) | tr_stat
| 'double' | uploadRatio | tr_stat
| number | webseedsSendingToUs | tr_stat
-------------------+----------+------------------------+-------------
announce, 2 | string | announceResponse | tr_stat
| string | announceURL | tr_stat
| number | lastAnnounceTime | tr_stat
| number | manualAnnounceTime | tr_stat
| number | nextAnnounceTime | tr_stat
-------------------+----------+------------------------+-------------
error, 4 | number | error | tr_stat
| number | errorString | tr_stat
-------------------+----------+------------------------+-------------
files, 8 | array | files
+----------+--------------------------------------
| files is an array of objects that contain:
+----------+------------------------+-------------
| number | length | tr_info
| string | name | tr_info
-------------------+----------+------------------------+-------------
history, 16 | number | activityDate | tr_stat
| number | addedDate | tr_stat
| number | corruptEver | tr_stat
| number | doneDate | tr_stat
| number | downloadedEver | tr_stat
| number | startDate | tr_stat
| number | uploadedEver | tr_stat
-------------------+----------+------------------------+-------------
id, 32 | number | uniqueId | tr_torrent
| string | hashString | tr_info
| string | name | tr_info
-------------------+----------+------------------------+-------------
info, 64 | string | comment | tr_info
| string | creator | tr_info
| number | dateCreated | tr_info
| number | pieceCount | tr_info
| number | pieceSize | tr_info
| 'boolean'| isPrivate | tr_torrent
-------------------+----------+------------------------+-------------
limits, 128 | number | downloadLimit | tr_torrent
| number | downloadLimitMode | tr_torrent
| number | maxConnectedPeers | tr_torrent
| number | uploadLimit | tr_torrent
| number | uploadLimitMode | tr_torrent
-------------------+----------+------------------------+-------------
peers, 256 | number | fromCache | tr_stat
| number | fromIncoming | tr_stat
| number | fromPex | tr_stat
| number | fromTracker | tr_stat
-------------------+----------+------------------------+-------------
priorities, 512 | array | priorities | tr_info
| array | wanted | tr_info
+----------+--------------------------------------
| priorities is an array of tr_info.fileCount
| numbers. Each is the tr_priority_t mode for
| the corresponding file.
+-------------------------------------------------
| wanted is an array of tr_info.fileCount
| 'booleans' true if the corresponding file
| is to be downloaded.
-------------------+----------+------------------------+-------------
scrape, 1024 | number | lastScrapeTime | tr_stat
| number | nextScrapeTime | tr_stat
| string | scrapeResponse | tr_stat
| string | scrapeURL | tr_stat
-------------------+----------+------------------------+-------------
size, 2048 | number | haveUnchecked | tr_stat
| number | haveValid | tr_stat
| number | leftUntilDone | tr_stat
| number | sizeWhenDone | tr_stat
| number | totalSize | tr_info
-------------------+----------+------------------------+-------------
tracker stats, | number | leechers | tr_stat
4096 | number | peersKnown | tr_stat
| number | seeders | tr_stat
| number | timesCompleted | tr_stat
-------------------+----------+--------------------------------------
trackers, 8192 | array | trackers
+----------+--------------------------------------
| trackers is an array of objects that contain:
+----------+------------------------+-------------
| string | announce | tr_info
| string | scrape | tr_info
| number | tier | tr_info
-------------------+----------+------------------------+-------------
webseeds, 16384 | array | webseeds
+----------+--------------------------------------
| webseeds is an array of strings:
+----------+------------------------+-------------
| string | webseed URL | tr_info
-------------------+----------+------------------------+-------------
Example:
Say we want to get the name and total size of torrents #7 and #10.
name is in the "id" section (32) and total size is in "size" (2048),
so the "fields" argument will be 32 + 2048 == 2080.
Request:
{
"arguments": {
"fields": 2080,
"ids": [ 7, 10 ],
"sort-method": "name"
}
"method": "torrent-get",
"tag": 39693
}
Response:
{
"arguments": {
"fields": 2080,
"torrents": [
{
"hashString": "sijioejisoefjiosejfioi",
"haveUnchecked", 23023,
"haveValid", 27986795145,
"leftUntilDone", 0,
"name": "Fedora x86_64 DVD",
"sizeWhenDone", 34983493932,
"totalSize", 34983493932,
"uniqueId": 10,
}
{
"hashString": "asdasiofjosejfoasjfiosj",
"haveUnchecked", 0,
"haveValid", 9923890123,
"leftUntilDone", 0,
"name": "Ubuntu x86_64 DVD",
"sizeWhenDone", 9923890123,
"totalSize", 9923890123,
"uniqueId": 7,
},
]
},
"result": "success",
"tag": 39693
}
3.4. Adding a Torrent
Method name: "torrent-add"
Request arguments:
key | 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" | number 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 with the
fields for id, name, and hashString.
4. Session Requests
4.1. Session Arguments
string | value type & description
---------------------------+-------------------------------------------------
"encryption" | string "required", "preferred", "tolerated"
"download-dir" | string default path to download torrents
"peer-limit" | number maximum global number of peers
"pex-allowed" | 'boolean' true means allow pex in public torrents
"port" | number port number
"port-forwarding-enabled" | 'boolean' true means enabled
"speed-limit-down" | number max global download speed (in K/s)
"speed-limit-down-enabled" | 'boolean' true means enabled
"speed-limit-up" | number max global upload speed (in K/s)
"speed-limit-up-enabled" | 'boolean' true means enabled
4.1.1. Mutators
Method name: "session-set"
Request arguments: one or more of 4.1's arguments
Response arguments: none
4.1.2. Accessors
Method name: "session-get"
Request arguments: none
Response arguments: all of 4.1's arguments
4.2. Session Statistics
Method name: "session-stats"
Request arguments: none
Response arguments:
string | value type
---------------------------+-------------------------------------------------
"activeTorrentCount" | number
"downloadSpeed" | number
"pausedTorrentCount" | number
"torrentCount" | number
"uploadSpeed" | number