mirror/transmission
1
0
Fork 0
mirror of https://github.com/transmission/transmission synced 2024-12-23 16:24:02 +00:00
Code Issues Releases Wiki Activity
transmission/doc/rpc-spec.txt

441 lines
22 KiB
Text
Raw Blame History

1. Introduction
This document describes a protocol for interacting with Transmission
sessions remotely.
1.1 Terminology
The JSON terminology in RFC 4627 is used.
In benc terms, a JSON "array" is equivalent to a benc list,
a JSON "object" is equivalent to a benc dictionary,
and a JSON 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
all have one-to-one mappings between JSON and benc.
Booleans and floating-point numbers are also used in the JSON messages.
Those two types aren't native to benc, so they're encoded this way:
Booleans are encoded 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).
All text MUST be UTF-8 encoded.
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. The current Transmission implementation
has the default URL as http://host:9091/transmission/rpc. Clients
may use this as a default, but should allow the URL to be reconfigured,
since the port and path may be changed to allow mapping and/or multiple
daemons to run on a single server.
In addition to POSTing, there's also a simple notation for sending
requests in the query portion of a URL. This is not as robust, but can
be useful for debugging and simple tasks. The 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-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 Mutators
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-down-global-enabled" | 'boolean' true if the download speed is limited by session
"speed-limit-up" | number maximum upload speed (in K/s)
"speed-limit-up-enabled" | 'boolean' true if the upload speed is limited
"speed-limit-up-global-enabled" | 'boolean' true if the upload speed is limited by session
Just as an empty "ids" value is shorthand for "all ids", using an empty array
for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
"priority-normal" is shorthand for saying "all files".
Response arguments: none
3.3. Torrent Accessors
Method name: "torrent-get".
Request arguments:
(1) An opional "ids" array as described in 3.1.
(2) A required "fields" array of keys. (see list below)
Response arguments:
(1) A "torrents" array of objects, each of which contains
the key/value pairs matching the request's "fields" argument.
key | type | source
--------------------------------+-----------------------------+---------
activityDate | number | tr_stat
addedDate | number | tr_stat
announceResponse | string | tr_stat
announceURL | string | tr_stat
comment | string | tr_info
corruptEver | number | tr_stat
creator | string | tr_info
dateCreated | number | tr_info
desiredAvailable | number | tr_stat
doneDate | number | tr_stat
downloadDir | string | tr_torrent
downloadedEver | number | tr_stat
downloaders | number | tr_stat
error | number | tr_stat
errorString | number | tr_stat
eta | number | tr_stat
files | array (see below) | n/a
hashString | string | tr_info
haveUnchecked | number | tr_stat
haveValid | number | tr_stat
id | number | tr_torrent
isPrivate | 'boolean' | tr_torrent
lastAnnounceTime | number | tr_stat
lastScrapeTime | number | tr_stat
leechers | number | tr_stat
leftUntilDone | number | tr_stat
manualAnnounceTime | number | tr_stat
maxConnectedPeers | number | tr_torrent
name | string | tr_info
nextAnnounceTime | number | tr_stat
nextScrapeTime | number | tr_stat
peers | array (see below) | n/a
peersConnected | number | tr_stat
peersFrom | object (see below) | n/a
peersGettingFromUs | number | tr_stat
peersKnown | number | tr_stat
peersSendingToUs | number | tr_stat
pieces | string (see below) | tr_torrent
pieceCount | tnumber | tr_info
pieceSize | tnumber | tr_info
priorities | array (see below) | n/a
rateDownload (B/s) | number | tr_stat
rateUpload (B/s) | number | tr_stat
recheckProgress | 'double' | tr_stat
scrapeResponse | string | tr_stat
scrapeURL | string | tr_stat
seeders | number | tr_stat
sizeWhenDone | number | tr_stat
speed-limit-down | number | tr_torrent
speed-limit-down-enabled | 'boolean' | tr_torrent
speed-limit-down-global-enabled | 'boolean' | tr_torrent
speed-limit-up | number | tr_torrent
speed-limit-up-enabled | 'boolean' | tr_torrent
speed-limit-up-global-enabled | 'boolean' | tr_torrent
startDate | number | tr_stat
status | number | tr_stat
swarmSpeed (K/s) | number | tr_stat
timesCompleted | number | tr_stat
trackers | array (see below) | n/a
totalSize | number | tr_info
uploadedEver | number | tr_stat
uploadLimitMode | number | tr_torrent
uploadLimit | number | tr_torrent
uploadRatio | 'double' | tr_stat
wanted | array (see below) | n/a
webseeds | array (see below) | n/a
webseedsSendingToUs | number | tr_stat
| |
| |
-----------------------+--------+-----------------------------+
files | array of objects, each containing: |
+-------------------------+------------+
| key | type |
| bytesCompleted | number | tr_torrent
| length | number | tr_info
| name | string | tr_info
-----------------------+--------------------------------------+
peers | array of objects, each containing: |
+-------------------------+------------+
| address | string | tr_peer_stat
| clientName | string | tr_peer_stat
| clientIsChoked | 'boolean' | tr_peer_stat
| clientIsInterested | 'boolean' | tr_peer_stat
| isDownloadingFrom | 'boolean' | tr_peer_stat
| isEncrypted | 'boolean' | tr_peer_stat
| isIncoming | 'boolean' | tr_peer_stat
| isUploadingTo | 'boolean' | tr_peer_stat
| peerIsChoked | 'boolean' | tr_peer_stat
| peerIsInterested | 'boolean' | tr_peer_stat
| port | number | tr_peer_stat
| progress | 'double' | tr_peer_stat
| rateToClient (B/s) | number | tr_peer_stat
| rateToPeer (B/s) | number | tr_peer_stat
-----------------------+--------------------------------------+
peersFrom | an object containing: |
+-------------------------+------------+
| fromCache | number | tr_stat
| fromIncoming | number | tr_stat
| fromPex | number | tr_stat
| fromTracker | number | tr_stat
-----------------------+--------------------------------------+
pieces | A bitfield holding pieceCount flags | tr_torrent
| which are set to 'true' if we have |
| the piece matching that position. |
| JSON doesn't allow raw binary data, |
| so this is a base64-encoded string. |
-----------------------+--------------------------------------+
priorities | an array of tr_info.filecount | tr_info
| numbers. each is the tr_priority_t |
| mode for the corresponding file. |
-----------------------+--------------------------------------+
trackers | array of objects, each containing: |
+-------------------------+------------+
| announce | string | tr_info
| scrape | string | tr_info
| tier | number | tr_info
-----------------------+--------------------------------------+
wanted | an array of tr_info.fileCount | tr_info
| 'booleans' true if the corresponding |
| file is to be downloaded. |
-----------------------+--------------------------------------+
webseeds | an array of strings: |
+-------------------------+------------+
| webseed | string | tr_info
+-------------------------+------------+
Example:
Say we want to get the name and total size of torrents #7 and #10.
Request:
{
"arguments": {
"fields": [ "id", "name", "totalSize" ],
"ids": [ 7, 10 ]
},
"method": "torrent-get",
"tag": 39693
}
Response:
{
"arguments": {
"torrents": [
{
"id": 10,
"name": "Fedora x86_64 DVD",
"totalSize", 34983493932,
},
{
"id": 7,
"name": "Ubuntu x86_64 DVD",
"totalSize", 9923890123,
}
]
},
"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 filename or URL 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.
3.5. Removing a Torrent
Method name: "torrent-remove"
Request arguments:
string | value type & description
---------------------------+-------------------------------------------------
"ids" | array torrent list, as described in 3.1
"delete-local-data" | 'boolean' delete local data. (default: false)
Response arguments: none
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
"version" | string long version string "$version ($revision)"
"rpc-version" | number the current RPC API version
"rpc-version-minimum" | number the minimum RPC API version supported
"rpc-version" indicates the RPC interface version supported by the RPC server.
It is incremented when a new version of Transmission changes the RPC interface.
"rpc-version-minimum" indicates the oldest API supported by the RPC server.
It is changes when a new version of Transmission changes the RPC interface
in a way that is not backwards compatible. There are no plans for this
to be common behavior.
4.1.1. Mutators
Method name: "session-set"
Request arguments: one or more of 4.1's arguments, except "version"
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
---------------------------+-------------------------------+
"cumulative-stats" | object, containing: |
+------------------+------------+
| uploadedBytes | number | tr_session_stats
| downloadedBytes | number | tr_session_stats
| filesAdded | number | tr_session_stats
| sessionCount | number | tr_session_stats
| secondsActive | number | tr_session_stats
---------------------------+-------------------------------+
"current-stats" | object, containing: |
+------------------+------------+
| uploadedBytes | number | tr_session_stats
| downloadedBytes | number | tr_session_stats
| filesAdded | number | tr_session_stats
| sessionCount | number | tr_session_stats
| secondsActive | number | tr_session_stats
5.0. Protocol Versions
The following changes have been made to the RPC interface:
RPC | Release | Backwards | |
Vers. | Version | Compat? | Method | Description
------+---------+-----------+----------------+-------------------------------
1 | 1.30 | n/a | n/a | Initial version
------+---------+-----------+----------------+-------------------------------
2 | 1.34 | yes | torrent-get | new arg "peers"
------+---------+-----------+----------------+-------------------------------
3 | 1.41 | yes | torrent-get | added "port" to "peers"
| | yes | torrent-get | new arg "downloaders"
| | yes | session-get | new arg "version"
| | yes | torrent-remove | new method
------+---------+-----------+----------------+-------------------------------
4 | 1.50 | yes | session-get | new arg "rpc-version"
| | yes | session-get | new arg "rpc-version-minimum"
| | yes | session-stats | added "cumulative-stats"
| | yes | session-stats | added "current-stats"
| | yes | torrent-get | new arg "downloadDir"
------+---------+-----------+----------------+-------------------------------
6 | 1.60 | yes | torrent-get | new arg "pieces"
| | yes | torrent-set | new arg "speed-limit-down-global-enabled"
| | yes | torrent-set | new arg "speed-limit-up-global-enabled"
| | yes | torrent-get | new arg "speed-limit-down"
| | yes | torrent-get | new arg "speed-limit-down-enabled"
| | yes | torrent-get | new arg "speed-limit-down-global-enabled"
| | yes | torrent-get | new arg "speed-limit-up"
| | yes | torrent-get | new arg "speed-limit-up-enabled"
| | yes | torrent-get | new arg "speed-limit-up-global-enabled"
| | NO | torrent-get | removed arg "downloadLimit"
| | NO | torrent-get | removed arg "downloadLimitMode"
| | NO | torrent-get | removed arg "uploadLimit"
| | NO | torrent-get | removed arg "uploadLimitMode"
------+---------+-----------+----------------+-------------------------------
Reference in a new issue View git blame Copy permalink