From eeccc3788f467ae22a555f93850bfbc563d2ce8f Mon Sep 17 00:00:00 2001 From: Charles Kerr Date: Fri, 11 Feb 2022 10:48:21 -0600 Subject: [PATCH] docs: move rpc-spec document from txt to markdown (#2606) --- CMakeLists.txt | 2 +- extras/rpc-spec.md | 952 +++++++++++++++++++++++++++++++++ extras/rpc-spec.txt | 874 ------------------------------ libtransmission/transmission.h | 2 +- 4 files changed, 954 insertions(+), 876 deletions(-) create mode 100644 extras/rpc-spec.md delete mode 100644 extras/rpc-spec.txt diff --git a/CMakeLists.txt b/CMakeLists.txt index 8bb35b060..35ac9f803 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -674,7 +674,7 @@ if(ENABLE_DAEMON OR ENABLE_GTK OR ENABLE_QT) endif() if(INSTALL_DOC) - install(FILES AUTHORS COPYING NEWS.md README.md extras/rpc-spec.txt extras/send-email-when-torrent-done.sh DESTINATION ${CMAKE_INSTALL_DOCDIR}) + install(FILES AUTHORS COPYING NEWS.md README.md extras/rpc-spec.md extras/send-email-when-torrent-done.sh DESTINATION ${CMAKE_INSTALL_DOCDIR}) endif() if(MSVC AND ENABLE_DAEMON AND ENABLE_QT AND ENABLE_UTILS AND WITH_CRYPTO STREQUAL "openssl") diff --git a/extras/rpc-spec.md b/extras/rpc-spec.md new file mode 100644 index 000000000..7ae938a36 --- /dev/null +++ b/extras/rpc-spec.md @@ -0,0 +1,952 @@ +# Transmission RPC Specification + +This document describes a protocol for interacting with Transmission sessions remotely. + +### 1.1 Terminology + +The [JSON](https://www.json.org/) terminology in [RFC 4627](https://datatracker.ietf.org/doc/html/rfc4627) is used. +RPC requests and responses are formatted in JSON. + +### 1.2 Tools + +If `transmission-remote` is called with a `--debug` argument, its RPC traffic to the Transmission server will be dumped to the terinal. This can be useful when you want to compare requests in your application to another for reference. + +If `transmission-qt` is run with an environment variable `TR_RPC_VERBOSE` set, it too will dump the RPC requests and responses to the terminal for inspection. + +Lastly, using devtools in the Transmission web client is always an option. + +## 2. Message Format + +Messages are formatted as objects. There are two types: requests (described in 2.1) and responses (described in 2.2). + +All text **must** be UTF-8 encoded. + +### 2.1. Requests + +Requests support three keys: + +1. A required `method` string telling the name of the method to invoke +2. An optional `arguments` object of key/value pairs. The keys allowed are defined by the `method`. +3. An optional `tag` number used by clients to track responses. If provided by a request, the response MUST include the same tag. + +```json +{ + "arguments": { + "fields": [ + "version" + ] + }, + "method": "session-get", + "tag": 912313 +} +``` + + +### 2.2. Responses + +Responses to a request will include: + +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. Its keys contents are defined by the `method` and `arguments` of the original request. +3. An optional `tag` number as described in 2.1. + +```json +{ + "arguments": { + "version": "2.93 (3c5870d4f5)" + }, + "result": "success", + "tag": 912313 +} +``` + +### 2.3. Transport Mechanism + +HTTP POSTing a JSON-encoded request is the preferred way of communicating +with a Transmission RPC server. The current Transmission implementation +has the default URL as `http://host:9091/transmission/rpc`. Clients +may use this as a default, but should allow the URL to be reconfigured, +since the port and path may be changed to allow mapping and/or multiple +daemons to run on a single server. + +#### 2.3.1. CSRF Protection + +Most Transmission RPC servers require a X-Transmission-Session-Id +header to be sent with requests, to prevent CSRF attacks. + +When your request has the wrong id -- such as when you send your first +request, or when the server expires the CSRF token -- the +Transmission RPC server will return an HTTP 409 error with the +right `X-Transmission-Session-Id` in its own headers. + +So, the correct way to handle a 409 response is to update your +`X-Transmission-Session-Id` and to resend the previous request. + +#### 2.3.2. DNS Rebinding Protection + +Additional check is being made on each RPC request to make sure that the +client sending the request does so using one of the allowed hostnames by +which RPC server is meant to be available. + +If host whitelisting is enabled (which is true by default), Transmission +inspects the `Host:` HTTP header value (with port stripped, if any) and +matches it to one of the whitelisted names. Regardless of host whitelist +content, `localhost` and `localhost.` domain names as well as all the IP +addresses are always implicitly allowed. + +For more information on configuration, see settings.json documentation for +`rpc-host-whitelist-enabled` and `rpc-host-whitelist` keys. + +#### 2.3.3. Authentication + +Enabling authentication is an optional security feature that can be enabled +on Transmission RPC servers. Authentication occurs by method of HTTP Basic +Access Authentication. + +If authentication is enabled, Transmission inspects the `Authorization:` +HTTP header value to validate the credentials of the request. The value +of this HTTP header is expected to be [`Basic `](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization#basic), +where is equal to a base64 encoded string of the +username and password (respectively), separated by a colon. + +## 3. Torrent Requests + +### 3.1. Torrent Action Requests + +| Method name | libtransmission function +|:--|:-- +| `torrent-start` | tr_torrentStart +| `torrent-start-now` | tr_torrentStartNow +| `torrent-stop` | tr_torrentStop +| `torrent-verify` | tr_torrentVerify +| `torrent-reannounce` | tr_torrentManualUpdate ("ask tracker for more peers") + +Request arguments: `ids`, which specifies which torrents to use. +All torrents are used if the `ids` argument is omitted. + +`ids` should be one of the following: +1. an integer referring to a torrent id +2. a list of torrent id numbers, sha1 hash strings, or both +3. a string, `recently-active`, for recently-active torrents + +Response arguments: none + +### 3.2. Torrent Mutator: `torrent-set` + +Method name: `torrent-set` + +Request arguments: + +| Key | Value Type | Value Description +|:--|:--|:-- +| `bandwidthPriority` | number | this torrent's bandwidth tr_priority_t +| `downloadLimit` | number | maximum download speed (KBps) +| `downloadLimited` | boolean | true if `downloadLimit` is honored +| `files-wanted` | array | indices of file(s) to download +| `files-unwanted` | array | indices of file(s) to not download +| `honorsSessionLimits` | boolean | true if session upload limits are honored +| `ids` | array | torrent list, as described in 3.1 +| `labels` | array | array of string labels +| `location` | string | new location of the torrent's content +| `peer-limit` | number | maximum number of peers +| `priority-high` | array | indices of high-priority file(s) +| `priority-low` | array | indices of low-priority file(s) +| `priority-normal` | array | indices of normal-priority file(s) +| `queuePosition` | number | position of this torrent in its queue [0...n) +| `seedIdleLimit` | number | torrent-level number of minutes of seeding inactivity +| `seedIdleMode` | number | which seeding inactivity to use. See tr_idlelimit +| `seedRatioLimit` | double | torrent-level seeding ratio +| `seedRatioMode` | number | which ratio to use. See tr_ratiolimit +| `trackerAdd` | array | strings of announce URLs to add +| `trackerRemove` | array | ids of trackers to remove +| `trackerReplace` | array | pairs of +| `uploadLimit` | number | maximum upload speed (KBps) +| `uploadLimited` | boolean | true if `uploadLimit` is honored + +Just as an empty `ids` value is shorthand for "all ids", using an empty array +for `files-wanted`, `files-unwanted`, `priority-high`, `priority-low`, or +`priority-normal` is shorthand for saying "all files". + + Response arguments: none + +### 3.3. Torrent Accessor: `torrent-get` + +Method name: `torrent-get`. + +Request arguments: + +1. An optional `ids` array as described in 3.1. +2. A required `fields` array of keys. (see list below) +3. An optional `format` string specifying how to format the + `torrents` response field. Allowed values are `objects` + (default) and `table`. (see "Response arguments" below) + +Response arguments: + +1. A `torrents` array. + + If the `format` request was `objects` (default), `torrents` will + be an array of objects, each of which contains the key/value + pairs matching the request's `fields` arg. This was the only + format before Transmission 3 and has some obvious programmer + conveniences, such as parsing directly into Javascript objects. + + If the format was `table`, then `torrents` will be an array of + arrays. The first row holds the keys and each remaining row holds + a torrent's values for those keys. This format is more efficient + in terms of JSON generation and JSON parsing. + +2. If the request's `ids` field was `recently-active`, + a `removed` array of torrent-id numbers of recently-removed + torrents. + +Note: For more information on what these fields mean, see the comments +in [libtransmission/transmission.h](../libtransmission/transmission.h). +The 'source' column here corresponds to the data structure there. + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `activityDate` | number | tr_stat +| `addedDate` | number | tr_stat +| `bandwidthPriority` | number | tr_priority_t +| `comment` | string | tr_torrent_view +| `corruptEver`| number | tr_stat +| `creator`| string | tr_torrent_view +| `dateCreated`| number| tr_torrent_view +| `desiredAvailable`| number| tr_stat +| `doneDate`| number | tr_stat +| `downloadDir` | string | tr_torrent +| `downloadedEver` | number | tr_stat +| `downloadLimit` | number | tr_torrent +| `downloadLimited` | boolean | tr_torrent +| `editDate` | number | tr_stat +| `error` | number | tr_stat +| `errorString` | string | tr_stat +| `eta` | number | tr_stat +| `etaIdle` | number | tr_stat +| `file-count` | number | tr_info +| `files`| array (see below)| n/a +| `fileStats`| array (see below)| n/a +| `hashString`| string| tr_torrent_view +| `haveUnchecked`| number| tr_stat +| `haveValid`| number| tr_stat +| `honorsSessionLimits`| boolean| tr_torrent +| `id` | number | tr_torrent +| `isFinished` | boolean| tr_stat +| `isPrivate` | boolean| tr_torrent +| `isStalled` | boolean| tr_stat +| `labels` | array of strings | tr_torrent +| `leftUntilDone` | number| tr_stat +| `magnetLink` | string| n/a +| `manualAnnounceTime` | number| tr_stat +| `maxConnectedPeers` | number| tr_torrent +| `metadataPercentComplete` | double| tr_stat +| `name` | string| tr_torrent_view +| `peer-limit` | number| tr_torrent +| `peers` | array (see below)| n/a +| `peersConnected` | number| tr_stat +| `peersFrom` | object (see below)| n/a +| `peersGettingFromUs` | number| tr_stat +| `peersSendingToUs` | number| tr_stat +| `percentDone` | double| tr_stat +| `pieces` | string (see below)| tr_torrent +| `pieceCount`| number| tr_torrent_view +| `pieceSize`| number| tr_torrent_view +| `priorities`| array (see below)| n/a +| `primary-mime-type`| string| tr_torrent +| `queuePosition`| number| tr_stat +| `rateDownload (B/s)`| number| tr_stat +| `rateUpload (B/s)`| number| tr_stat +| `recheckProgress`| double| tr_stat +| `secondsDownloading`| number| tr_stat +| `secondsSeeding`| number| tr_stat +| `seedIdleLimit`| number| tr_torrent +| `seedIdleMode`| number| tr_inactvelimit +| `seedRatioLimit`| double| tr_torrent +| `seedRatioMode`| number| tr_ratiolimit +| `sizeWhenDone`| number| tr_stat +| `startDate`| number| tr_stat +| `status`| number (see below)| tr_stat +| `trackers`| array (see below)| n/a +| `trackerStats`| array (see below)| n/a +| `totalSize`| number| tr_torrent_view +| `torrentFile`| string| tr_info +| `uploadedEver`| number| tr_stat +| `uploadLimit`| number| tr_torrent +| `uploadLimited`| boolean| tr_torrent +| `uploadRatio`| double| tr_stat +| `wanted`| array (see below)| n/a +| `webseeds`| array of strings | tr_tracker_view +| `webseedsSendingToUs`| number| tr_stat + + +`files`: array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `bytesCompleted` | number | tr_file_view +| `length` | number | tr_file_view +| `name` | string | tr_file_view + + +`fileStats`: a file's non-constant properties. An array of `tr_info.filecount` objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `bytesCompleted` | number | tr_file_view +| `wanted` | boolean | tr_file_view +| `priority` | number | tr_file_view + +`peers`: an array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `address` | string | tr_peer_stat +| `clientName` | string | tr_peer_stat +| `clientIsChoked` | boolean | tr_peer_stat +| `clientIsInterested` | boolean | tr_peer_stat +| `flagStr` | string | tr_peer_stat +| `isDownloadingFrom` | boolean | tr_peer_stat +| `isEncrypted` | boolean | tr_peer_stat +| `isIncoming` | boolean | tr_peer_stat +| `isUploadingTo` | boolean | tr_peer_stat +| `isUTP` | boolean | tr_peer_stat +| `peerIsChoked` | boolean | tr_peer_stat +| `peerIsInterested` | boolean | tr_peer_stat +| `port` | number | tr_peer_stat +| `progress` | double | tr_peer_stat +| `rateToClient` (B/s) | number | tr_peer_stat +| `rateToPeer` (B/s) | number | tr_peer_stat + +`peersFrom`: an object containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `fromCache` | number | tr_stat +| `fromDht` | number | tr_stat +| `fromIncoming` | number | tr_stat +| `fromLpd` | number | tr_stat +| `fromLtep` | number | tr_stat +| `fromPex` | number | tr_stat +| `fromTracker` | number | tr_stat + + +`pieces`: A bitfield holding pieceCount flags which are set to 'true' if we have the piece matching that position. JSON doesn't allow raw binary data, so this is a base64-encoded string. (Source: tr_torrent) + +`priorities`: An array of `tr_torrentFileCount()` numbers. Each is the `tr_priority_t` mode for the corresponding file. + +`status`: A number between 0 and 6, where: + +| Value | Meaning +|:--|:-- +| 0 | Torrent is stopped +| 1 | Torrent is queued to verify local data +| 2 | Torrent is verifying local data +| 3 | Torrent is queued to download +| 4 | Torrent is downloading +| 5 | Torrent is queued to seed +| 6 | Torrent is seeding + + +`trackers`: array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `announce` | string | tr_tracker_info +| `id` | number | tr_tracker_info +| `scrape` | string | tr_tracker_info +| `tier` | number | tr_tracker_info + +`trackerStats`: array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `announce` | string | tr_tracker_stat +| `announceState` | number | tr_tracker_stat +| `downloadCount` | number | tr_tracker_stat +| `hasAnnounced` | boolean | tr_tracker_stat +| `hasScraped` | boolean | tr_tracker_stat +| `host` | string | tr_tracker_stat +| `id` | number | tr_tracker_stat +| `isBackup` | boolean | tr_tracker_stat +| `lastAnnouncePeerCount` | number | tr_tracker_stat +| `lastAnnounceResult` | string | tr_tracker_stat +| `lastAnnounceStartTime` | number | tr_tracker_stat +| `lastAnnounceSucceeded` | boolean | tr_tracker_stat +| `lastAnnounceTime` | number | tr_tracker_stat +| `lastAnnounceTimedOut` | boolean | tr_tracker_stat +| `lastScrapeResult` | string | tr_tracker_stat +| `lastScrapeStartTime` | number | tr_tracker_stat +| `lastScrapeSucceeded` | boolean | tr_tracker_stat +| `lastScrapeTime` | number | tr_tracker_stat +| `lastScrapeTimedOut` | boolean | tr_tracker_stat +| `leecherCount` | number | tr_tracker_stat +| `nextAnnounceTime` | number | tr_tracker_stat +| `nextScrapeTime` | number | tr_tracker_stat +| `scrape` | string | tr_tracker_stat +| `scrapeState` | number | tr_tracker_stat +| `seederCount` | number | tr_tracker_stat +| `tier` | number | tr_tracker_stat + + +`wanted`: An array of `tr_torrentFileCount()` booleans true if the corresponding file is to be downloaded. (Source: `tr_file_view`) + + +Example: + +Say we want to get the name and total size of torrents #7 and #10. + +Request: + +```json +{ + "arguments": { + "fields": [ "id", "name", "totalSize" ], + "ids": [ 7, 10 ] + }, + "method": "torrent-get", + "tag": 39693 +} +``` + +Response: + +```json +{ + "arguments": { + "torrents": [ + { + "id": 10, + "name": "Fedora x86_64 DVD", + "totalSize": 34983493932 + }, + { + "id": 7, + "name": "Ubuntu x86_64 DVD", + "totalSize": 9923890123 + } + ] + }, + "result": "success", + "tag": 39693 +} +``` + +### 3.4. Adding a Torrent + +Method name: `torrent-add` + +Request arguments: + +| Key | Value Type | Description +|:--|:--|:-- +| `cookies` | string | pointer to a string of one or more cookies. +| `download-dir` | string | path to download the torrent to +| `filename` | string | filename or URL of the .torrent file +| `labels` | array | array of string labels +| `metainfo` | string | base64-encoded .torrent content +| `paused` | boolean | if true, don't start the torrent +| `peer-limit` | number | maximum number of peers +| `bandwidthPriority` | number | torrent's bandwidth tr_priority_t +| `files-wanted` | array | indices of file(s) to download +| `files-unwanted` | array | indices of file(s) to not download +| `priority-high` | array | indices of high-priority file(s) +| `priority-low` | array | indices of low-priority file(s) +| `priority-normal` | array | indices of normal-priority file(s) + +Either `filename` **or** `metainfo` **must** be included. All other arguments are optional. + +The format of the `cookies` should be `NAME=CONTENTS`, where `NAME` is the cookie name and `CONTENTS` is what the cookie should contain. Set multiple cookies like this: `name1=content1; name2=content2;` etc. See [libcurl documentation](http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE) for more information. + +Response arguments: + +* On success, a `torrent-added` object in the form of one of 3.3's torrent objects with the fields for `id`, `name`, and `hashString`. + +* On failure due to a duplicate torrent existing, a `torrent-duplicate` object in the same form. + +### 3.5. Removing a Torrent + +Method name: `torrent-remove` + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | torrent list, as described in 3.1 +| `delete-local-data` | boolean | delete local data. (default: false) + +Response arguments: none + +### 3.6. Moving a Torrent + +Method name: `torrent-set-location` + +Request arguments: + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | torrent list, as described in 3.1 +| `location` | string | the new torrent location +| `move` | boolean | if true, move from previous location. otherwise, search "location" for files (default: false) + +Response arguments: none + +### 3.7. Renaming a Torrent's Path + +Method name: `torrent-rename-path` + +For more information on the use of this function, see the transmission.h +documentation of `tr_torrentRenamePath()`. In particular, note that if this +call succeeds you'll want to update the torrent's `files` and `name` field +with `torrent-get`. + +Request arguments: + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | the torrent torrent list, as described in 3.1 (must only be 1 torrent) +| `path` | string | the path to the file or folder that will be renamed +| `name` | string | the file or folder's new name + +Response arguments: `path`, `name`, and `id`, holding the torrent ID integer + +## 4. Session Requests + +### 4.1. Session Arguments + +| Key | Value Type | Description +|:--|:--|:-- +| `alt-speed-down` | number | max global download speed (KBps) +| `alt-speed-enabled` | boolean | true means use the alt speeds +| `alt-speed-time-begin` | number | when to turn on alt speeds (units: minutes after midnight) +| `alt-speed-time-day` | number | what day(s) to turn on alt speeds (look at tr_sched_day) +| `alt-speed-time-enabled` | boolean | true means the scheduled on/off times are used +| `alt-speed-time-end` | number | when to turn off alt speeds (units: same) +| `alt-speed-up` | number | max global upload speed (KBps) +| `blocklist-enabled` | boolean | true means enabled +| `blocklist-size` | number | number of rules in the blocklist +| `blocklist-url` | string | location of the blocklist to use for `blocklist-update` +| `cache-size-mb` | number | maximum size of the disk cache (MB) +| `config-dir` | string | location of transmission's configuration directory +| `dht-enabled` | boolean | true means allow dht in public torrents +| `download-dir` | string | default path to download torrents +| `download-queue-enabled` | boolean | if true, limit how many torrents can be downloaded at once +| `download-queue-size` | number | max number of torrents to download at once (see download-queue-enabled) +| `encryption` | string | `required`, `preferred`, `tolerated` +| `idle-seeding-limit-enabled` | boolean | true if the seeding inactivity limit is honored by default +| `idle-seeding-limit` | number | torrents we're seeding will be stopped if they're idle for this long +| `incomplete-dir-enabled` | boolean | true means keep torrents in incomplete-dir until done +| `incomplete-dir` | string | path for incomplete torrents, when enabled +| `lpd-enabled` | boolean | true means allow Local Peer Discovery in public torrents +| `peer-limit-global` | number | maximum global number of peers +| `peer-limit-per-torrent` | number | maximum global number of peers +| `peer-port-random-on-start` | boolean | true means pick a random peer port on launch +| `peer-port` | number | port number +| `pex-enabled` | boolean | true means allow pex in public torrents +| `port-forwarding-enabled` | boolean | true means ask upstream router to forward the configured peer port to transmission using UPnP or NAT-PMP +| `queue-stalled-enabled` | boolean | whether or not to consider idle torrents as stalled +| `queue-stalled-minutes` | number | torrents that are idle for N minuets aren't counted toward seed-queue-size or download-queue-size +| `rename-partial-files` | boolean | true means append `.part` to incomplete files +| `rpc-version-minimum` | number | the minimum RPC API version supported +| `rpc-version-semver` | number | the current RPC API version in a semver-compatible string +| `rpc-version` | number | the current RPC API version +| `script-torrent-added-enabled` | boolean | whether or not to call the `done` script +| `script-torrent-added-filename` | string | filename of the script to run +| `script-torrent-done-enabled` | boolean | whether or not to call the `done` script +| `script-torrent-done-filename` | string | filename of the script to run +| `seed-queue-enabled` | boolean | if true, limit how many torrents can be uploaded at once +| `seed-queue-size` | number | max number of torrents to uploaded at once (see seed-queue-enabled) +| `seedRatioLimit` | double | the default seed ratio for torrents to use +| `seedRatioLimited` | boolean | true if seedRatioLimit is honored by default +| `speed-limit-down-enabled` | boolean | true means enabled +| `speed-limit-down` | number | max global download speed (KBps) +| `speed-limit-up-enabled` | boolean | true means enabled +| `speed-limit-up` | number | max global upload speed (KBps) +| `start-added-torrents` | boolean | true means added torrents will be started right away +| `trash-original-torrent-files` | boolean | true means the .torrent file of added torrents will be deleted +| `units` | object | see below +| `utp-enabled` | boolean | true means allow utp +| `version` | string | long version string `$version ($revision)` + + +`units`: an object containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `speed-units` | array | 4 strings: KB/s, MB/s, GB/s, TB/s +| `speed-bytes` | number | number of bytes in a KB (1000 for kB; 1024 for KiB) +| `size-units` | array | 4 strings: KB/s, MB/s, GB/s, TB/s +| `size-bytes` | number | number of bytes in a KB (1000 for kB; 1024 for KiB) +| `memory-units` | array | 4 strings: KB/s, MB/s, GB/s, TB/s +| `memory-bytes` | number | number of bytes in a KB (1000 for kB; 1024 for KiB) + +`rpc-version` indicates the RPC interface version supported by the RPC server. +It is incremented when a new version of Transmission changes the RPC interface. + +`rpc-version-minimum` indicates the oldest API supported by the RPC server. +It is changes when a new version of Transmission changes the RPC interface +in a way that is not backwards compatible. There are no plans for this +to be common behavior. + +#### 4.1.1. Mutators + +Method name: `session-set` + +Request arguments: one or more of 4.1's arguments, except: `blocklist-size`, +`config-dir`, `rpc-version`, `rpc-version-minimum`, +`version`, and `session-id` + +Response arguments: none + +#### 4.1.2. Accessors + +Method name: `session-get` + +Request arguments: an optional `fields` array of keys (see 4.1) + +Response arguments: key/value pairs matching the request's `fields` +argument if present, or all supported fields (see 4.1) otherwise. + +### 4.2. Session Statistics + +Method name: `session-stats` + +Request arguments: none + +Response arguments: + +| Key | Value Type | Description +|:--|:--|:-- +| `activeTorrentCount` | number +| `downloadSpeed` | number +| `pausedTorrentCount` | number +| `torrentCount` | number +| `uploadSpeed` | number +| `cumulative-stats` | stats object (see below) +| `current-stats` | stats object (see below) + +A stats object contains: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| uploadedBytes | number | tr_session_stats +| downloadedBytes | number | tr_session_stats +| filesAdded | number | tr_session_stats +| sessionCount | number | tr_session_stats +| secondsActive | number | tr_session_stats + +### 4.3. Blocklist + +Method name: `blocklist-update` + +Request arguments: none + +Response arguments: a number `blocklist-size` + +### 4.4. Port Checking + +This method tests to see if your incoming peer port is accessible +from the outside world. + +Method name: `port-test` + +Request arguments: none + +Response arguments: a bool, `port-is-open` + +### 4.5. Session shutdown + +This method tells the transmission session to shut down. + +Method name: `session-close` + +Request arguments: none + +Response arguments: none + +### 4.6. Queue Movement Requests + +| Method name | transmission.h source +|:--|:-- +| `queue-move-top` | tr_torrentQueueMoveTop() +| `queue-move-up` | tr_torrentQueueMoveUp() +| `queue-move-down` | tr_torrentQueueMoveDown() +| `queue-move-bottom` | tr_torrentQueueMoveBottom() + +Request arguments: + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | torrent list, as described in 3.1. + +Response arguments: none + +### 4.7. Free Space + +This method tests how much free space is available in a +client-specified folder. + +Method name: `free-space` + +Request arguments: + +| Key | Value type | Description +|:--|:-- +| `path` | string | the directory to query + +Response arguments: + +| Key | Value type | Description +|:--|:--|:-- +| `path` | string | same as the Request argument +| `size-bytes` | number | the size, in bytes, of the free space in that directory +| `total_size` | number | the total capacity, in bytes, of that directory + + +## 5. Protocol Versions + +This section lists the changes that have been made to the RPC protocol. + +There are two ways to check for API compatibility. Since most developers know +semver, session-get's `rpc-version-semver` is the recommended way. That value +is a semver-compatible string of the RPC protocol version number. + +Since Transmission predates the semver 1.0 spec, the previous scheme was for +the RPC version to be a whole number and to increment it whenever a change was +made. That is session-get's `rpc-version`. `rpc-version-minimum` lists the +oldest version that is compatible with the current version; i.e. an app coded +to use `rpc-version-minimum` would still work on a Transmission release running +`rpc-version`. + +Breaking changes are denoted with a :bomb: emoji. + +Transmission 1.30 (`rpc-version-semver` 1.0.0, `rpc-version`: 1) + +Initial revision. + +Transmission 1.40 (`rpc-version-semver` 1.1.0, `rpc-version`: 2) + +| Method | Description +|:---|:--- +| `torrent-get` | new `port` to `peers` + +Transmission 1.41 (`rpc-version-semver` 1.2.0, `rpc-version`: 3) + +| Method | Description +|:---|:--- +| `session-get` | new arg `version` +| `torrent-get` | new arg `downloaders` +| `torrent-remove` | new method + +Transmission 1.50 (`rpc-version-semver` 1.3.0, `rpc-version`: 4) + +| Method | Description +|:---|:--- +|`session-get` | new arg `rpc-version-minimum` +|`session-get` | new arg `rpc-version` +|`session-stats` | added `cumulative-stats` +|`session-stats` | added `current-stats` +|`torrent-get` | new arg `downloadDir` + +Transmission 1.60 (`rpc-version-semver` 2.0.0, `rpc-version`: 5) + +| Method | Description +|:---|:--- +| `session-get` | :bomb: renamed `peer-limit` to `peer-limit-global` +| `session-get` | :bomb: renamed `pex-allowed` to `pex-enabled` +| `session-get` | :bomb: renamed `port` to `peer-port` +| `torrent-get` | :bomb: removed arg `downloadLimitMode` +| `torrent-get` | :bomb: removed arg `uploadLimitMode` +| `torrent-set` | :bomb: renamed `speed-limit-down-enabled` to `downloadLimited` +| `torrent-set` | :bomb: renamed `speed-limit-down` to `downloadLimit` +| `torrent-set` | :bomb: renamed `speed-limit-up-enabled` to `uploadLimited` +| `torrent-set` | :bomb: renamed `speed-limit-up` to `uploadLimit` +| `blocklist-update` | new method +| `port-test` | new method +| `session-get` | new arg `alt-speed-begin` +| `session-get` | new arg `alt-speed-down` +| `session-get` | new arg `alt-speed-enabled` +| `session-get` | new arg `alt-speed-end` +| `session-get` | new arg `alt-speed-time-enabled` +| `session-get` | new arg `alt-speed-up` +| `session-get` | new arg `blocklist-enabled` +| `session-get` | new arg `blocklist-size` +| `session-get` | new arg `peer-limit-per-torrent` +| `session-get` | new arg `seedRatioLimit` +| `session-get` | new arg `seedRatioLimited` +| `torrent-add` | new arg `files-unwanted` +| `torrent-add` | new arg `files-wanted` +| `torrent-add` | new arg `priority-high` +| `torrent-add` | new arg `priority-low` +| `torrent-add` | new arg `priority-normal` +| `torrent-get` | new arg `bandwidthPriority` +| `torrent-get` | new arg `fileStats` +| `torrent-get` | new arg `honorsSessionLimits` +| `torrent-get` | new arg `percentDone` +| `torrent-get` | new arg `pieces` +| `torrent-get` | new arg `seedRatioLimit` +| `torrent-get` | new arg `seedRatioMode` +| `torrent-get` | new arg `torrentFile` +| `torrent-get` | new ids option `recently-active` +| `torrent-reannounce` | new method +| `torrent-set` | new arg `bandwidthPriority` +| `torrent-set` | new arg `honorsSessionLimits` +| `torrent-set` | new arg `seedRatioLimit` +| `torrent-set` | new arg `seedRatioLimited` + +Transmission 1.70 (`rpc-version-semver` 2.1.0, `rpc-version`: 6) + +| Method | Description +|:---|:--- +| `method torrent-set-location` | new method + +Transmission 1.80 (`rpc-version-semver` 3.0.0, `rpc-version`: 7) + +| Method | Description +|:---|:--- +| `torrent-get` | :bomb: removed arg `announceResponse` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `announceURL` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `downloaders` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `lastAnnounceTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `lastScrapeTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `leechers` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `nextAnnounceTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `nextScrapeTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `scrapeResponse` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `scrapeURL` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `seeders` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `swarmSpeed` +| `torrent-get` | :bomb: removed arg `timesCompleted` (use `trackerStats instead`) +| `session-set` | new arg `incomplete-dir-enabled` +| `session-set` | new arg `incomplete-dir` +| `torrent-get` | new arg `magnetLink` +| `torrent-get` | new arg `metadataPercentComplete` +| `torrent-get` | new arg `trackerStats` + +Transmission 1.90 (`rpc-version-semver` 3.1.0, `rpc-version`: 8) + +| Method | Description +|:---|:--- +| `session-set` | new arg `rename-partial-files` +| `session-get` | new arg `rename-partial-files` +| `session-get` | new arg `config-dir` +| `torrent-add` | new arg `bandwidthPriority` +| `torrent-get` | new trackerStats arg `lastAnnounceTimedOut` + +Transmission 1.92 (`rpc-version-semver` 3.2.0, `rpc-version`: 8) + +Note: `rpc-version` was not bumped in this release due to an oversight. + +| Method | Description +|:---|:--- +| `torrent-get` | new trackerStats arg `lastScrapeTimedOut` + +Transmission 2.00 (`rpc-version-semver` 3.3.0, `rpc-version`: 9) + +| Method | Description +|:---|:--- +| `session-set` | new arg `start-added-torrents` +| `session-set` | new arg `trash-original-torrent-files` +| `session-get` | new arg `start-added-torrents` +| `session-get` | new arg `trash-original-torrent-files` +| `torrent-get` | new arg `isFinished` + +Transmission 2.10 (`rpc-version-semver` 3.4.0, `rpc-version`: 10) + +| Method | Description +|:---|:--- +| `session-get` | new arg `cache-size-mb` +| `session-get` | new arg `units` +| `session-set` | new arg `idle-seeding-limit-enabled` +| `session-set` | new arg `idle-seeding-limit` +| `torrent-set` | new arg `seedIdleLimit` +| `torrent-set` | new arg `seedIdleMode` +| `torrent-set` | new arg `trackerAdd` +| `torrent-set` | new arg `trackerRemove` +| `torrent-set` | new arg `trackerReplace` + +Transmission 2.12 (`rpc-version-semver` 3.5.0, `rpc-version`: 11) + +| Method | Description +|:---|:--- +| `session-get` | new arg `blocklist-url` +| `session-set` | new arg `blocklist-url` + +Transmission 2.20 (`rpc-version-semver` 3.6.0, `rpc-version`: 12) + +| Method | Description +|:---|:--- +| `session-get` | new arg `download-dir-free-space` +| `session-close` | new method + +Transmission 2.30 (`rpc-version-semver` 4.0.0, `rpc-version`: 13) + +| Method | Description +|:---|:--- +| `torrent-get` | :bomb: removed arg `peersKnown` +| `session-get` | new arg `isUTP` to the `peers` list +| `torrent-add` | new arg `cookies` + +Transmission 2.40 (`rpc-version-semver` 5.0.0, `rpc-version`: 14) + +| Method | Description +|:---|:--- +| `torrent-get` | :bomb: values of `status` field changed +| `queue-move-bottom` | new method +| `queue-move-down` | new method +| `queue-move-top` | new method +| `session-set` | new arg `download-queue-enabled` +| `session-set` | new arg `download-queue-size` +| `session-set` | new arg `queue-stalled-enabled` +| `session-set` | new arg `queue-stalled-minutes` +| `session-set` | new arg `seed-queue-enabled` +| `session-set` | new arg `seed-queue-size` +| `torrent-get` | new arg `fromLpd` in peersFrom +| `torrent-get` | new arg `isStalled` +| `torrent-get` | new arg `queuePosition` +| `torrent-set` | new arg `queuePosition` +| `torrent-start-now` | new method + +Transmission 2.80 (`rpc-version-semver` 5.1.0, `rpc-version`: 15) + +| Method | Description +|:---|:--- +| `torrent-get` | new arg `etaIdle` +| `torrent-rename-path` | new method +| `free-space` | new method +| `torrent-add` | new return arg `torrent-duplicate` + +Transmission 3.00 (`rpc-version-semver` 5.2.0, `rpc-version`: 16) + +| Method | Description +|:---|:--- +| `session-get` | new request arg `fields` +| `session-get` | new arg `session-id` +| `torrent-get` | new arg `labels` +| `torrent-set` | new arg `labels` +| `torrent-get` | new arg `editDate` +| `torrent-get` | new request arg `format` + +Transmission 4.0.0 (`rpc-version-semver` 5.3.0, `rpc-version`: 17) + +| Method | Description +|:---|:--- +| `/upload` | :warning: undocumented `/upload` endpoint removed +| `free-space` | new return arg `total-capacity` +| `session-get` | new arg `rpc-version-semver` +| `session-get` | new arg `script-torrent-added-enabled` +| `session-get` | new arg `script-torrent-added-filename` +| `torrent-add` | new arg `labels` +| `torrent-get` | new arg `file-count` +| `torrent-get` | new arg `primary-mime-type` + + +### 5.1. Upcoming Breakage + +These features are deprecated: + +1. session-get's 'download-dir-free-space' argument will be removed. + Its functionality has been superceded by the 'free-space' method. + +2. HTTP POSTs to http://server:port/transmission/upload will fail. + This was an undocumented hack to allow web clients to add files without + client-side access to the file. This functionality is superceded by + using HTML5's FileReader object + the documented 'torrent-add' method. diff --git a/extras/rpc-spec.txt b/extras/rpc-spec.txt deleted file mode 100644 index 229480c0c..000000000 --- a/extras/rpc-spec.txt +++ /dev/null @@ -1,874 +0,0 @@ -1. Introduction - - This document describes a protocol for interacting with Transmission - sessions remotely. - -1.1 Terminology - - The JSON terminology in RFC 4627 is used. - - JSON is fairly common now, but for the benefit of - torrent developers familiar with benc: - a JSON array is equivalent to a benc list, - a JSON object is equivalent to a benc dictionary, - and a JSON object's keys are the dictionary's string keys. - -1.2 Resources - - The command-line utility "transmission-remote" uses this RPC API. - Several developers have reported using its --debug JSON output as - a reference when developing/debugging their own code. - -2. Message Format - - Messages are formatted as objects. There are two types: - requests (described in 2.1) and responses (described in 2.2). - - All text MUST be UTF-8 encoded. - -2.1. Requests - - Requests support 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" number used by clients to track responses. - If provided by a request, the response MUST include the same tag. - -2.2. Responses - - Responses 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" number as described in 2.1. - -2.3. Transport Mechanism - - HTTP POSTing a JSON-encoded request is the preferred way of communicating - with a Transmission RPC server. The current Transmission implementation - has the default URL as http://host:9091/transmission/rpc. Clients - may use this as a default, but should allow the URL to be reconfigured, - since the port and path may be changed to allow mapping and/or multiple - daemons to run on a single server. - -2.3.1. CSRF Protection - - Most Transmission RPC servers require a X-Transmission-Session-Id - header to be sent with requests, to prevent CSRF attacks. - - When your request has the wrong id -- such as when you send your first - request, or when the server expires the CSRF token -- the - Transmission RPC server will return an HTTP 409 error with the - right X-Transmission-Session-Id in its own headers. - - So, the correct way to handle a 409 response is to update your - X-Transmission-Session-Id and to resend the previous request. - -2.3.2. DNS Rebinding Protection - - Additional check is being made on each RPC request to make sure that the - client sending the request does so using one of the allowed hostnames by - which RPC server is meant to be available. - - If host whitelisting is enabled (which is true by default), Transmission - inspects the "Host:" HTTP header value (with port stripped, if any) and - matches it to one of the whitelisted names. Regardless of host whitelist - content, "localhost" and "localhost." domain names as well as all the IP - addresses are always implicitly allowed. - - For more information on configuration, see settings.json documentation for - "rpc-host-whitelist-enabled" and "rpc-host-whitelist" keys. - -2.3.3. Authentication - - Enabling authentication is an optional security feature that can be enabled - on Transmission RPC servers. Authentication occurs by method of HTTP Basic - Access Authentication. - - If authentication is enabled, Transmission inspects the "Authorization:" - HTTP header value to validate the credentials of the request. The value - of this HTTP header is expected to be "Basic ", where - is equal to a base64 encoded string of the username - and password (respectively), separated by a colon. - - -3. Torrent Requests - -3.1. Torrent Action Requests - - Method name | libtransmission function - ---------------------+------------------------------------------------- - "torrent-start" | tr_torrentStart - "torrent-start-now" | tr_torrentStartNow - "torrent-stop" | tr_torrentStop - "torrent-verify" | tr_torrentVerify - "torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers") - - Request arguments: "ids", which specifies which torrents to use. - All torrents are used if the "ids" argument is omitted. - "ids" should be one of the following: - (1) an integer referring to a torrent id - (2) a list of torrent id numbers, sha1 hash strings, or both - (3) a string, "recently-active", for recently-active torrents - - Response arguments: none - -3.2. Torrent Mutators - - Method name: "torrent-set" - - Request arguments: - - string | value type & description - ----------------------+------------------------------------------------- - "bandwidthPriority" | number this torrent's bandwidth tr_priority_t - "downloadLimit" | number maximum download speed (KBps) - "downloadLimited" | boolean true if "downloadLimit" is honored - "files-wanted" | array indices of file(s) to download - "files-unwanted" | array indices of file(s) to not download - "honorsSessionLimits" | boolean true if session upload limits are honored - "ids" | array torrent list, as described in 3.1 - "labels" | array array of string labels - "location" | string new location of the torrent's content - "peer-limit" | number maximum number of peers - "priority-high" | array indices of high-priority file(s) - "priority-low" | array indices of low-priority file(s) - "priority-normal" | array indices of normal-priority file(s) - "queuePosition" | number position of this torrent in its queue [0...n) - "seedIdleLimit" | number torrent-level number of minutes of seeding inactivity - "seedIdleMode" | number which seeding inactivity to use. See tr_idlelimit - "seedRatioLimit" | double torrent-level seeding ratio - "seedRatioMode" | number which ratio to use. See tr_ratiolimit - "trackerAdd" | array strings of announce URLs to add - "trackerRemove" | array ids of trackers to remove - "trackerReplace" | array pairs of - "uploadLimit" | number maximum upload speed (KBps) - "uploadLimited" | boolean true if "uploadLimit" is honored - - Just as an empty "ids" value is shorthand for "all ids", using an empty array - for "files-wanted", "files-unwanted", "priority-high", "priority-low", or - "priority-normal" is shorthand for saying "all files". - - Response arguments: none - -3.3. Torrent Accessors - - Method name: "torrent-get". - - Request arguments: - - (1) An optional "ids" array as described in 3.1. - (2) A required "fields" array of keys. (see list below) - (3) An optional "format" string specifying how to format the - "torrents" response field. Allowed values are "objects" (default) - and "table". (see "Response arguments" below) - - Response arguments: - - (1) A "torrents" array. - - If the "format" request was "objects" (default), "torrents" will - be an array of objects, each of which contains the key/value - pairs matching the request's "fields" arg. This was the only - format before Transmission 3 and has some obvious programmer - conveniences, such as parsing directly into Javascript objects. - - If the format was "table", then "torrents" will be an array of - arrays. The first row holds the keys and each remaining row holds - a torrent's values for those keys. This format is more efficient - in terms of JSON generation and JSON parsing. - - (2) If the request's "ids" field was "recently-active", - a "removed" array of torrent-id numbers of recently-removed - torrents. - - Note: For more information on what these fields mean, see the comments - in libtransmission/transmission.h. The "source" column here - corresponds to the data structure there. - - key | type | source - ----------------------------+-----------------------------+--------- - activityDate | number | tr_stat - addedDate | number | tr_stat - bandwidthPriority | number | tr_priority_t - comment | string | tr_info - corruptEver | number | tr_stat - creator | string | tr_info - dateCreated | number | tr_info - desiredAvailable | number | tr_stat - doneDate | number | tr_stat - downloadDir | string | tr_torrent - downloadedEver | number | tr_stat - downloadLimit | number | tr_torrent - downloadLimited | boolean | tr_torrent - editDate | number | tr_stat - error | number | tr_stat - errorString | string | tr_stat - eta | number | tr_stat - etaIdle | number | tr_stat - file-count | number | tr_info - files | array (see below) | n/a - fileStats | array (see below) | n/a - hashString | string | tr_info - haveUnchecked | number | tr_stat - haveValid | number | tr_stat - honorsSessionLimits | boolean | tr_torrent - id | number | tr_torrent - isFinished | boolean | tr_stat - isPrivate | boolean | tr_torrent - isStalled | boolean | tr_stat - labels | array (see below) | tr_torrent - leftUntilDone | number | tr_stat - magnetLink | string | n/a - manualAnnounceTime | number | tr_stat - maxConnectedPeers | number | tr_torrent - metadataPercentComplete | double | tr_stat - name | string | tr_info - peer-limit | number | tr_torrent - peers | array (see below) | n/a - peersConnected | number | tr_stat - peersFrom | object (see below) | n/a - peersGettingFromUs | number | tr_stat - peersSendingToUs | number | tr_stat - percentDone | double | tr_stat - pieces | string (see below) | tr_torrent - pieceCount | number | tr_info - pieceSize | number | tr_info - priorities | array (see below) | n/a - primary-mime-type | string | tr_torrent - queuePosition | number | tr_stat - rateDownload (B/s) | number | tr_stat - rateUpload (B/s) | number | tr_stat - recheckProgress | double | tr_stat - secondsDownloading | number | tr_stat - secondsSeeding | number | tr_stat - seedIdleLimit | number | tr_torrent - seedIdleMode | number | tr_inactvelimit - seedRatioLimit | double | tr_torrent - seedRatioMode | number | tr_ratiolimit - sizeWhenDone | number | tr_stat - startDate | number | tr_stat - status | number (see below) | tr_stat - trackers | array (see below) | n/a - trackerStats | array (see below) | n/a - totalSize | number | tr_info - torrentFile | string | tr_info - uploadedEver | number | tr_stat - uploadLimit | number | tr_torrent - uploadLimited | boolean | tr_torrent - uploadRatio | double | tr_stat - wanted | array (see below) | n/a - webseeds | array (see below) | n/a - webseedsSendingToUs | number | tr_stat - | | - | | - -------------------+--------+-----------------------------+ - files | array of objects, each containing: | - +-------------------------+------------+ - | bytesCompleted | number | tr_torrent - | length | number | tr_info - | name | string | tr_info - -------------------+--------------------------------------+ - fileStats | a file's non-constant properties. | - | array of tr_info.filecount objects, | - | each containing: | - +-------------------------+------------+ - | bytesCompleted | number | tr_torrent - | wanted | boolean | tr_info - | priority | number | tr_info - -------------------+--------------------------------------+ - labels | an array of strings: | - +-------------------------+------------+ - | label | string | tr_torrent - -------------------+--------------------------------------+ - peers | array of objects, each containing: | - +-------------------------+------------+ - | address | string | tr_peer_stat - | clientName | string | tr_peer_stat - | clientIsChoked | boolean | tr_peer_stat - | clientIsInterested | boolean | tr_peer_stat - | flagStr | string | tr_peer_stat - | isDownloadingFrom | boolean | tr_peer_stat - | isEncrypted | boolean | tr_peer_stat - | isIncoming | boolean | tr_peer_stat - | isUploadingTo | boolean | tr_peer_stat - | isUTP | boolean | tr_peer_stat - | peerIsChoked | boolean | tr_peer_stat - | peerIsInterested | boolean | tr_peer_stat - | port | number | tr_peer_stat - | progress | double | tr_peer_stat - | rateToClient (B/s) | number | tr_peer_stat - | rateToPeer (B/s) | number | tr_peer_stat - -------------------+--------------------------------------+ - peersFrom | an object containing: | - +-------------------------+------------+ - | fromCache | number | tr_stat - | fromDht | number | tr_stat - | fromIncoming | number | tr_stat - | fromLpd | number | tr_stat - | fromLtep | number | tr_stat - | fromPex | number | tr_stat - | fromTracker | number | tr_stat - -------------------+--------------------------------------+ - pieces | A bitfield holding pieceCount flags | tr_torrent - | which are set to 'true' if we have | - | the piece matching that position. | - | JSON doesn't allow raw binary data, | - | so this is a base64-encoded string. | - -------------------+--------------------------------------+ - priorities | an array of tr_info.filecount | tr_info - | numbers. each is the tr_priority_t | - | mode for the corresponding file. | - -------------------+--------------------------------------+ - status | a number between 0 and 6, where: | tr_stat - | 0: Torrent is stopped | - | 1: Queued to check files | - | 2: Checking files | - | 3: Queued to download | - | 4: Downloading | - | 5: Queued to seed | - | 6: Seeding | - -------------------+--------------------------------------+ - trackers | array of objects, each containing: | - +-------------------------+------------+ - | announce | string | tr_tracker_info - | id | number | tr_tracker_info - | scrape | string | tr_tracker_info - | tier | number | tr_tracker_info - -------------------+--------------------------------------+ - trackerStats | array of objects, each containing: | - +-------------------------+------------+ - | announce | string | tr_tracker_stat - | announceState | number | tr_tracker_stat - | downloadCount | number | tr_tracker_stat - | hasAnnounced | boolean | tr_tracker_stat - | hasScraped | boolean | tr_tracker_stat - | host | string | tr_tracker_stat - | id | number | tr_tracker_stat - | isBackup | boolean | tr_tracker_stat - | lastAnnouncePeerCount | number | tr_tracker_stat - | lastAnnounceResult | string | tr_tracker_stat - | lastAnnounceStartTime | number | tr_tracker_stat - | lastAnnounceSucceeded | boolean | tr_tracker_stat - | lastAnnounceTime | number | tr_tracker_stat - | lastAnnounceTimedOut | boolean | tr_tracker_stat - | lastScrapeResult | string | tr_tracker_stat - | lastScrapeStartTime | number | tr_tracker_stat - | lastScrapeSucceeded | boolean | tr_tracker_stat - | lastScrapeTime | number | tr_tracker_stat - | lastScrapeTimedOut | boolean | tr_tracker_stat - | leecherCount | number | tr_tracker_stat - | nextAnnounceTime | number | tr_tracker_stat - | nextScrapeTime | number | tr_tracker_stat - | scrape | string | tr_tracker_stat - | scrapeState | number | tr_tracker_stat - | seederCount | number | tr_tracker_stat - | tier | number | tr_tracker_stat - -------------------+-------------------------+------------+ - wanted | an array of tr_info.fileCount | tr_info - | 'booleans' true if the corresponding | - | file is to be downloaded. | - -------------------+--------------------------------------+ - webseeds | an array of strings: | - +-------------------------+------------+ - | webseed | string | tr_info - +-------------------------+------------+ - - Example: - - Say we want to get the name and total size of torrents #7 and #10. - - Request: - - { - "arguments": { - "fields": [ "id", "name", "totalSize" ], - "ids": [ 7, 10 ] - }, - "method": "torrent-get", - "tag": 39693 - } - - - Response: - - { - "arguments": { - "torrents": [ - { - "id": 10, - "name": "Fedora x86_64 DVD", - "totalSize": 34983493932, - }, - { - "id": 7, - "name": "Ubuntu x86_64 DVD", - "totalSize", 9923890123, - } - ] - }, - "result": "success", - "tag": 39693 - } - -3.4. Adding a Torrent - - Method name: "torrent-add" - - Request arguments: - - key | value type & description - ---------------------+------------------------------------------------- - "cookies" | string pointer to a string of one or more cookies. - "download-dir" | string path to download the torrent to - "filename" | string filename or URL of the .torrent file - "labels" | array array of string labels - "metainfo" | string base64-encoded .torrent content - "paused" | boolean if true, don't start the torrent - "peer-limit" | number maximum number of peers - "bandwidthPriority" | number torrent's bandwidth tr_priority_t - "files-wanted" | array indices of file(s) to download - "files-unwanted" | array indices of file(s) to not download - "priority-high" | array indices of high-priority file(s) - "priority-low" | array indices of low-priority file(s) - "priority-normal" | array indices of normal-priority file(s) - - Either "filename" OR "metainfo" MUST be included. - All other arguments are optional. - - The format of the "cookies" should be NAME=CONTENTS, where NAME is the - cookie name and CONTENTS is what the cookie should contain. - Set multiple cookies like this: "name1=content1; name2=content2;" etc. - - - Response arguments: On success, a "torrent-added" object in the - form of one of 3.3's tr_info objects with the - fields for id, name, and hashString. - - On failure due to a duplicate torrent existing, - a "torrent-duplicate" object in the same form. - -3.5. Removing a Torrent - - Method name: "torrent-remove" - - Request arguments: - - string | value type & description - ---------------------------+------------------------------------------------- - "ids" | array torrent list, as described in 3.1 - "delete-local-data" | boolean delete local data. (default: false) - - Response arguments: none - - -3.6. Moving a Torrent - - Method name: "torrent-set-location" - - Request arguments: - - string | value type & description - ---------------------------------+------------------------------------------------- - "ids" | array torrent list, as described in 3.1 - "location" | string the new torrent location - "move" | boolean if true, move from previous location. - | otherwise, search "location" for files - | (default: false) - - Response arguments: none - - -3.7. Renaming a Torrent's Path - - Method name: "torrent-rename-path" - - For more information on the use of this function, see the transmission.h - documentation of tr_torrentRenamePath(). In particular, note that if this - call succeeds you'll want to update the torrent's "files" and "name" field - with torrent-get. - - Request arguments: - - string | value type & description - ---------------------------------+------------------------------------------------- - "ids" | array the torrent torrent list, as described in 3.1 - | (must only be 1 torrent) - "path" | string the path to the file or folder that will be renamed - "name" | string the file or folder's new name - - Response arguments: "path", "name", and "id", holding the torrent ID integer - - -4. Session Requests - -4.1. Session Arguments - - string | value type | description - ---------------------------------+------------+------------------------------------- - "alt-speed-down" | number | max global download speed (KBps) - "alt-speed-enabled" | boolean | true means use the alt speeds - "alt-speed-time-begin" | number | when to turn on alt speeds (units: minutes after midnight) - "alt-speed-time-enabled" | boolean | true means the scheduled on/off times are used - "alt-speed-time-end" | number | when to turn off alt speeds (units: same) - "alt-speed-time-day" | number | what day(s) to turn on alt speeds (look at tr_sched_day) - "alt-speed-up" | number | max global upload speed (KBps) - "blocklist-url" | string | location of the blocklist to use for "blocklist-update" - "blocklist-enabled" | boolean | true means enabled - "blocklist-size" | number | number of rules in the blocklist - "cache-size-mb" | number | maximum size of the disk cache (MB) - "config-dir" | string | location of transmission's configuration directory - "download-dir" | string | default path to download torrents - "download-queue-size" | number | max number of torrents to download at once (see download-queue-enabled) - "download-queue-enabled" | boolean | if true, limit how many torrents can be downloaded at once - "dht-enabled" | boolean | true means allow dht in public torrents - "encryption" | string | "required", "preferred", "tolerated" - "idle-seeding-limit" | number | torrents we're seeding will be stopped if they're idle for this long - "idle-seeding-limit-enabled" | boolean | true if the seeding inactivity limit is honored by default - "incomplete-dir" | string | path for incomplete torrents, when enabled - "incomplete-dir-enabled" | boolean | true means keep torrents in incomplete-dir until done - "lpd-enabled" | boolean | true means allow Local Peer Discovery in public torrents - "peer-limit-global" | number | maximum global number of peers - "peer-limit-per-torrent" | number | maximum global number of peers - "pex-enabled" | boolean | true means allow pex in public torrents - "peer-port" | number | port number - "peer-port-random-on-start" | boolean | true means pick a random peer port on launch - "port-forwarding-enabled" | boolean | true means ask upstream router to forward the configured peer port to transmission using UPnP or NAT-PMP - "queue-stalled-enabled" | boolean | whether or not to consider idle torrents as stalled - "queue-stalled-minutes" | number | torrents that are idle for N minuets aren't counted toward seed-queue-size or download-queue-size - "rename-partial-files" | boolean | true means append ".part" to incomplete files - "rpc-version" | number | the current RPC API version - "rpc-version-minimum" | number | the minimum RPC API version supported - "rpc-version-semver" | number | the current RPC API version in a semver-compatible string - "script-torrent-added-filename" | string | filename of the script to run - "script-torrent-added-enabled" | boolean | whether or not to call the "done" script - "script-torrent-done-filename" | string | filename of the script to run - "script-torrent-done-enabled" | boolean | whether or not to call the "done" script - "seedRatioLimit" | double | the default seed ratio for torrents to use - "seedRatioLimited" | boolean | true if seedRatioLimit is honored by default - "seed-queue-size" | number | max number of torrents to uploaded at once (see seed-queue-enabled) - "seed-queue-enabled" | boolean | if true, limit how many torrents can be uploaded at once - "speed-limit-down" | number | max global download speed (KBps) - "speed-limit-down-enabled" | boolean | true means enabled - "speed-limit-up" | number | max global upload speed (KBps) - "speed-limit-up-enabled" | boolean | true means enabled - "start-added-torrents" | boolean | true means added torrents will be started right away - "trash-original-torrent-files" | boolean | true means the .torrent file of added torrents will be deleted - "units" | object | see below - "utp-enabled" | boolean | true means allow utp - "version" | string | long version string "$version ($revision)" - ---------------------------------+------------+-----------------------------+ - units | object containing: | - +--------------+--------+------------------+ - | speed-units | array | 4 strings: KB/s, MB/s, GB/s, TB/s - | speed-bytes | number | number of bytes in a KB (1000 for kB; 1024 for KiB) - | size-units | array | 4 strings: KB/s, MB/s, GB/s, TB/s - | size-bytes | number | number of bytes in a KB (1000 for kB; 1024 for KiB) - | memory-units | array | 4 strings: KB/s, MB/s, GB/s, TB/s - | memory-bytes | number | number of bytes in a KB (1000 for kB; 1024 for KiB) - +--------------+--------+------------------+ - - "rpc-version" indicates the RPC interface version supported by the RPC server. - It is incremented when a new version of Transmission changes the RPC interface. - - "rpc-version-minimum" indicates the oldest API supported by the RPC server. - It is changes when a new version of Transmission changes the RPC interface - in a way that is not backwards compatible. There are no plans for this - to be common behavior. - -4.1.1. Mutators - - Method name: "session-set" - Request arguments: one or more of 4.1's arguments, except: "blocklist-size", - "config-dir", "rpc-version", "rpc-version-minimum", - "version", and "session-id" - Response arguments: none - -4.1.2. Accessors - - Method name: "session-get" - Request arguments: an optional "fields" array of keys (see 4.1) - Response arguments: key/value pairs matching the request's "fields" - argument if present, or all supported fields (see 4.1) otherwise. - -4.2. Session Statistics - - Method name: "session-stats" - - Request arguments: none - - Response arguments: - - string | value type - ---------------------------+------------------------------------------------- - "activeTorrentCount" | number - "downloadSpeed" | number - "pausedTorrentCount" | number - "torrentCount" | number - "uploadSpeed" | number - ---------------------------+-------------------------------+ - "cumulative-stats" | object, containing: | - +------------------+------------+ - | uploadedBytes | number | tr_session_stats - | downloadedBytes | number | tr_session_stats - | filesAdded | number | tr_session_stats - | sessionCount | number | tr_session_stats - | secondsActive | number | tr_session_stats - ---------------------------+-------------------------------+ - "current-stats" | object, containing: | - +------------------+------------+ - | uploadedBytes | number | tr_session_stats - | downloadedBytes | number | tr_session_stats - | filesAdded | number | tr_session_stats - | sessionCount | number | tr_session_stats - | secondsActive | number | tr_session_stats - -4.3. Blocklist - - Method name: "blocklist-update" - Request arguments: none - Response arguments: a number "blocklist-size" - -4.4. Port Checking - - This method tests to see if your incoming peer port is accessible - from the outside world. - - Method name: "port-test" - Request arguments: none - Response arguments: a bool, "port-is-open" - -4.5. Session shutdown - - This method tells the transmission session to shut down. - - Method name: "session-close" - Request arguments: none - Response arguments: none - -4.6. Queue Movement Requests - - Method name | libtransmission function - ---------------------+------------------------------------------------- - "queue-move-top" | tr_torrentQueueMoveTop() - "queue-move-up" | tr_torrentQueueMoveUp() - "queue-move-down" | tr_torrentQueueMoveDown() - "queue-move-bottom" | tr_torrentQueueMoveBottom() - - Request arguments: - - string | value type & description - ------------+---------------------------------------------------------- - "ids" | array torrent list, as described in 3.1. - - Response arguments: none - -4.7. Free Space - - This method tests how much free space is available in a - client-specified folder. - - Method name: "free-space" - - Request arguments: - - string | value type & description - ------------+---------------------------------------------------------- - "path" | string the directory to query - - Response arguments: - - string | value type & description - -------------+---------------------------------------------------------- - "path" | string same as the Request argument - "size-bytes" | number the size, in bytes, of the free space in that directory - "total_size" | number the total capacity, in bytes, of that directory - - -5.0. Protocol Versions - - This section lists the changes that have been made to the RPC protocol. - - There are two ways to check for API compatibility. Since most developers know - semver, session-get's "rpc-version-semver" is the recommended way. That value - is a semver-compatible string of the RPC protocol version number. - - Since Transmission predates the semver 1.0 spec, the previous scheme was for - the RPC version to be a whole number and to increment it whenever a change was - made. That is session-get's "rpc-version". "rpc-version-minimum" lists the - oldest version that is compatible with the current version; i.e. an app coded - to use `rpc-version-minimum` would still work on a Transmission release running - `rpc-version`. - - RPC | Sem | Tr. | Method | Description - Ver | Ver | Ver | (breaking changes | - | | | marked w/asterisk) | - ----+-------+------+----------------------+------------------------------- - 1 | 1.0.0 | 1.30 | n/a | Initial version - ----+-------+------+----------------------+------------------------------- - 2 | 1.1.0 | 1.40 | torrent-get | new arg "peers" - ----+-------+------+----------------------+------------------------------- - 3 | 1.2.0 | 1.41 | torrent-get | added "port" to "peers" - | | | torrent-get | new arg "downloaders" - | | | session-get | new arg "version" - | | | torrent-remove | new method - ----+-------+------+----------------------+------------------------------- - 4 | 1.3.0 | 1.50 | session-get | new arg "rpc-version" - | | | session-get | new arg "rpc-version-minimum" - | | | session-stats | added "cumulative-stats" - | | | session-stats | added "current-stats" - | | | torrent-get | new arg "downloadDir" - ----+-------+------+----------------------+------------------------------- - 5 | 2.0.0 | 1.60 | | new method "torrent-reannounce" - | | | | new method "blocklist-update" - | | | | new method "port-test" - | | | | - | | | session-get | new arg "alt-speed-begin" - | | | session-get | new arg "alt-speed-down" - | | | session-get | new arg "alt-speed-enabled" - | | | session-get | new arg "alt-speed-end" - | | | session-get | new arg "alt-speed-time-enabled" - | | | session-get | new arg "alt-speed-up" - | | | session-get | new arg "blocklist-enabled" - | | | session-get | new arg "blocklist-size" - | | | session-get | new arg "peer-limit-per-torrent" - | | | session-get | new arg "seedRatioLimit" - | | | session-get | new arg "seedRatioLimited" - | | | session-get * | renamed "pex-allowed" to "pex-enabled" - | | | session-get * | renamed "port" to "peer-port" - | | | session-get * | renamed "peer-limit" to "peer-limit-global" - | | | | - | | | torrent-add | new arg "files-unwanted" - | | | torrent-add | new arg "files-wanted" - | | | torrent-add | new arg "priority-high" - | | | torrent-add | new arg "priority-low" - | | | torrent-add | new arg "priority-normal" - | | | | - | | | torrent-set | new arg "bandwidthPriority" - | | | torrent-set | new arg "honorsSessionLimits" - | | | torrent-set | new arg "seedRatioLimit" - | | | torrent-set | new arg "seedRatioLimited" - | | | torrent-set * | renamed "speed-limit-down" to "downloadLimit" - | | | torrent-set * | renamed "speed-limit-down-enabled" to "downloadLimited" - | | | torrent-set * | renamed "speed-limit-up" to "uploadLimit" - | | | torrent-set * | renamed "speed-limit-up-enabled" to "uploadLimited" - | | | | - | | | torrent-get | new arg "bandwidthPriority" - | | | torrent-get | new arg "fileStats" - | | | torrent-get | new arg "honorsSessionLimits" - | | | torrent-get | new arg "percentDone" - | | | torrent-get | new arg "pieces" - | | | torrent-get | new arg "seedRatioLimit" - | | | torrent-get | new arg "seedRatioMode" - | | | torrent-get | new arg "torrentFile" - | | | torrent-get | new ids option "recently-active" - | | | torrent-get * | removed arg "downloadLimitMode" - | | | torrent-get * | removed arg "uploadLimitMode" - ----+-------+------+----------------------+------------------------------- - 6 | 2.1.0 | 1.70 | | new "method torrent-set-location" - ----+-------+------+----------------------+------------------------------- - 7 | 3.0.0 | 1.80 | torrent-get * | removed arg "announceResponse" - | | | torrent-get * | removed arg "announceURL" - | | | torrent-get * | removed arg "downloaders" - | | | torrent-get * | removed arg "lastAnnounceTime" - | | | torrent-get * | removed arg "lastScrapeTime" - | | | torrent-get * | removed arg "leechers" - | | | torrent-get * | removed arg "nextAnnounceTime" - | | | torrent-get * | removed arg "nextScrapeTime" - | | | torrent-get * | removed arg "scrapeResponse" - | | | torrent-get * | removed arg "scrapeURL" - | | | torrent-get * | removed arg "seeders" - | | | torrent-get * | removed arg "timesCompleted" - | | | torrent-get * | removed arg "swarmSpeed" - | | | torrent-get | new arg "magnetLink" - | | | torrent-get | new arg "metadataPercentComplete" - | | | torrent-get | new arg "trackerStats" - | | | session-set | new arg "incomplete-dir" - | | | session-set | new arg "incomplete-dir-enabled" - ----+-------+------+----------------------+------------------------------- - 8 | 3.1.0 | 1.90 | session-set | new arg "rename-partial-files" - | | | session-get | new arg "rename-partial-files" - | | | session-get | new arg "config-dir" - | | | torrent-add | new arg "bandwidthPriority" - | | | torrent-get | new trackerStats arg "lastAnnounceTimedOut" - ----+-------+------+----------------------+------------------------------- - 8 | 3.2.0 | 1.92 | torrent-get | new trackerStats arg "lastScrapeTimedOut" - ----+-------+------+----------------------+------------------------------- - 9 | 3.3.0 | 2.00 | session-set | new arg "start-added-torrents" - | | | session-set | new arg "trash-original-torrent-files" - | | | session-get | new arg "start-added-torrents" - | | | session-get | new arg "trash-original-torrent-files" - | | | torrent-get | new arg "isFinished" - ----+-------+------+----------------------+------------------------------- - 10 | 3.4.0 | 2.10 | session-get | new arg "cache-size-mb" - | | | torrent-set | new arg "trackerAdd" - | | | torrent-set | new arg "trackerRemove" - | | | torrent-set | new arg "trackerReplace" - | | | session-set | new arg "idle-seeding-limit" - | | | session-set | new arg "idle-seeding-limit-enabled" - | | | session-get | new arg "units" - | | | torrent-set | new arg "seedIdleLimit" - | | | torrent-set | new arg "seedIdleMode" - ----+-------+------+----------------------+------------------------------- - 11 | 3.5.0 | 2.12 | session-get | new arg "blocklist-url" - | | | session-set | new arg "blocklist-url" - ----+-------+------+----------------------+------------------------------- - 12 | 3.6.0 | | session-get | new arg "download-dir-free-space" - | | | session-close | new method - ----+-------+------+----------------------+------------------------------- - 13 | 4.0.0 | 2.30 | session-get | new arg "isUTP" to the "peers" list - | | | torrent-add | new arg "cookies" - | | | torrent-get * | removed arg "peersKnown" - ----+-------+------+----------------------+------------------------------- - 14 | 5.0.0 | 2.40 | torrent-get * | values of "status" field changed - | | | torrent-get | new arg "queuePosition" - | | | torrent-get | new arg "isStalled" - | | | torrent-get | new arg "fromLpd" in peersFrom - | | | torrent-set | new arg "queuePosition" - | | | session-set | new arg "download-queue-size" - | | | session-set | new arg "download-queue-enabled" - | | | session-set | new arg "seed-queue-size" - | | | session-set | new arg "seed-queue-enabled" - | | | session-set | new arg "queue-stalled-enabled" - | | | session-set | new arg "queue-stalled-minutes" - | | | | new method "queue-move-top" - | | | | new method "queue-move-up" - | | | | new method "queue-move-down" - | | | | new method "queue-move-bottom" - | | | | new method "torrent-start-now" - ----+-------+------+----------------------+------------------------------- - 15 | 5.1.0 | 2.80 | torrent-get | new arg "etaIdle" - | | | torrent-rename-path | new method - | | | free-space | new method - | | | torrent-add | new return arg "torrent-duplicate" - ----+-------+------+----------------------+------------------------------- - 16 | 5.2.0 | 3.00 | session-get | new request arg "fields" - | | | session-get | new arg "session-id" - | | | torrent-get | new arg "labels" - | | | torrent-set | new arg "labels" - | | | torrent-get | new arg "editDate" - | | | torrent-get | new request arg "format" - ----+-------+------+----------------------+------------------------------- - 17 | 5.3.0 | 3.xx | session-get | new arg "rpc-version-semver" - | | | session-get | new arg "script-torrent-added-enabled" - | | | session-get | new arg "script-torrent-added-filename" - | | | torrent-get | new arg "file-count" - | | | torrent-get | new arg "primary-mime-type" - | | | free-space | new return arg "total-capacity" - | | | | undocumented "/upload" endpoint removed - | | | torrent-add | new arg "labels" - - -5.1. Upcoming Breakage - - These features are deprecated: - - 1. session-get's 'download-dir-free-space' argument will be removed. - Its functionality has been superceded by the 'free-space' method. - - 2. HTTP POSTs to http://server:port/transmission/upload will fail. - This was an undocumented hack to allow web clients to add files without - client-side access to the file. This functionality is superceded by - using HTML5's FileReader object + the documented 'torrent-add' method. diff --git a/libtransmission/transmission.h b/libtransmission/transmission.h index 71cf035d1..70e56a505 100644 --- a/libtransmission/transmission.h +++ b/libtransmission/transmission.h @@ -314,7 +314,7 @@ bool tr_sessionIsIncompleteFileNamingEnabled(tr_session const* session); * @brief Set whether or not RPC calls are allowed in this session. * * @details If true, libtransmission will open a server socket to listen - * for incoming http RPC requests as described in docs/rpc-spec.txt. + * for incoming http RPC requests as described in extras/rpc-spec.md. * * This is intially set by tr_sessionInit() and can be * queried by tr_sessionIsRPCEnabled().