1.  Introduction

   This document describes a protocol for interacting with Vuze and Transmission
   sessions remotely.  Updated from 
   https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt to include
   Vuze additions.

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

   Reponses support three keys:

   (1) A required "result" string whose value MUST be "success" on success,
       or an error string on failure.
   (2) An optional "arguments" object of 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.

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
>>> BiglyBT
   "tagAdd"              | array      list of string (tag names) or number (tag uid) to add to torrent
   "tagRemove"           | array      list of string (tag names) or number (tag uid) to remove from torrent
<<< BiglyBT
   "trackerAdd"          | array      strings of announce URLs to add
   "trackerRemove"       | array      ids of trackers to remove
   "trackerReplace"      | array      pairs of <trackerId/new announce URLs>
   "uploadLimit"         | number     maximum upload speed (KBps)
   "uploadLimited"       | boolean    true if "uploadLimit" is honored
   
   >>> VUZE
   "name"                | string     new display name for the torrent
   "files"               | array of map
       key                  | value type & description
       ---------------------+-------------------------------------------------
       "index"              | index (position) of file in torrent (mandatory)
       "name"               | new name for file
   <<< VUZE

   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.
       
       >>> BiglyBT
       Essentially this saves sending the field keys over and over again, and
       is a similar concept to BiglyBT's mapPerFile=false.
 
       [ 
         // Row 0: keys
         [ field-key0, field-key1, ... ],
         // Row 1: First Torrent
         [ value for "field-key0", value for "field-key1", ... ],
         // Row 2: 2nd Torrent
         [ value for "field-key0", value for "field-key1", ... ],
         // Row X: Xth Torrent
         ...
       ]
       
       Note: for "files" and "fileStats", value will still be an array of map.
             These maps will still have their keys ("bytesCompleted", "name", etc)
             duplicated for every file, and every torrent.
             
             BiglyBT has "mapPerFile" instead of "format", but it only
             works for "files".  When set to false, "files" will be an array of
             arrays, and the keys will be in a field called "kileKeys" (not row 0)
             
             BiglyBT also has a "file-fields" parameter that you can set to
             limit the fields that "files" returns
       <<< BiglyBT

   (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
                               | The last time during this session that a rarely-changing field
                               | changed -- e.g. any tr_info field (trackers, filenames, name)
                               | or download directory. RPC clients can monitor this to know when
                               | to reload fields that rarely change.
   error                       | number                      | tr_stat
   errorString                 | string                      | tr_stat
   eta                         | number                      | tr_stat
   etaIdle                     | number                      | tr_stat
   files                       | array (see below)           | n/a
>>> BiglyBT
   file-fields                 | array of "files" fields to return in "files" map
                               | If missing, all files fields are returned 
                               | (when "files" is in the "fields" list)
   files-hc-<torrentid>        | array of string
                               | A hashcode for each file (length must be # of files in torrent)
                               | File will only be returned in "files" if the file has changed.
                               | (when "files" is in the "fields" list)
   file-indexes-<torrentid>    | array of number
                               | "files" result will only contain files at
                               | the indexes specified
                               | If missing, all files will be returned
                               | (when "files" is in the "fields" list)
<<< BiglyBT
   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                  | number                      | 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
>>> BiglyBT
   peer-fields                 | array of "peers" fields to return in "peers" map
                               | if missing, all peers fields are returned 
                               | (when "peers" is in the "fields" list)
<<< BiglyBT
   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
   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                      | tr_stat
>>> BiglyBT
   tag-uids                    | array of number. See "tags-get-list" method
<<< BiglyBT
   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
>>> BiglyBT
                      | index                   | number     | file #
                      |                                      | Useful if you requested a subset of files
                      | eta                     | number     | eta in seconds to file completion
                      | contentURL              | string     | Streaming URL
                      | fullPath                | string     | Absolute path to file
                      | hc                      | string     | hashcode for all fields requested.
                                                             | In future calls to torrent-get, adding a key "files-hc-<torrentid>"
                                                             | with a value of an array (length=# files in torrent). Each entry
                                                             | is a hc value. RPC will not return that file if nothing changed.
                      |--------------------------------------|
                      | You can also request fields from     |
                      | "fileStats".                         |
                      | "name" field is relative to          |
                      | "downloadDir", or absolute if file   |
                      | has been moved outside of path.      | 
<<< BiglyBT
   -------------------+--------------------------------------+
   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
>>> BiglyBT
                       Note: There is no "label" key, it's jsut an array of strings
<<< BiglyBT
   -------------------+--------------------------------------+
   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.     |
   -------------------+--------------------------------------+
   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
   "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)
>>> BiglyBT
   "vuze_tags"          | array       list of strings. Each string will be added 
                        |             as a tag.  If the tag doesn't exist yet, 
                        |             it will be created.
<<< BiglyBT

   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.
   <http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE>

   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 enabled
   "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
   "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)
                                    +--------------+--------+------------------+

   >>> BiglyBT
   "rpc-supports"                   | array of string | various features remote client supports
                                    |                 | "method:X" supports rpc method X
                                    |                 | "method:X" supports rpc method X
   "biglybt-version"
   "rpc-i2p-address"
   "rpc-tor-address"
   "az-content-port"
   "az-rpc-version"
   <<< BiglyBT

   "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


5.0.  Protocol Versions

  The following changes have been made to the RPC interface:

   RPC   | Release | Backwards |                      |
   Vers. | Version | Compat?   | Method               | Description
   ------+---------+-----------+----------------------+-------------------------------
   1     | 1.30    | n/a       | n/a                  | Initial version
   ------+---------+-----------+----------------------+-------------------------------
   2     | 1.34    | yes       | torrent-get          | new arg "peers"
   ------+---------+-----------+----------------------+-------------------------------
   3     | 1.41    | yes       | torrent-get          | added "port" to "peers"
         |         | yes       | torrent-get          | new arg "downloaders"
         |         | yes       | session-get          | new arg "version"
         |         | yes       | torrent-remove       | new method
   ------+---------+-----------+----------------------+-------------------------------
   4     | 1.50    | yes       | session-get          | new arg "rpc-version"
         |         | yes       | session-get          | new arg "rpc-version-minimum"
         |         | yes       | session-stats        | added "cumulative-stats"
         |         | yes       | session-stats        | added "current-stats"
         |         | yes       | torrent-get          | new arg "downloadDir"
   ------+---------+-----------+----------------------+-------------------------------
   5     | 1.60    | yes       |                      | new method "torrent-reannounce"
         |         | yes       |                      | new method "blocklist-update"
         |         | yes       |                      | new method "port-test"
         |         |           |                      |
         |         | yes       | session-get          | new arg "alt-speed-begin"
         |         | yes       | session-get          | new arg "alt-speed-down"
         |         | yes       | session-get          | new arg "alt-speed-enabled"
         |         | yes       | session-get          | new arg "alt-speed-end"
         |         | yes       | session-get          | new arg "alt-speed-time-enabled"
         |         | yes       | session-get          | new arg "alt-speed-up"
         |         | yes       | session-get          | new arg "blocklist-enabled"
         |         | yes       | session-get          | new arg "blocklist-size"
         |         | yes       | session-get          | new arg "peer-limit-per-torrent"
         |         | yes       | session-get          | new arg "seedRatioLimit"
         |         | yes       | session-get          | new arg "seedRatioLimited"
         |         |        NO | session-get          | renamed "pex-allowed" to "pex-enabled"
         |         |        NO | session-get          | renamed "port" to "peer-port"
         |         |        NO | session-get          | renamed "peer-limit" to "peer-limit-global"
         |         |           |                      |
         |         | yes       | torrent-add          | new arg "files-unwanted"
         |         | yes       | torrent-add          | new arg "files-wanted"
         |         | yes       | torrent-add          | new arg "priority-high"
         |         | yes       | torrent-add          | new arg "priority-low"
         |         | yes       | torrent-add          | new arg "priority-normal"
         |         |           |                      |
         |         | yes       | torrent-set          | new arg "bandwidthPriority"
         |         | yes       | torrent-set          | new arg "honorsSessionLimits"
         |         | yes       | torrent-set          | new arg "seedRatioLimit"
         |         | yes       | torrent-set          | new arg "seedRatioLimited"
         |         |        NO | torrent-set          | renamed "speed-limit-down" to "downloadLimit"
         |         |        NO | torrent-set          | renamed "speed-limit-down-enabled" to "downloadLimited"
         |         |        NO | torrent-set          | renamed "speed-limit-up" to "uploadLimit"
         |         |        NO | torrent-set          | renamed "speed-limit-up-enabled" to "uploadLimited"
         |         |           |                      |
         |         | yes       | torrent-get          | new arg "bandwidthPriority"
         |         | yes       | torrent-get          | new arg "fileStats"
         |         | yes       | torrent-get          | new arg "honorsSessionLimits"
         |         | yes       | torrent-get          | new arg "percentDone"
         |         | yes       | torrent-get          | new arg "pieces"
         |         | yes       | torrent-get          | new arg "seedRatioLimit"
         |         | yes       | torrent-get          | new arg "seedRatioMode"
         |         | yes       | torrent-get          | new arg "torrentFile"
         |         | yes       | torrent-get          | new ids option "recently-active"
         |         |        NO | torrent-get          | removed arg "downloadLimitMode"
         |         |        NO | torrent-get          | removed arg "uploadLimitMode"
   ------+---------+-----------+----------------------+-------------------------------
   6     | 1.70    | yes       |                      | new "method torrent-set-location"
   ------+---------+-----------+----------------------+-------------------------------
   7     | 1.80    |        NO | torrent-get          | removed arg "announceResponse"
         |         |        NO | torrent-get          | removed arg "announceURL"
         |         |        NO | torrent-get          | removed arg "downloaders"
         |         |        NO | torrent-get          | removed arg "lastAnnounceTime"
         |         |        NO | torrent-get          | removed arg "lastScrapeTime"
         |         |        NO | torrent-get          | removed arg "leechers"
         |         |        NO | torrent-get          | removed arg "nextAnnounceTime"
         |         |        NO | torrent-get          | removed arg "nextScrapeTime"
         |         |        NO | torrent-get          | removed arg "scrapeResponse"
         |         |        NO | torrent-get          | removed arg "scrapeURL"
         |         |        NO | torrent-get          | removed arg "seeders"
         |         |        NO | torrent-get          | removed arg "timesCompleted"
         |         |        NO | torrent-get          | removed arg "swarmSpeed"
         |         | yes       | torrent-get          | new arg "magnetLink"
         |         | yes       | torrent-get          | new arg "metadataPercentComplete"
         |         | yes       | torrent-get          | new arg "trackerStats"
         |         | yes       | session-set          | new arg "incomplete-dir"
         |         | yes       | session-set          | new arg "incomplete-dir-enabled"
   ------+---------+-----------+----------------------+-------------------------------
   8     | 1.90    | yes       | session-set          | new arg "rename-partial-files"
         |         | yes       | session-get          | new arg "rename-partial-files"
         |         | yes       | session-get          | new arg "config-dir"
         |         | yes       | torrent-add          | new arg "bandwidthPriority"
         |         | yes       | torrent-get          | new trackerStats arg "lastAnnounceTimedOut"
   ------+---------+-----------+----------------------+-------------------------------
   8     | 1.92    | yes       | torrent-get          | new trackerStats arg "lastScrapeTimedOut"
   ------+---------+-----------+----------------------+-------------------------------
   9     | 2.00    | yes       | session-set          | new arg "start-added-torrents"
         |         | yes       | session-set          | new arg "trash-original-torrent-files"
         |         | yes       | session-get          | new arg "start-added-torrents"
         |         | yes       | session-get          | new arg "trash-original-torrent-files"
         |         | yes       | torrent-get          | new arg "isFinished"
   ------+---------+-----------+----------------------+-------------------------------
   10    | 2.10    | yes       | session-get          | new arg "cache-size-mb"
         |         | yes       | torrent-set          | new arg "trackerAdd"
         |         | yes       | torrent-set          | new arg "trackerRemove"
         |         | yes       | torrent-set          | new arg "trackerReplace"
         |         | yes       | session-set          | new arg "idle-seeding-limit"
         |         | yes       | session-set          | new arg "idle-seeding-limit-enabled"
         |         | yes       | session-get          | new arg "units"
         |         | yes       | torrent-set          | new arg "seedIdleLimit"
         |         | yes       | torrent-set          | new arg "seedIdleMode"
   ------+---------+-----------+----------------------+-------------------------------
   11    | 2.12    | yes       | session-get          | new arg "blocklist-url"
         |         | yes       | session-set          | new arg "blocklist-url"
   ------+---------+-----------+----------------------+-------------------------------
   12    | 2.20    | yes       | session-get          | new arg "download-dir-free-space"
         |         | yes       | session-close        | new method
   ------+---------+-----------+----------------------+-------------------------------
   13    | 2.30    | yes       | session-get          | new arg "isUTP" to the "peers" list
         |         | yes       | torrent-add          | new arg "cookies"
         |         |        NO | torrent-get          | removed arg "peersKnown"
   ------+---------+-----------+----------------------+-------------------------------
   14    | 2.40    |        NO | torrent-get          | values of "status" field changed
         |         | yes       | torrent-get          | new arg "queuePosition"
         |         | yes       | torrent-get          | new arg "isStalled"
         |         | yes       | torrent-get          | new arg "fromLpd" in peersFrom
         |         | yes       | torrent-set          | new arg "queuePosition"
         |         | yes       | session-set          | new arg "download-queue-size"
         |         | yes       | session-set          | new arg "download-queue-enabled"
         |         | yes       | session-set          | new arg "seed-queue-size"
         |         | yes       | session-set          | new arg "seed-queue-enabled"
         |         | yes       | session-set          | new arg "queue-stalled-enabled"
         |         | yes       | session-set          | new arg "queue-stalled-minutes"
         |         | yes       |                      | new method "queue-move-top"
         |         | yes       |                      | new method "queue-move-up"
         |         | yes       |                      | new method "queue-move-down"
         |         | yes       |                      | new method "queue-move-bottom"
         |         | yes       |                      | new method "torrent-start-now"
   ------+---------+-----------+----------------------+-------------------------------
   15    | 2.80    | yes       | torrent-get          | new arg "etaIdle"
         |         | yes       | torrent-rename-path  | new method
         |         | yes       | free-space           | new method
         |         | yes       | torrent-add          | new return arg "torrent-duplicate"
   ------+---------+-----------+----------------------+-------------------------------
   16    | 3.00    | yes       | session-get          | new request arg "fields"
         |         | yes       | session-get          | new arg "session-id"
         |         | yes       | torrent-get          | new arg "labels"
         |         | yes       | torrent-set          | new arg "labels"
         |         | yes       | torrent-set          | new arg "editDate"
         |         | yes       | torrent-get          | new arg "format"


5.1.  Upcoming Breakage

   These features will be removed three months after 2.80's release:

   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.

VZ.1 Start Search

   Method name: "vuze-search-start"
   
   az-rpc-version: 1

   Request arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "expression"         | string         search term

   Response arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "sid"                | string         Search ID to be used for result lookup
   "engines"            | array of map   List of search engines available
       key                  | value type & description
       ---------------------+-------------------------------------------------
       "name"               | string     Name of search engine
       "id"                 | string     UID of search engine
       "favicon"            | string     URL to icon
       "dl_link_css"        | string     ?????
       "selected"           | string     { "no", "auto", "manual" }
       "source"             | string     { "unknown","vuze","local","rss","unused" }
       "type"               | depends    { "unknown","regexp","json", "plugin", number }
 
 VZ.2 Get Search Results
 
   Method name: "vuze-search-get-results"

   az-rpc-version: 1

   Request arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "sid"                | string      Search ID from vuze-search-start

   Response arguments:
   
   NOTE: numeric values are returned in strings

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "sid"                | string         Search ID to be used for result lookup
   "complete"           | boolean        Whether all engines have completed the search
                        |                Once true, you will not be able to request for this sid again
   "engines"            | map            List of search engines available
       key                  | value type & description
       ---------------------+-------------------------------------------------
       "id"                 | string        UID of search engine
       "error"              | string        If present, engine's error message
       "complete"           | boolean       Whether the search has completed for this engine
       "result"             | array of map  Search results
       key                  | value type & description
       ---------------------+-------------------------------------------------
       "d"                  | string    Publish Date in "<time> <units> ago" or "unknown"
       "ts"                 | string    Numeric Publish Date or "0" if unkown
       "c"                  | string    Category
       "n"                  | string    Name
       "s"                  | string    Numeric # of seeds; "-1" if unknown
       "p"                  | string    Numeric # of peers; "-1" if unknown
       "co"                 | string    Comments
       "l"                  | string    Download size, friendly format (ex "50 kB"), or "-1" if unknown
       "lb"                 | string    Numeric download size in bytes, or "0" if unkown
       "r"                  | string    Numeric search ranking value
       "ct"                 | string    Content Type
       "ac"                 | string    If present, numeric (float) accuracy, "0" to "1"
       "cdp"                | string    If present, URL to details page
       "dl"                 | string    If present, the download url
       "dbl"                | string    If present, the download button url
       "pl"                 | string    If present, the play url
       "v"                  | string    If present, the number of up votes
       "vd"                 | string    If present, the number of down votes
       "u"                  | string    If present, the UID (for subscriptions)
       "pr"                 | string    "1" for private, "0" for not
       "h"                  | string    If present, the torrent hash
       
VZ.3 Vuze Lifecycle

   Method name: "vuze-lifecycle"
    
   az-rpc-version: 1

   Request arguments: 

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "cmd"                | string       az-rpc-version 1: "status"
                        |              az-rpc-version 1: "close"
                        |              az-rpc-version 1: "restart"
                        |              az-rpc-version 1: "update-check"
                        |              az-rpc-version 1: "update-apply"

   Response arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------

VZ.4 Tags
 
 We support tag RPCs.

   Method name: "tags-get-list"

   Request arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "fields"             | array of string field names to return.  Optional
   "tags-hc"            | object       Optional. hashcode passed from last result

   Response arguments:
   
   key                  | value type & description
   ---------------------+-------------------------------------------------
   "tags-hc"            | object       hashcode to use when requesting again
   "tags"               | array of map.  Will not return if tags haven't changed from tags-hc
         key                  | value type & description
         ---------------------+-------------------------------------------------
         "name"               | string       Tag name
         "count"              | number       Number of torrents having this tag
         "type"               | number       Species of Tag
                              |                1: Category
                              |                2: Download State
                              |                3: Download Manual (User Tags)
                              |                4: Peer IP set
         "type-name"          | string       Things like "Category", but localized
         "category-type"      | number       Only if tag is a category
                              |                0: User
                              |                1: All
                              |                2: Uncategorized
         "uid"                | number       Unique id across tag types
         "id"                 | number       Id within this tag type  
         "color"              | string       #rrggbb color hint
         "canBePublic"        | boolean      true if tag can be set to public
         "public"             | boolean      true if tag is shared
         "visible"            | boolean      not useful
         "group"              | string       User defined group name that this tag belongs to
         "auto_add"           | boolean      Tag is auto-added based on rules
         "auto_remove"        | boolean      Tag is auto-removed based on rules
         "constraint"         | map          Constraint logic
                key        | value type & description
                -----------+---------------------------------------------------
                "text"     | string     See https://github.com/BiglySoftware/BiglyBT/wiki/Tags#Constraints
                "mode"     | string     "am=0;" CM_ADD_REMOVE
                           |            "am=1;" CM_ADD_ONLY
                           |            "am=2;" CM_REMOVE_ONLY
                           |            "am=3;" CM_NEW_DLS
                "enabled"  | boolean    If the logic is enabled
                "error"    | string     If present, describes an error in the contraint logic
          "file-location"     | map          File Location settings.  All, some, or no keys may be present
                key                         | value type & description
                ----------------------------+---------------------------------------------------
                "initial-save-folder"       | string
                "initial-save-folder-flags" | number bitfield    0x0 None; 0x1 Data; 0x2 Torrent
                "move-on-complete"          | string
                "move-on-complete-flags"    | number bitfield    0x0 None; 0x1 Data; 0x2 Torrent
                "copy-on-complete"          |
                "copy-on-complete-flags"    | number bitfield    0x0 None; 0x1 Data; 0x2 Torrent
                "move-on-remove"            |
                "move-on-remove-flags"      | number bitfield    0x0 None; 0x1 Data; 0x2 Torrent
          "limit"             | map          Limits on taggables
                key                 | value type & description
                --------------------+---------------------------------------------------
                "max-taggables"     | number  Limit the # of taggables that can be in this tag
                "removal-strategy"  | number  0=None
                                    |         1=Archive
                                    |         2=Remove from Library
                                    |         3=Delete from device
                                    |         4=Move to old tag (tag name + "_old" or "_Old")
                "ordering"          | number  0=Date Added to Client
                                    |         1=Date Added to Tag
          "transfer"          | map          Tag Transfer Settings.  All, some, or no keys may be present
                key                           | value type & description
                ------------------------------+---------------------------------------------------
                "download-limit"              | number   Limit download rate in bytes/sec
                "upload-limit"                | number   Limit upload rate in bytes/sec
                "current-download-rate"       | number   Current download rate in bytes/sec
                "current-upload-rate"         | number   Current upload rate in bytes/sec
                "download-session"            | number   bytes downloaded this session
                "upload-session"              | number   bytes uploaded this session
                "download-total"              | number   total bytes downloaded by this tag
                "upload-total"                | number   total bytes uploaded by this tag
                "upload-priority"             | number   0=normal priority; 1=higher priority
                "min-sr"                      | number   Min. Share Ratio * 1000
                "max-sr"                      | number   Max. Share Ratio * 1000
                "max-sr-action"               | number   0=Queue
                                              |          1=Pause
                                              |          2=Stop
                                              |          3=Archive
                                              |          4=Remove from Library
                                              |          5=Delete from Device 
                "max-aggregate-sr"            | number   Max. Aggregate Share Ratio * 1000
                "max-aggregate-sr-action"     | number   What to do when max is hit
                                              |          1=Pause
                                              |          2=Stop
                "max-aggregate-sr-prioritize" | boolean  Aggregate has Priority
                "first-priority-seeding"      | boolean  Set torrent 1st Priority Seeding


   Method name: "tags-add"
   
   key                  | value type & description
   ---------------------+-------------------------------------------------
   "name"               | string     Tag name
   fields               | See tags-set for tag fields you can set

   Response arguments:
   
   Returns all keys in "tags" key in "tags-get-list" (For example, "count" key
   be available at the root of the response)


   Method name: "tags-set"
   
   key                  | value type & description
   ---------------------+-------------------------------------------------
   "uid"                | number     Tag UID.  Optional if "name" key is set to
                        |            existing tag name
   "color"              | \
   "constraint"         |  |
   "group"              |  |- See types and descriptions in "tags-get-list"
   "name"               |  |
   "public"             | /

   Returns all keys in "tags" key in "tags-get-list" (For example, "count" key
   will be available at the root of the response)


   Method name: "tags-lookup-start"

   Request arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "ids"                | array      torrent list, as described in 3.1

   Response arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "id"                 | string       Tag Search ID to be used for result lookup


   Method name: "tags-lookup-get-results"

   Request arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "id"                 | string       Tag Search ID from tags-lookup-start

   Response arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "id"                 | string       Tag Search ID to be used for result lookup
   "torrents"           | array of map
       key                  | value type & description
       ---------------------+-------------------------------------------------
       "hashString"         | Torrent hash
       "tags"               | array of string tag names


 TODO: Document
 
 VZ.5 Hash Codes
 
 We use hascodes for lists and maps to reduce network traffic
 TODO: Document
 
 
 VZ.6 Internationalization
 
   Method name: "i18n-get-text"
   
   az-rpc-version: 8

   Request arguments:

   key                  | value type & description
   ---------------------+-------------------------------------------------
   "id"                 | string or array of string. See our MessageBundle
                        | for keys. Keys don't often change, but having a
                        | unit test for any keys you use is recommended.

   Response arguments:
   
   key                  | value type & description
   ---------------------+-------------------------------------------------
   <id>                 | string   Text associated with the id, in the current 
                        |          locale, or english if locale is missing id.
                        |          If id doesn't exist, it will not be returned.