transmission/doc/ipc-json-spec.txt

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