mirror of
https://github.com/transmission/transmission
synced 2024-12-26 09:37:56 +00:00
269 lines
9 KiB
Text
269 lines
9 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 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 these keys:
|
|
|
|
key | value type
|
|
----------------------+-------------------------------------------------
|
|
"downloadedEver" | number
|
|
"eta" | number
|
|
"hashString" | string
|
|
"id" | number
|
|
"name" | string
|
|
"peersConnected" | number
|
|
"peersSendingToUs" | number
|
|
"peersGettingFromUs" | number
|
|
"percentDone" | double
|
|
"rateDownload" | double
|
|
"rateUpload" | double
|
|
"ratio" | double
|
|
"sizeWhenDone" | number
|
|
"status" | number
|
|
"uploadedEver" | number
|
|
|
|
|
|
|
|
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
|
|
|