mirror of
https://github.com/transmission/transmission
synced 2024-12-26 09:37:56 +00:00
344 lines
15 KiB
Text
344 lines
15 KiB
Text
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 KiB/s)
|
|
"speed-limit-down-enabled" | 'boolean' true if the download speed is limited
|
|
"speed-limit-up" | number maximum upload speed (in KiB/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
|
|
"sort" | no | "id" | string "activity", "age", "id",
|
|
| | | "name", "progress", "ratio",
|
|
| | | "state", or "tracker".
|
|
"ascending" | no | 'true' | 'boolean' true if sorting ascending
|
|
"filter" | no | "all" | string "active", "all", "paused",
|
|
| | | "downloading", or "seeding".
|
|
|
|
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 | 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 KiB/s)
|
|
"speed-limit-down-enabled" | 'boolean' true means enabled
|
|
"speed-limit-up" | number max global upload speed (in KiB/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
|
|
|
|
|