mirror/transmission
1
0
Fork 0
mirror of https://github.com/transmission/transmission synced 2024-12-24 16:52:39 +00:00
Code Issues Releases Wiki Activity

readability

Browse source
This commit is contained in:
Charles Kerr 2008-05-10 16:11:00 +00:00
parent cd9f885417
commit b33d40c47e
1 changed files with 44 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

91
doc/ipc-json-spec.txt
View file

@ -3,6 +3,8 @@
This document describes a protocol for interacting with Transmission This document describes a protocol for interacting with Transmission
sessions remotely. sessions remotely.
1.1 Terminology
The JSON terminology in RFC 4627 is used. "array" is equivalent The JSON terminology in RFC 4627 is used. "array" is equivalent
to a benc list; "object" is equivalent to a benc dictionary; to a benc list; "object" is equivalent to a benc dictionary;
an object's "strings" are the dictionary's keys, an object's "strings" are the dictionary's keys,
@ -16,59 +18,54 @@
floating-point numbers are represented as strings. floating-point numbers are represented as strings.
booleans are represented as integers where 0 is false and 1 is true. booleans are represented as integers where 0 is false and 1 is true.
There are only two message types, request and response. Both have There are only two message types: request and response. Both
the same format: an object with two members whose strings are are json objects with two members: "headers" (described in 2.1)
"headers" and "body", and whose values are both objects. and "body" (described in 2.2-2.3).
2.1. Headers 2.1. Headers
Message headers support two members: Message headers support two members:
(1) A required "type" string whose value must be "request" or "response". (1) A required "type" string whose value must be "request" or "response".
(2) An optional "tag" integer that may be supplied by request. (2) An optional "tag" integer supplied by requests for their own use.
Responses MUST return an identical tag member. Responses MUST include the request tag's verbatim.
2.2. Request Body 2.2. Request Body
Request bodies support two members: Request bodies support two members:
(1) A required "name" string telling the name of the request. (1) A required "name" string telling the name of the request.
(2) An optional "arguments" object of argument name/value pairs. (2) An optional "arguments" object of name/value argument pairs.
2.3. Response Body 2.3. Response Body
Response bodies support three members: Response bodies support two members:
(1) A required "name" string which matches the request's name. (1) An optional "arguments" object of argument name/value pairs.
(2) An optional "error" string which may be omitted on success. (2) An optional "error" string which may be omitted on success.
(3) An optional "arguments" object of argument name/value pairs.
3. Torrent Requests 3. Torrent Requests
3.1. Common Arguments 3.1. Common Arguments
Most torrent requests support an "ids" argument, which is a list Most torrent requests support an "ids" argument, which is a list
containing unique torrent information ids, or torrent sha1 hash strings, containing unique torrent ids, or torrent sha1 hash strings, or both.
or both. These are the torrents that the request will be applied to. These are the torrents that the request will be applied to.
If the ids are omitted, the request is applied to all torrents. If "ids" is omitted, the request is applied to all torrents.
3.2. Torrent Action Requests 3.2. Torrent Action Requests
Request names: "torrent-start", "torrent-stop", "torrent-remove", Request names: "torrent-start", "torrent-stop",
"torrent-verify". "torrent-remove", "torrent-verify"
The only supported argument is 3.1's "ids" argument. The only supported argument is 3.1's "ids" argument.
The response has no arguments. The response has no arguments.
3.3. Torrent Info Requests 3.3. Torrent Info Requests
Request name is "torrent-info". Request name: "torrent-info".
The only supported argument is 3.1's "ids" argument. The only supported argument is 3.1's "ids" argument.
The response's arguments object contains a member whose string The response will contain an "info" argument holding an array of
is "info" and whose value is an array of tr_info objects. tr_info objects. these are a (nearly) 1-to-1 mapping of
tr_info objects are (nearly) 1-to-1 mappings of libtransmission's libtransmission's tr_info struct, but differ in the following ways:
tr_info struct, where the members' string in the tr_info field name,
and the members' value is the field's value.
The tr_info object differs from libtransmission's tr_info struct
in the following ways:
(1) tr_info's "hash" field is omitted. (1) tr_info's "hash" field is omitted.
(2) tr_info's "pieces" field is omitted. (2) tr_info's "pieces" field is omitted.
(3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted. (3) tr_file's "firstPiece", "lastPiece", and "offset" fields are omitted.
@ -77,7 +74,8 @@
{ {
"headers": { "headers": {
"type": "request" "type": "request",
"tag": 666
}, },
"body": { "body": {
"arguments": { "arguments": {
@ -91,7 +89,8 @@
{ {
"headers": { "headers": {
"type": "response" "type": "response",
"tag": 666
} }
"body": { "body": {
"arguments": { "arguments": {
@ -122,17 +121,13 @@
Request name is "torrent-status". Request name is "torrent-status".
The only supported argument is 3.1's "ids" argument. The only supported argument is 3.1's "ids" argument.
The response's arguments contains a member whose string is "status" The response will contain a "status" argument holding an array of
and whose value is an array of tr_stat objects. tr_stat objects tr_stat objects. these are a (nearly) 1-to-1 mapping of
are (nearly) 1-to-1 mappings of libtransmission's tr_stat struct, libtransmission's tr_stat struct, but differ in the following ways:
where the members' string in the tr_stat field name, and the
members' value is the field's value.
The tr_stat object differs from libtransmission's tr_stat struct (1) tr_stat's "tracker" field is omitted
in the following ways: (2) a new string, "announce-url", is added
(3) a new string, "scrape-url", is added
(1) tr_stat's "tracker" field is omitted and replaced
with two fields: "announce-url" and "scrape-url"
3.5. Adding a Torrent 3.5. Adding a Torrent
@ -142,11 +137,12 @@
string | value type & description string | value type & description
-------------------+------------------------------------------------- -------------------+-------------------------------------------------
"autostart" | boolean. true means to auto-start torrents. "autostart" | boolean true means to auto-start torrents
"directory" | string. path to download the torrent to. "directory" | string path to download the torrent to
"filename" | string. location of the .torrent file. "filename" | string location of the .torrent file
"speed-limit-up" | int. speed in KiB/s "max-peers" | int maximum number of peers
"speed-limit-down" | int. speed in KiB/s "speed-limit-down" | int maximum download speed (in KiB/s)
"speed-limit-up" | int maximum upload speed (in KiB/s)
4. Session Status Requests 4. Session Status Requests
@ -158,14 +154,15 @@
string | value type & description string | value type & description
-------------------+------------------------------------------------- -------------------+-------------------------------------------------
"autostart" | boolean. true means to auto-start torrents. "autostart" | boolean true means to auto-start torrents
"directory" | string. path to download torrents to. "directory" | string path to download torrents to
"encryption" | string. "required", "preferred", or "plaintext" "encryption" | string "required", "preferred", or "plaintext"
"port" | int. port number "max-peers" | int maximum global number of peers
"port-forwarding" | boolean. true means enabled. "port" | int port number
"pex-allowed" | boolean. true means allow pex for public torrents. "port-forwarding" | boolean true means enabled.
"speed-limit-up" | int. speed in KiB/s "pex-allowed" | boolean true means allow pex for public torrents
"speed-limit-down" | int. speed in KiB/s "speed-limit-down" | int maximum global download speed (in KiB/s)
"speed-limit-up" | int maximum global upload speed (in KiB/s)
4.2. Accessors 4.2. Accessors