223 lines
7.3 KiB
Plaintext
223 lines
7.3 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;
|
|
an object's "strings" are the dictionary's keys,
|
|
and an object's "members" are its string/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 in benc.
|
|
floating-point numbers are represented as strings.
|
|
booleans are represented as integers where 0 is false and 1 is true.
|
|
|
|
There are only two message types: request and response. Both
|
|
are JSON objects with two members: "headers" (described in 2.1)
|
|
and "body" (described in 2.2 - 2.3).
|
|
|
|
2.1. Headers
|
|
|
|
Message headers support two members:
|
|
(1) A required "type" string whose value must be "request" or "response".
|
|
(2) An optional "tag" integer supplied by requests for their own use.
|
|
Responses MUST include the request tag's verbatim.
|
|
|
|
2.2. Request Body
|
|
|
|
Request bodies support two members:
|
|
(1) A required "name" string telling the name of the request.
|
|
(2) An optional "arguments" object of name/value pairs.
|
|
|
|
2.3. Response Body
|
|
|
|
All response bodies support two members:
|
|
(1) A required "result" string whose value must be "success" on success,
|
|
and may be "no-permission", "bad-format", or "error" on failure.
|
|
(2) An optional "arguments" object of name/value pairs.
|
|
The contents of these arguments depend on the request's name.
|
|
|
|
3. Torrent Requests
|
|
|
|
3.1. Torrent Action Requests
|
|
|
|
Request names: "torrent-start", "torrent-stop",
|
|
"torrent-remove", "torrent-verify"
|
|
Request arguments: "ids", a list of unique torrent ids, 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
|
|
|
|
Request 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:
|
|
|
|
{
|
|
"headers": {
|
|
"type": "request",
|
|
"tag": 666
|
|
},
|
|
"body": {
|
|
"name": "torrent-info",
|
|
"arguments": {
|
|
"ids": [ 7, 10 ]
|
|
}
|
|
}
|
|
}
|
|
|
|
Example Response:
|
|
|
|
{
|
|
"headers": {
|
|
"type": "response",
|
|
"tag": 666
|
|
}
|
|
"body": {
|
|
"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
|
|
|
|
Request name is "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 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
|
|
|
|
Request name: "torrent-add"
|
|
Request arguments:
|
|
|
|
string | value type & description
|
|
-------------------+-------------------------------------------------
|
|
"autostart" | boolean true means to auto-start torrents
|
|
"destination" | string path to download the torrent to
|
|
"filename" | string location of the .torrent file
|
|
"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.1'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-up" | int maximum upload speed (in KiB/s)
|
|
|
|
3.5.1. Mutators
|
|
|
|
Request 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
|
|
|
|
Request 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
|
|
|
|
Request name: "torrent-set-file"
|
|
Request arguments: 3.1's "ids", plus one or more of 3.6's arguments
|
|
Response arguments: none
|
|
|
|
3.6.2. Accessors
|
|
|
|
Request name: "torrent-get-file"
|
|
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
|
|
"port" | int port number
|
|
"port-forwarding-enabled" | boolean true means enabled.
|
|
"pex-allowed" | boolean true means allow pex in public torrents
|
|
"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
|
|
|
|
Request name: "session-set"
|
|
Request arguments: one or more of 4.1's arguments
|
|
Response arguments: none
|
|
|
|
4.2. Accessors
|
|
|
|
Request name: "session-get"
|
|
Request arguments: none
|
|
Response arguments: all of 4.1's arguments
|
|
|