mirror of
https://github.com/transmission/transmission
synced 2024-12-25 09:13:06 +00:00
213 lines
7 KiB
Text
213 lines
7 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;
|
|
an object's "keys" are the dictionary's string keys,
|
|
and an object's "members" are its key/value pairs.
|
|
|
|
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 name/value pairs
|
|
(3) An optional "tag" integer used for 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 name/value pairs
|
|
(3) An optional "tag" integer as described in 2.1.
|
|
|
|
3. Torrent Requests
|
|
|
|
3.1. Torrent Action Requests
|
|
|
|
Method names: "torrent-start", "torrent-stop",
|
|
"torrent-remove", "torrent-verify"
|
|
|
|
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 Info Requests
|
|
|
|
Method name: "torrent-info".
|
|
|
|
Request arguments: 3.1's optional "ids" argument.
|
|
|
|
Response arguments: "info", an array of objects based on libtransmission's
|
|
tr_info struct but differ in the following ways:
|
|
|
|
(1) tr_info's "hash" field is omitted.
|
|
(2) tr_info's "pieces" field is omitted.
|
|
(3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
|
|
|
|
Example Request:
|
|
|
|
{
|
|
"arguments": { "ids": [ 7, 10 ] }
|
|
"method": "torrent-info",
|
|
"tag": 39693
|
|
}
|
|
|
|
Example Response:
|
|
|
|
{
|
|
"tag": 39693
|
|
"result": "success",
|
|
"arguments": {
|
|
"info": [
|
|
{
|
|
"id": 7,
|
|
"totalSize": 9803930483,
|
|
"pieceCount": 1209233,
|
|
"pieceSize": 4096,
|
|
"name": "Ubuntu x86_64 DVD",
|
|
...
|
|
},
|
|
{
|
|
"id": 10,
|
|
"totalSize": 2398480394,
|
|
"pieceCount": 83943,
|
|
"pieceSize": 12345,
|
|
"name": "Ubuntu i386 DVD",
|
|
...
|
|
}
|
|
]
|
|
}
|
|
}
|
|
|
|
3.3. Torrent Status Requests
|
|
|
|
Method name: "torrent-status"
|
|
|
|
Request arguments: 3.1's optional "ids" argument.
|
|
|
|
Response arguments: "status", an array of objects based on
|
|
libtransmission's tr_stat struct but which differ in the following ways:
|
|
|
|
(1) tr_stat's "tracker" field is omitted.
|
|
(2) a new string, "announce-url", is added.
|
|
(3) a new string, "scrape-url", is added.
|
|
|
|
3.4. Adding a Torrent
|
|
|
|
Method name: "torrent-add"
|
|
|
|
Request arguments:
|
|
|
|
string | value type & description
|
|
-------------------+-------------------------------------------------
|
|
"destination" | string path to download the torrent to
|
|
"filename" | string location of the .torrent file
|
|
"paused" | boolean if true, don't start the torrent
|
|
"peer-limit" | int maximum number of peers
|
|
|
|
The "filename" argument is required; all others are optional.
|
|
|
|
Response arguments: on success, a "torrent-added" object in the
|
|
form of one of 3.2's tr_info objects.
|
|
|
|
3.5. 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.5.1. Mutators
|
|
|
|
Method name: "torrent-set"
|
|
Request arguments: 3.1's "ids", plus one or more of 3.5's arguments
|
|
Response arguments: none
|
|
|
|
3.5.2. Accessors
|
|
|
|
Method name: "torrent-get"
|
|
Request arguments: none
|
|
Response arguments: A "torrents" list of objects containing all
|
|
of 3.5's arguments plus the torrent's "id" int.
|
|
|
|
|
|
3.6 File Priorities
|
|
|
|
Common arguments:
|
|
|
|
string | value type & description
|
|
-------------------+-------------------------------------------------
|
|
"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
|
|
"download" | array indices of one or more file to download
|
|
"no-download" | array indices of one or more file to not download
|
|
|
|
3.6.1. Mutators
|
|
|
|
Method name: "torrent-set-priorities"
|
|
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-priorities"
|
|
Request arguments: none
|
|
Response arguments: A "torrents" list of objects containing all
|
|
of 3.6'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"
|
|
"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
|
|
|