source: trunk/extras/rpc-spec.txt

Last change on this file was 14463, checked in by mikedld, 16 months ago

Fix "magnetLink" field type in RPC spec (reported by r04r)

File size: 43.7 KB
Line 
11.  Introduction
2
3   This document describes a protocol for interacting with Transmission
4   sessions remotely.
5
61.1  Terminology
7
8   The JSON terminology in RFC 4627 is used.
9
10   JSON is fairly common now, but for the benefit of
11   torrent developers familiar with benc:
12   a JSON array is equivalent to a benc list,
13   a JSON object is equivalent to a benc dictionary,
14   and a JSON object's keys are the dictionary's string keys.
15
161.2  Resources
17
18   The command-line utility "transmission-remote" uses this RPC API.
19   Several developers have reported using its --debug JSON output as
20   a reference when developing/debugging their own code.
21   
222.  Message Format
23
24   Messages are formatted as objects.  There are two types:
25   requests (described in 2.1) and responses (described in 2.2).
26
27   All text MUST be UTF-8 encoded.
28
292.1.  Requests
30
31   Requests support three keys:
32
33   (1) A required "method" string telling the name of the method to invoke
34   (2) An optional "arguments" object of key/value pairs
35   (3) An optional "tag" number used by clients to track responses.
36       If provided by a request, the response MUST include the same tag.
37
382.2.  Responses
39
40   Reponses support three keys:
41
42   (1) A required "result" string whose value MUST be "success" on success,
43       or an error string on failure.
44   (2) An optional "arguments" object of key/value pairs
45   (3) An optional "tag" number as described in 2.1.
46
472.3.  Transport Mechanism
48
49   HTTP POSTing a JSON-encoded request is the preferred way of communicating
50   with a Transmission RPC server.  The current Transmission implementation
51   has the default URL as http://host:9091/transmission/rpc.  Clients
52   may use this as a default, but should allow the URL to be reconfigured,
53   since the port and path may be changed to allow mapping and/or multiple
54   daemons to run on a single server.
55
562.3.1.  CSRF Protection
57
58   Most Transmission RPC servers require a X-Transmission-Session-Id
59   header to be sent with requests, to prevent CSRF attacks.
60
61   When your request has the wrong id -- such as when you send your first
62   request, or when the server expires the CSRF token -- the
63   Transmission RPC server will return an HTTP 409 error with the
64   right X-Transmission-Session-Id in its own headers.
65
66   So, the correct way to handle a 409 response is to update your
67   X-Transmission-Session-Id and to resend the previous request.
68
693.  Torrent Requests
70
713.1.  Torrent Action Requests
72
73   Method name          | libtransmission function
74   ---------------------+-------------------------------------------------
75   "torrent-start"      | tr_torrentStart
76   "torrent-start-now"  | tr_torrentStartNow
77   "torrent-stop"       | tr_torrentStop
78   "torrent-verify"     | tr_torrentVerify
79   "torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers")
80
81   Request arguments: "ids", which specifies which torrents to use.
82                  All torrents are used if the "ids" argument is omitted.
83                  "ids" should be one of the following:
84                  (1) an integer referring to a torrent id
85                  (2) a list of torrent id numbers, sha1 hash strings, or both
86                  (3) a string, "recently-active", for recently-active torrents
87
88   Response arguments: none
89
903.2.  Torrent Mutators
91
92   Method name: "torrent-set"
93
94   Request arguments:
95
96   string                | value type & description
97   ----------------------+-------------------------------------------------
98   "bandwidthPriority"   | number     this torrent's bandwidth tr_priority_t
99   "downloadLimit"       | number     maximum download speed (KBps)
100   "downloadLimited"     | boolean    true if "downloadLimit" is honored
101   "files-wanted"        | array      indices of file(s) to download
102   "files-unwanted"      | array      indices of file(s) to not download
103   "honorsSessionLimits" | boolean    true if session upload limits are honored
104   "ids"                 | array      torrent list, as described in 3.1
105   "location"            | string     new location of the torrent's content
106   "peer-limit"          | number     maximum number of peers
107   "priority-high"       | array      indices of high-priority file(s)
108   "priority-low"        | array      indices of low-priority file(s)
109   "priority-normal"     | array      indices of normal-priority file(s)
110   "queuePosition"       | number     position of this torrent in its queue [0...n)
111   "seedIdleLimit"       | number     torrent-level number of minutes of seeding inactivity
112   "seedIdleMode"        | number     which seeding inactivity to use.  See tr_idlelimit
113   "seedRatioLimit"      | double     torrent-level seeding ratio
114   "seedRatioMode"       | number     which ratio to use.  See tr_ratiolimit
115   "trackerAdd"          | array      strings of announce URLs to add
116   "trackerRemove"       | array      ids of trackers to remove
117   "trackerReplace"      | array      pairs of <trackerId/new announce URLs>
118   "uploadLimit"         | number     maximum upload speed (KBps)
119   "uploadLimited"       | boolean    true if "uploadLimit" is honored
120
121   Just as an empty "ids" value is shorthand for "all ids", using an empty array
122   for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
123   "priority-normal" is shorthand for saying "all files".
124
125   Response arguments: none
126
1273.3.  Torrent Accessors
128
129   Method name: "torrent-get".
130
131   Request arguments:
132
133   (1) An optional "ids" array as described in 3.1.
134   (2) A required "fields" array of keys. (see list below)
135
136   Response arguments:
137
138   (1) A "torrents" array of objects, each of which contains
139       the key/value pairs matching the request's "fields" argument.
140   (2) If the request's "ids" field was "recently-active",
141       a "removed" array of torrent-id numbers of recently-removed
142       torrents.
143
144   Note: For more information on what these fields mean, see the comments
145   in libtransmission/transmission.h.  The "source" column here
146   corresponds to the data structure there.
147
148   key                         | type                        | source
149   ----------------------------+-----------------------------+---------
150   activityDate                | number                      | tr_stat
151   addedDate                   | number                      | tr_stat
152   bandwidthPriority           | number                      | tr_priority_t
153   comment                     | string                      | tr_info
154   corruptEver                 | number                      | tr_stat
155   creator                     | string                      | tr_info
156   dateCreated                 | number                      | tr_info
157   desiredAvailable            | number                      | tr_stat
158   doneDate                    | number                      | tr_stat
159   downloadDir                 | string                      | tr_torrent
160   downloadedEver              | number                      | tr_stat
161   downloadLimit               | number                      | tr_torrent
162   downloadLimited             | boolean                     | tr_torrent
163   error                       | number                      | tr_stat
164   errorString                 | string                      | tr_stat
165   eta                         | number                      | tr_stat
166   etaIdle                     | number                      | tr_stat
167   files                       | array (see below)           | n/a
168   fileStats                   | array (see below)           | n/a
169   hashString                  | string                      | tr_info
170   haveUnchecked               | number                      | tr_stat
171   haveValid                   | number                      | tr_stat
172   honorsSessionLimits         | boolean                     | tr_torrent
173   id                          | number                      | tr_torrent
174   isFinished                  | boolean                     | tr_stat
175   isPrivate                   | boolean                     | tr_torrent
176   isStalled                   | boolean                     | tr_stat
177   leftUntilDone               | number                      | tr_stat
178   magnetLink                  | string                      | n/a
179   manualAnnounceTime          | number                      | tr_stat
180   maxConnectedPeers           | number                      | tr_torrent
181   metadataPercentComplete     | double                      | tr_stat
182   name                        | string                      | tr_info
183   peer-limit                  | number                      | tr_torrent
184   peers                       | array (see below)           | n/a
185   peersConnected              | number                      | tr_stat
186   peersFrom                   | object (see below)          | n/a
187   peersGettingFromUs          | number                      | tr_stat
188   peersSendingToUs            | number                      | tr_stat
189   percentDone                 | double                      | tr_stat
190   pieces                      | string (see below)          | tr_torrent
191   pieceCount                  | number                      | tr_info
192   pieceSize                   | number                      | tr_info
193   priorities                  | array (see below)           | n/a
194   queuePosition               | number                      | tr_stat
195   rateDownload (B/s)          | number                      | tr_stat
196   rateUpload (B/s)            | number                      | tr_stat
197   recheckProgress             | double                      | tr_stat
198   secondsDownloading          | number                      | tr_stat
199   secondsSeeding              | number                      | tr_stat
200   seedIdleLimit               | number                      | tr_torrent
201   seedIdleMode                | number                      | tr_inactvelimit
202   seedRatioLimit              | double                      | tr_torrent
203   seedRatioMode               | number                      | tr_ratiolimit
204   sizeWhenDone                | number                      | tr_stat
205   startDate                   | number                      | tr_stat
206   status                      | number                      | tr_stat
207   trackers                    | array (see below)           | n/a
208   trackerStats                | array (see below)           | n/a
209   totalSize                   | number                      | tr_info
210   torrentFile                 | string                      | tr_info
211   uploadedEver                | number                      | tr_stat
212   uploadLimit                 | number                      | tr_torrent
213   uploadLimited               | boolean                     | tr_torrent
214   uploadRatio                 | double                      | tr_stat
215   wanted                      | array (see below)           | n/a
216   webseeds                    | array (see below)           | n/a
217   webseedsSendingToUs         | number                      | tr_stat
218                               |                             |
219                               |                             |
220   -------------------+--------+-----------------------------+
221   files              | array of objects, each containing:   |
222                      +-------------------------+------------+
223                      | bytesCompleted          | number     | tr_torrent
224                      | length                  | number     | tr_info
225                      | name                    | string     | tr_info
226   -------------------+--------------------------------------+
227   fileStats          | a file's non-constant properties.    |
228                      | array of tr_info.filecount objects,  |
229                      | each containing:                     |
230                      +-------------------------+------------+
231                      | bytesCompleted          | number     | tr_torrent
232                      | wanted                  | boolean    | tr_info
233                      | priority                | number     | tr_info
234   -------------------+--------------------------------------+
235   peers              | array of objects, each containing:   |
236                      +-------------------------+------------+
237                      | address                 | string     | tr_peer_stat
238                      | clientName              | string     | tr_peer_stat
239                      | clientIsChoked          | boolean    | tr_peer_stat
240                      | clientIsInterested      | boolean    | tr_peer_stat
241                      | flagStr                 | string     | tr_peer_stat
242                      | isDownloadingFrom       | boolean    | tr_peer_stat
243                      | isEncrypted             | boolean    | tr_peer_stat
244                      | isIncoming              | boolean    | tr_peer_stat
245                      | isUploadingTo           | boolean    | tr_peer_stat
246                      | isUTP                   | boolean    | tr_peer_stat
247                      | peerIsChoked            | boolean    | tr_peer_stat
248                      | peerIsInterested        | boolean    | tr_peer_stat
249                      | port                    | number     | tr_peer_stat
250                      | progress                | double     | tr_peer_stat
251                      | rateToClient (B/s)      | number     | tr_peer_stat
252                      | rateToPeer (B/s)        | number     | tr_peer_stat
253   -------------------+--------------------------------------+
254   peersFrom          | an object containing:                |
255                      +-------------------------+------------+
256                      | fromCache               | number     | tr_stat
257                      | fromDht                 | number     | tr_stat
258                      | fromIncoming            | number     | tr_stat
259                      | fromLpd                 | number     | tr_stat
260                      | fromLtep                | number     | tr_stat
261                      | fromPex                 | number     | tr_stat
262                      | fromTracker             | number     | tr_stat
263   -------------------+--------------------------------------+
264   pieces             | A bitfield holding pieceCount flags  | tr_torrent
265                      | which are set to 'true' if we have   |
266                      | the piece matching that position.    |
267                      | JSON doesn't allow raw binary data,  |
268                      | so this is a base64-encoded string.  |
269   -------------------+--------------------------------------+
270   priorities         | an array of tr_info.filecount        | tr_info
271                      | numbers. each is the tr_priority_t   |
272                      | mode for the corresponding file.     |
273   -------------------+--------------------------------------+
274   trackers           | array of objects, each containing:   |
275                      +-------------------------+------------+
276                      | announce                | string     | tr_tracker_info
277                      | id                      | number     | tr_tracker_info
278                      | scrape                  | string     | tr_tracker_info
279                      | tier                    | number     | tr_tracker_info
280   -------------------+--------------------------------------+
281   trackerStats       | array of objects, each containing:   |
282                      +-------------------------+------------+
283                      | announce                | string     | tr_tracker_stat
284                      | announceState           | number     | tr_tracker_stat
285                      | downloadCount           | number     | tr_tracker_stat
286                      | hasAnnounced            | boolean    | tr_tracker_stat
287                      | hasScraped              | boolean    | tr_tracker_stat
288                      | host                    | string     | tr_tracker_stat
289                      | id                      | number     | tr_tracker_stat
290                      | isBackup                | boolean    | tr_tracker_stat
291                      | lastAnnouncePeerCount   | number     | tr_tracker_stat
292                      | lastAnnounceResult      | string     | tr_tracker_stat
293                      | lastAnnounceStartTime   | number     | tr_tracker_stat
294                      | lastAnnounceSucceeded   | boolean    | tr_tracker_stat
295                      | lastAnnounceTime        | number     | tr_tracker_stat
296                      | lastAnnounceTimedOut    | boolean    | tr_tracker_stat
297                      | lastScrapeResult        | string     | tr_tracker_stat
298                      | lastScrapeStartTime     | number     | tr_tracker_stat
299                      | lastScrapeSucceeded     | boolean    | tr_tracker_stat
300                      | lastScrapeTime          | number     | tr_tracker_stat
301                      | lastScrapeTimedOut      | boolean    | tr_tracker_stat
302                      | leecherCount            | number     | tr_tracker_stat
303                      | nextAnnounceTime        | number     | tr_tracker_stat
304                      | nextScrapeTime          | number     | tr_tracker_stat
305                      | scrape                  | string     | tr_tracker_stat
306                      | scrapeState             | number     | tr_tracker_stat
307                      | seederCount             | number     | tr_tracker_stat
308                      | tier                    | number     | tr_tracker_stat
309   -------------------+-------------------------+------------+
310   wanted             | an array of tr_info.fileCount        | tr_info
311                      | 'booleans' true if the corresponding |
312                      | file is to be downloaded.            |
313   -------------------+--------------------------------------+
314   webseeds           | an array of strings:                 |
315                      +-------------------------+------------+
316                      | webseed                 | string     | tr_info
317                      +-------------------------+------------+
318
319   Example:
320
321   Say we want to get the name and total size of torrents #7 and #10.
322
323   Request:
324
325      {
326         "arguments": {
327             "fields": [ "id", "name", "totalSize" ],
328             "ids": [ 7, 10 ]
329         },
330         "method": "torrent-get",
331         "tag": 39693
332      }
333
334
335   Response:
336
337      {
338         "arguments": {
339            "torrents": [
340               {
341                   "id": 10,
342                   "name": "Fedora x86_64 DVD",
343                   "totalSize": 34983493932,
344               },
345               {
346                   "id": 7,
347                   "name": "Ubuntu x86_64 DVD",
348                   "totalSize", 9923890123,
349               }
350            ]
351         },
352         "result": "success",
353         "tag": 39693
354      }
355
3563.4.  Adding a Torrent
357
358   Method name: "torrent-add"
359
360   Request arguments:
361
362   key                  | value type & description
363   ---------------------+-------------------------------------------------
364   "cookies"            | string      pointer to a string of one or more cookies.
365   "download-dir"       | string      path to download the torrent to
366   "filename"           | string      filename or URL of the .torrent file
367   "metainfo"           | string      base64-encoded .torrent content
368   "paused"             | boolean     if true, don't start the torrent
369   "peer-limit"         | number      maximum number of peers
370   "bandwidthPriority"  | number      torrent's bandwidth tr_priority_t
371   "files-wanted"       | array       indices of file(s) to download
372   "files-unwanted"     | array       indices of file(s) to not download
373   "priority-high"      | array       indices of high-priority file(s)
374   "priority-low"       | array       indices of low-priority file(s)
375   "priority-normal"    | array       indices of normal-priority file(s)
376
377   Either "filename" OR "metainfo" MUST be included.
378   All other arguments are optional.
379
380   The format of the "cookies" should be NAME=CONTENTS, where NAME is the
381   cookie name and CONTENTS is what the cookie should contain.
382   Set multiple cookies like this: "name1=content1; name2=content2;" etc.
383   <http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE>
384
385   Response arguments: On success, a "torrent-added" object in the
386                       form of one of 3.3's tr_info objects with the
387                       fields for id, name, and hashString.
388
389                       On failure due to a duplicate torrent existing,
390                       a "torrent-duplicate" object in the same form.
391
3923.5.  Removing a Torrent
393
394   Method name: "torrent-remove"
395
396   Request arguments:
397
398   string                     | value type & description
399   ---------------------------+-------------------------------------------------
400   "ids"                      | array      torrent list, as described in 3.1
401   "delete-local-data"        | boolean    delete local data. (default: false)
402
403   Response arguments: none
404
405
4063.6.  Moving a Torrent
407
408   Method name: "torrent-set-location"
409
410   Request arguments:
411
412   string                           | value type & description
413   ---------------------------------+-------------------------------------------------
414   "ids"                            | array      torrent list, as described in 3.1
415   "location"                       | string     the new torrent location
416   "move"                           | boolean    if true, move from previous location.
417                                    |            otherwise, search "location" for files
418                                    |            (default: false)
419
420   Response arguments: none
421
422
4233.7.  Renaming a Torrent's Path
424
425   Method name: "torrent-rename-path"
426
427   For more information on the use of this function, see the transmission.h
428   documentation of tr_torrentRenamePath(). In particular, note that if this
429   call succeeds you'll want to update the torrent's "files" and "name" field
430   with torrent-get.
431
432   Request arguments:
433
434   string                           | value type & description
435   ---------------------------------+-------------------------------------------------
436   "ids"                            | array      the torrent torrent list, as described in 3.1
437                                    |            (must only be 1 torrent)
438   "path"                           | string     the path to the file or folder that will be renamed
439   "name"                           | string     the file or folder's new name
440
441   Response arguments: "path", "name", and "id", holding the torrent ID integer
442
443
4444.   Session Requests
445
4464.1.  Session Arguments
447
448   string                           | value type | description
449   ---------------------------------+------------+-------------------------------------
450   "alt-speed-down"                 | number     | max global download speed (KBps)
451   "alt-speed-enabled"              | boolean    | true means use the alt speeds
452   "alt-speed-time-begin"           | number     | when to turn on alt speeds (units: minutes after midnight)
453   "alt-speed-time-enabled"         | boolean    | true means the scheduled on/off times are used
454   "alt-speed-time-end"             | number     | when to turn off alt speeds (units: same)
455   "alt-speed-time-day"             | number     | what day(s) to turn on alt speeds (look at tr_sched_day)
456   "alt-speed-up"                   | number     | max global upload speed (KBps)
457   "blocklist-url"                  | string     | location of the blocklist to use for "blocklist-update"
458   "blocklist-enabled"              | boolean    | true means enabled
459   "blocklist-size"                 | number     | number of rules in the blocklist
460   "cache-size-mb"                  | number     | maximum size of the disk cache (MB)
461   "config-dir"                     | string     | location of transmission's configuration directory
462   "download-dir"                   | string     | default path to download torrents
463   "download-queue-size"            | number     | max number of torrents to download at once (see download-queue-enabled)
464   "download-queue-enabled"         | boolean    | if true, limit how many torrents can be downloaded at once
465   "dht-enabled"                    | boolean    | true means allow dht in public torrents
466   "encryption"                     | string     | "required", "preferred", "tolerated"
467   "idle-seeding-limit"             | number     | torrents we're seeding will be stopped if they're idle for this long
468   "idle-seeding-limit-enabled"     | boolean    | true if the seeding inactivity limit is honored by default
469   "incomplete-dir"                 | string     | path for incomplete torrents, when enabled
470   "incomplete-dir-enabled"         | boolean    | true means keep torrents in incomplete-dir until done
471   "lpd-enabled"                    | boolean    | true means allow Local Peer Discovery in public torrents
472   "peer-limit-global"              | number     | maximum global number of peers
473   "peer-limit-per-torrent"         | number     | maximum global number of peers
474   "pex-enabled"                    | boolean    | true means allow pex in public torrents
475   "peer-port"                      | number     | port number
476   "peer-port-random-on-start"      | boolean    | true means pick a random peer port on launch
477   "port-forwarding-enabled"        | boolean    | true means enabled
478   "queue-stalled-enabled"          | boolean    | whether or not to consider idle torrents as stalled
479   "queue-stalled-minutes"          | number     | torrents that are idle for N minuets aren't counted toward seed-queue-size or download-queue-size
480   "rename-partial-files"           | boolean    | true means append ".part" to incomplete files
481   "rpc-version"                    | number     | the current RPC API version
482   "rpc-version-minimum"            | number     | the minimum RPC API version supported
483   "script-torrent-done-filename"   | string     | filename of the script to run
484   "script-torrent-done-enabled"    | boolean    | whether or not to call the "done" script
485   "seedRatioLimit"                 | double     | the default seed ratio for torrents to use
486   "seedRatioLimited"               | boolean    | true if seedRatioLimit is honored by default
487   "seed-queue-size"                | number     | max number of torrents to uploaded at once (see seed-queue-enabled)
488   "seed-queue-enabled"             | boolean    | if true, limit how many torrents can be uploaded at once
489   "speed-limit-down"               | number     | max global download speed (KBps)
490   "speed-limit-down-enabled"       | boolean    | true means enabled
491   "speed-limit-up"                 | number     | max global upload speed (KBps)
492   "speed-limit-up-enabled"         | boolean    | true means enabled
493   "start-added-torrents"           | boolean    | true means added torrents will be started right away
494   "trash-original-torrent-files"   | boolean    | true means the .torrent file of added torrents will be deleted
495   "units"                          | object     | see below
496   "utp-enabled"                    | boolean    | true means allow utp
497   "version"                        | string     | long version string "$version ($revision)"
498   ---------------------------------+------------+-----------------------------+
499   units                            | object containing:                       |
500                                    +--------------+--------+------------------+
501                                    | speed-units  | array  | 4 strings: KB/s, MB/s, GB/s, TB/s
502                                    | speed-bytes  | number | number of bytes in a KB (1000 for kB; 1024 for KiB)
503                                    | size-units   | array  | 4 strings: KB/s, MB/s, GB/s, TB/s
504                                    | size-bytes   | number | number of bytes in a KB (1000 for kB; 1024 for KiB)
505                                    | memory-units | array  | 4 strings: KB/s, MB/s, GB/s, TB/s
506                                    | memory-bytes | number | number of bytes in a KB (1000 for kB; 1024 for KiB)
507                                    +--------------+--------+------------------+
508
509   "rpc-version" indicates the RPC interface version supported by the RPC server.
510   It is incremented when a new version of Transmission changes the RPC interface.
511
512   "rpc-version-minimum" indicates the oldest API supported by the RPC server.
513   It is changes when a new version of Transmission changes the RPC interface
514   in a way that is not backwards compatible.  There are no plans for this
515   to be common behavior.
516
5174.1.1.  Mutators
518
519   Method name: "session-set"
520   Request arguments: one or more of 4.1's arguments, except: "blocklist-size",
521                      "config-dir", "rpc-version", "rpc-version-minimum", and
522                      "version"
523   Response arguments: none
524
5254.1.2.  Accessors
526
527   Method name: "session-get"
528   Request arguments: none
529   Response arguments: all of 4.1's arguments
530
5314.2.  Session Statistics
532
533   Method name: "session-stats"
534
535   Request arguments: none
536
537   Response arguments:
538
539   string                     | value type
540   ---------------------------+-------------------------------------------------
541   "activeTorrentCount"       | number
542   "downloadSpeed"            | number
543   "pausedTorrentCount"       | number
544   "torrentCount"             | number
545   "uploadSpeed"              | number
546   ---------------------------+-------------------------------+
547   "cumulative-stats"         | object, containing:           |
548                              +------------------+------------+
549                              | uploadedBytes    | number     | tr_session_stats
550                              | downloadedBytes  | number     | tr_session_stats
551                              | filesAdded       | number     | tr_session_stats
552                              | sessionCount     | number     | tr_session_stats
553                              | secondsActive    | number     | tr_session_stats
554   ---------------------------+-------------------------------+
555   "current-stats"            | object, containing:           |
556                              +------------------+------------+
557                              | uploadedBytes    | number     | tr_session_stats
558                              | downloadedBytes  | number     | tr_session_stats
559                              | filesAdded       | number     | tr_session_stats
560                              | sessionCount     | number     | tr_session_stats
561                              | secondsActive    | number     | tr_session_stats
562
5634.3.  Blocklist
564
565   Method name: "blocklist-update"
566   Request arguments: none
567   Response arguments: a number "blocklist-size"
568
5694.4.  Port Checking
570
571   This method tests to see if your incoming peer port is accessible
572   from the outside world.
573
574   Method name: "port-test"
575   Request arguments: none
576   Response arguments: a bool, "port-is-open"
577
5784.5.  Session shutdown
579
580   This method tells the transmission session to shut down.
581
582   Method name: "session-close"
583   Request arguments: none
584   Response arguments: none
585
5864.6.  Queue Movement Requests
587
588   Method name          | libtransmission function
589   ---------------------+-------------------------------------------------
590   "queue-move-top"     | tr_torrentQueueMoveTop()
591   "queue-move-up"      | tr_torrentQueueMoveUp()
592   "queue-move-down"    | tr_torrentQueueMoveDown()
593   "queue-move-bottom"  | tr_torrentQueueMoveBottom()
594
595   Request arguments:
596
597   string      | value type & description
598   ------------+----------------------------------------------------------
599   "ids"       | array   torrent list, as described in 3.1.
600
601   Response arguments: none
602
6034.7.  Free Space
604
605   This method tests how much free space is available in a
606   client-specified folder.
607
608   Method name: "free-space"
609
610   Request arguments:
611
612   string      | value type & description
613   ------------+----------------------------------------------------------
614   "path"      | string  the directory to query
615
616   Response arguments:
617
618   string      | value type & description
619   ------------+----------------------------------------------------------
620   "path"      | string  same as the Request argument
621   "size-bytes"| number  the size, in bytes, of the free space in that directory
622
623
6245.0.  Protocol Versions
625
626  The following changes have been made to the RPC interface:
627
628   RPC   | Release | Backwards |                      |
629   Vers. | Version | Compat?   | Method               | Description
630   ------+---------+-----------+----------------------+-------------------------------
631   1     | 1.30    | n/a       | n/a                  | Initial version
632   ------+---------+-----------+----------------------+-------------------------------
633   2     | 1.34    | yes       | torrent-get          | new arg "peers"
634   ------+---------+-----------+----------------------+-------------------------------
635   3     | 1.41    | yes       | torrent-get          | added "port" to "peers"
636         |         | yes       | torrent-get          | new arg "downloaders"
637         |         | yes       | session-get          | new arg "version"
638         |         | yes       | torrent-remove       | new method
639   ------+---------+-----------+----------------------+-------------------------------
640   4     | 1.50    | yes       | session-get          | new arg "rpc-version"
641         |         | yes       | session-get          | new arg "rpc-version-minimum"
642         |         | yes       | session-stats        | added "cumulative-stats"
643         |         | yes       | session-stats        | added "current-stats"
644         |         | yes       | torrent-get          | new arg "downloadDir"
645   ------+---------+-----------+----------------------+-------------------------------
646   5     | 1.60    | yes       |                      | new method "torrent-reannounce"
647         |         | yes       |                      | new method "blocklist-update"
648         |         | yes       |                      | new method "port-test"
649         |         |           |                      |
650         |         | yes       | session-get          | new arg "alt-speed-begin"
651         |         | yes       | session-get          | new arg "alt-speed-down"
652         |         | yes       | session-get          | new arg "alt-speed-enabled"
653         |         | yes       | session-get          | new arg "alt-speed-end"
654         |         | yes       | session-get          | new arg "alt-speed-time-enabled"
655         |         | yes       | session-get          | new arg "alt-speed-up"
656         |         | yes       | session-get          | new arg "blocklist-enabled"
657         |         | yes       | session-get          | new arg "blocklist-size"
658         |         | yes       | session-get          | new arg "peer-limit-per-torrent"
659         |         | yes       | session-get          | new arg "seedRatioLimit"
660         |         | yes       | session-get          | new arg "seedRatioLimited"
661         |         |        NO | session-get          | renamed "pex-allowed" to "pex-enabled"
662         |         |        NO | session-get          | renamed "port" to "peer-port"
663         |         |        NO | session-get          | renamed "peer-limit" to "peer-limit-global"
664         |         |           |                      |
665         |         | yes       | torrent-add          | new arg "files-unwanted"
666         |         | yes       | torrent-add          | new arg "files-wanted"
667         |         | yes       | torrent-add          | new arg "priority-high"
668         |         | yes       | torrent-add          | new arg "priority-low"
669         |         | yes       | torrent-add          | new arg "priority-normal"
670         |         |           |                      |
671         |         | yes       | torrent-set          | new arg "bandwidthPriority"
672         |         | yes       | torrent-set          | new arg "honorsSessionLimits"
673         |         | yes       | torrent-set          | new arg "seedRatioLimit"
674         |         | yes       | torrent-set          | new arg "seedRatioLimited"
675         |         |        NO | torrent-set          | renamed "speed-limit-down" to "downloadLimit"
676         |         |        NO | torrent-set          | renamed "speed-limit-down-enabled" to "downloadLimited"
677         |         |        NO | torrent-set          | renamed "speed-limit-up" to "uploadLimit"
678         |         |        NO | torrent-set          | renamed "speed-limit-up-enabled" to "uploadLimited"
679         |         |           |                      |
680         |         | yes       | torrent-get          | new arg "bandwidthPriority"
681         |         | yes       | torrent-get          | new arg "fileStats"
682         |         | yes       | torrent-get          | new arg "honorsSessionLimits"
683         |         | yes       | torrent-get          | new arg "percentDone"
684         |         | yes       | torrent-get          | new arg "pieces"
685         |         | yes       | torrent-get          | new arg "seedRatioLimit"
686         |         | yes       | torrent-get          | new arg "seedRatioMode"
687         |         | yes       | torrent-get          | new arg "torrentFile"
688         |         | yes       | torrent-get          | new ids option "recently-active"
689         |         |        NO | torrent-get          | removed arg "downloadLimitMode"
690         |         |        NO | torrent-get          | removed arg "uploadLimitMode"
691   ------+---------+-----------+----------------------+-------------------------------
692   6     | 1.70    | yes       |                      | new "method torrent-set-location"
693   ------+---------+-----------+----------------------+-------------------------------
694   7     | 1.80    |        NO | torrent-get          | removed arg "announceResponse"
695         |         |        NO | torrent-get          | removed arg "announceURL"
696         |         |        NO | torrent-get          | removed arg "downloaders"
697         |         |        NO | torrent-get          | removed arg "lastAnnounceTime"
698         |         |        NO | torrent-get          | removed arg "lastScrapeTime"
699         |         |        NO | torrent-get          | removed arg "leechers"
700         |         |        NO | torrent-get          | removed arg "nextAnnounceTime"
701         |         |        NO | torrent-get          | removed arg "nextScrapeTime"
702         |         |        NO | torrent-get          | removed arg "scrapeResponse"
703         |         |        NO | torrent-get          | removed arg "scrapeURL"
704         |         |        NO | torrent-get          | removed arg "seeders"
705         |         |        NO | torrent-get          | removed arg "timesCompleted"
706         |         |        NO | torrent-get          | removed arg "swarmSpeed"
707         |         | yes       | torrent-get          | new arg "magnetLink"
708         |         | yes       | torrent-get          | new arg "metadataPercentComplete"
709         |         | yes       | torrent-get          | new arg "trackerStats"
710         |         | yes       | session-set          | new arg "incomplete-dir"
711         |         | yes       | session-set          | new arg "incomplete-dir-enabled"
712   ------+---------+-----------+----------------------+-------------------------------
713   8     | 1.90    | yes       | session-set          | new arg "rename-partial-files"
714         |         | yes       | session-get          | new arg "rename-partial-files"
715         |         | yes       | session-get          | new arg "config-dir"
716         |         | yes       | torrent-add          | new arg "bandwidthPriority"
717         |         | yes       | torrent-get          | new trackerStats arg "lastAnnounceTimedOut"
718   ------+---------+-----------+----------------------+-------------------------------
719   8     | 1.92    | yes       | torrent-get          | new trackerStats arg "lastScrapeTimedOut"
720   ------+---------+-----------+----------------------+-------------------------------
721   9     | 2.00    | yes       | session-set          | new arg "start-added-torrents"
722         |         | yes       | session-set          | new arg "trash-original-torrent-files"
723         |         | yes       | session-get          | new arg "start-added-torrents"
724         |         | yes       | session-get          | new arg "trash-original-torrent-files"
725         |         | yes       | torrent-get          | new arg "isFinished"
726   ------+---------+-----------+----------------------+-------------------------------
727   10    | 2.10    | yes       | session-get          | new arg "cache-size-mb"
728         |         | yes       | torrent-set          | new arg "trackerAdd"
729         |         | yes       | torrent-set          | new arg "trackerRemove"
730         |         | yes       | torrent-set          | new arg "trackerReplace"
731         |         | yes       | session-set          | new arg "idle-seeding-limit"
732         |         | yes       | session-set          | new arg "idle-seeding-limit-enabled"
733         |         | yes       | session-get          | new arg "units"
734         |         | yes       | torrent-set          | new arg "seedIdleLimit"
735         |         | yes       | torrent-set          | new arg "seedIdleMode"
736   ------+---------+-----------+----------------------+-------------------------------
737   11    | 2.12    | yes       | session-get          | new arg "blocklist-url"
738         |         | yes       | session-set          | new arg "blocklist-url"
739   ------+---------+-----------+----------------------+-------------------------------
740   12    | 2.20    | yes       | session-get          | new arg "download-dir-free-space"
741         |         | yes       | session-close        | new method
742   ------+---------+-----------+----------------------+-------------------------------
743   13    | 2.30    | yes       | session-get          | new arg "isUTP" to the "peers" list
744         |         | yes       | torrent-add          | new arg "cookies"
745         |         |        NO | torrent-get          | removed arg "peersKnown"
746   ------+---------+-----------+--------------------------+-------------------------------
747   14    | 2.40    |        NO | torrent-get          | values of "status" field changed
748         |         | yes       | torrent-get          | new arg "queuePosition"
749         |         | yes       | torrent-get          | new arg "isStalled"
750         |         | yes       | torrent-get          | new arg "fromLpd" in peersFrom
751         |         | yes       | torrent-set          | new arg "queuePosition"
752         |         | yes       | session-set          | new arg "download-queue-size"
753         |         | yes       | session-set          | new arg "download-queue-enabled"
754         |         | yes       | session-set          | new arg "seed-queue-size"
755         |         | yes       | session-set          | new arg "seed-queue-enabled"
756         |         | yes       | session-set          | new arg "queue-stalled-enabled"
757         |         | yes       | session-set          | new arg "queue-stalled-minutes"
758         |         | yes       |                      | new method "queue-move-top"
759         |         | yes       |                      | new method "queue-move-up"
760         |         | yes       |                      | new method "queue-move-down"
761         |         | yes       |                      | new method "queue-move-bottom"
762         |         | yes       |                      | new method "torrent-start-now"
763   ------+---------+-----------+--------------------------+-------------------------------
764   15    | 2.80    | yes       | torrent-get          | new arg "etaIdle"
765         |         | yes       | torrent-rename-path  | new method
766         |         | yes       | free-space           | new method
767         |         | yes       | torrent-add          | new return return arg "torrent-duplicate"
768
7695.1.  Upcoming Breakage
770
771   These features will be removed three months after 2.80's release:
772
773   1. session-get's 'download-dir-free-space' argument will be removed.
774      Its functionality has been superceded by the 'free-space' method.
775
776   2. HTTP POSTs to http://server:port/transmission/upload will fail.
777      This was an undocumented hack to allow web clients to add files without
778      client-side access to the file. This functionality is superceded by
779      using HTML5's FileReader object + the documented 'torrent-add' method.
Note: See TracBrowser for help on using the repository browser.