Ignore:
Timestamp:
Jul 26, 2008, 2:47:07 PM (13 years ago)
Author:
charles
Message:

(rpc) to lower the bandwidth/cpu used up by very large torrent lists, allow finer-grained control over which fields to return in the `torrent-get' request.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/rpc-spec.txt

    r6377 r6404  
    101101   Request arguments:
    102102
    103    string       | required? | default | value type & description
    104    -------------+-----------+---------+---------------------------------------
    105    "ids"        | no        | all     | array     described in 3.1
    106    "fields"     | yes       | n/a     | number    bitwise-or'ed field
    107                 |           |         |           values from the table below
     103   (1) An opional "ids" array as described in 3.1.
     104   (2) A required "fields" array of keys. (see list below)
    108105
    109106   Response arguments:
    110107
    111    (1) A "fields" number identical to the request's
    112    (2) A "torrents" array of objects, each of which contains the
    113        key/value fields that match the "fields" argument.
    114        See the table below for a complete list.
    115 
    116    "fields" value     | response | response               | source
    117                       | value    | key                    |
    118    -------------------+----------+------------------------+-------------
    119    activity, 1        | number   | desiredAvailable       | tr_stat
    120                       | number   | eta                    | tr_stat
    121                       | number   | peersConnected         | tr_stat
    122                       | number   | peersGettingFromUs     | tr_stat
    123                       | number   | peersSendingToUs       | tr_stat
    124                       | number   | rateDownload           | tr_stat
    125                       | number   | rateUpload             | tr_stat
    126                       | number   | recheckProgress        | tr_stat
    127                       | number   | status                 | tr_stat
    128                       | number   | swarmSpeed (K/s)       | tr_stat
    129                       | 'double' | uploadRatio            | tr_stat
    130                       | number   | webseedsSendingToUs    | tr_stat
    131    -------------------+----------+------------------------+-------------
    132    announce, 2        | string   | announceResponse       | tr_stat
    133                       | string   | announceURL            | tr_stat
    134                       | number   | lastAnnounceTime       | tr_stat
    135                       | number   | manualAnnounceTime     | tr_stat
    136                       | number   | nextAnnounceTime       | tr_stat
    137    -------------------+----------+------------------------+-------------
    138    error, 4           | number   | error                  | tr_stat
    139                       | number   | errorString            | tr_stat
    140    -------------------+----------+------------------------+-------------
    141    files, 8           | array    | files
    142                       +----------+--------------------------------------
    143                       | files is an array of objects that contain:
    144                       +----------+------------------------+-------------
    145                       | number   | bytesCompleted         | tr_torrent
    146                       | number   | length                 | tr_info
    147                       | string   | name                   | tr_info
    148    -------------------+----------+------------------------+-------------
    149    history, 16        | number   | activityDate           | tr_stat
    150                       | number   | addedDate              | tr_stat
    151                       | number   | corruptEver            | tr_stat
    152                       | number   | doneDate               | tr_stat
    153                       | number   | downloadedEver         | tr_stat
    154                       | number   | startDate              | tr_stat
    155                       | number   | uploadedEver           | tr_stat
    156    -------------------+----------+------------------------+-------------
    157    id, 32             | number   | uniqueId               | tr_torrent
    158                       | string   | hashString             | tr_info
    159                       | string   | name                   | tr_info
    160    -------------------+----------+------------------------+-------------
    161    info, 64           | string   | comment                | tr_info
    162                       | string   | creator                | tr_info
    163                       | number   | dateCreated            | tr_info
    164                       | number   | pieceCount             | tr_info
    165                       | number   | pieceSize              | tr_info
    166                       | 'boolean'| isPrivate              | tr_torrent
    167    -------------------+----------+------------------------+-------------
    168    limits, 128        | number   | downloadLimit          | tr_torrent
    169                       | number   | downloadLimitMode      | tr_torrent
    170                       | number   | maxConnectedPeers      | tr_torrent
    171                       | number   | uploadLimit            | tr_torrent
    172                       | number   | uploadLimitMode        | tr_torrent
    173    -------------------+----------+------------------------+-------------
    174    peers, 256         | not defined yet
    175    -------------------+----------+------------------------+-------------
    176    peer stats, 512    | number   | fromCache              | tr_stat
    177                       | number   | fromIncoming           | tr_stat
    178                       | number   | fromPex                | tr_stat
    179                       | number   | fromTracker            | tr_stat
    180    -------------------+----------+------------------------+-------------
    181    priorities, 1024   | array    | priorities             | tr_info
    182                       | array    | wanted                 | tr_info
    183                       +----------+--------------------------------------
    184                       | priorities is an array of tr_info.fileCount
    185                       | numbers.  Each is the tr_priority_t mode for
    186                       | the corresponding file.
    187                       +-------------------------------------------------
    188                       | wanted is an array of tr_info.fileCount
    189                       | 'booleans' true if the corresponding file
    190                       | is to be downloaded.
    191    -------------------+----------+------------------------+-------------
    192    scrape, 2048       | number   | lastScrapeTime         | tr_stat
    193                       | number   | nextScrapeTime         | tr_stat
    194                       | string   | scrapeResponse         | tr_stat
    195                       | string   | scrapeURL              | tr_stat
    196    -------------------+----------+------------------------+-------------
    197    size, 4096         | number   | haveUnchecked          | tr_stat
    198                       | number   | haveValid              | tr_stat
    199                       | number   | leftUntilDone          | tr_stat
    200                       | number   | sizeWhenDone           | tr_stat
    201                       | number   | totalSize              | tr_info
    202    -------------------+----------+------------------------+-------------
    203    tracker stats,     | number   | leechers               | tr_stat
    204    8192               | number   | peersKnown             | tr_stat
    205                       | number   | seeders                | tr_stat
    206                       | number   | timesCompleted         | tr_stat
    207    -------------------+----------+--------------------------------------
    208    trackers, 16384    | array    | trackers
    209                       +----------+--------------------------------------
    210                       | trackers is an array of objects that contain:
    211                       +----------+------------------------+-------------
    212                       | string   | announce               | tr_info
    213                       | string   | scrape                 | tr_info
    214                       | number   | tier                   | tr_info
    215    -------------------+----------+------------------------+-------------
    216    webseeds, 32768    | array    | webseeds
    217                       +----------+--------------------------------------
    218                       | webseeds is an array of strings:
    219                       +----------+------------------------+-------------
    220                       | string   | webseed URL            | tr_info
    221    -------------------+----------+------------------------+-------------
     108   (1) A "torrents" array of objects, each of which contains
     109       the key/value pairs matching the request's "fields" argument.
     110
     111   key                    | type                                 | source
     112   -----------------------+--------------------------------------+---------
     113   activityDate           | number                               | tr_stat
     114   addedDate              | number                               | tr_stat
     115   announceResponse       | string                               | tr_stat
     116   announceURL            | string                               | tr_stat
     117   comment                | string                               | tr_info
     118   corruptEver            | number                               | tr_stat
     119   creator                | string                               | tr_info
     120   dateCreated            | number                               | tr_info
     121   desiredAvailable       | number                               | tr_stat
     122   doneDate               | number                               | tr_stat
     123   downloadedEver         | number                               | tr_stat
     124   downloadLimitMode      | number                               | tr_torrent
     125   downloadLimit          | number                               | tr_torrent
     126   error                  | number                               | tr_stat
     127   errorString            | number                               | tr_stat
     128   eta                    | number                               | tr_stat
     129   files                  | array (see below)                    | n/a
     130   hashString             | string                               | tr_info
     131   haveUnchecked          | number                               | tr_stat
     132   haveValid              | number                               | tr_stat
     133   id                     | number                               | tr_torrent
     134   isPrivate              | 'boolean                             | tr_torrent
     135   lastAnnounceTime       | number                               | tr_stat
     136   lastScrapeTime         | number                               | tr_stat
     137   leechers               | number                               | tr_stat
     138   leftUntilDone          | number                               | tr_stat
     139   manualAnnounceTime     | number                               | tr_stat
     140   maxConnectedPeers      | number                               | tr_torrent
     141   name                   | string                               | tr_info
     142   nextAnnounceTime       | number                               | tr_stat
     143   nextScrapeTime         | number                               | tr_stat
     144   peersConnected         | number                               | tr_stat
     145   peersFrom              | object (see below)                   | n/a
     146   peersGettingFromUs     | number                               | tr_stat
     147   peersKnown             | number                               | tr_stat
     148   peersSendingToUs       | number                               | tr_stat
     149   pieceCount             | tnumber                              | tr_info
     150   pieceSize              | tnumber                              | tr_info
     151   priorities             | array (see below)                    | n/a
     152   rateDownload           | number                               | tr_stat
     153   rateUpload             | number                               | tr_stat
     154   recheckProgress        | number                               | tr_stat
     155   scrapeResponse         | string                               | tr_stat
     156   scrapeURL              | string                               | tr_stat
     157   seeders                | number                               | tr_stat
     158   sizeWhenDone           | number                               | tr_stat
     159   startDate              | number                               | tr_stat
     160   status                 | number                               | tr_stat
     161   swarmSpeed (K/s)       | number                               | tr_stat
     162   timesCompleted         | number                               | tr_stat
     163   trackers               | array (see below)                    | n/a
     164   totalSize              | number                               | tr_info
     165   uploadedEver           | number                               | tr_stat
     166   uploadLimitMode        | number                               | tr_torrent
     167   uploadLimit            | number                               | tr_torrent
     168   uploadRatio            | 'double'                             | tr_stat
     169   wanted                 | array (see below)                    | n/a
     170   webseeds               | array (see below)                    | n/a
     171   webseedsSendingToUs    | number                               | tr_stat
     172                          |                                      |
     173                          |                                      |
     174   -----------------------+--------------------------------------+
     175   files                  | array of objects, each containing:   |
     176                          +------------------+-------------------+
     177                          | key              | type              |
     178                          | bytesCompleted   | number            | tr_torrent
     179                          | length           | number            | tr_info
     180                          | name             | string            | tr_info
     181   -----------------------+--------------------------------------+
     182   peersFrom              | an object containing:                |
     183                          +------------------+-------------------+
     184                          | fromCache        | number            | tr_stat
     185                          | fromIncoming     | number            | tr_stat
     186                          | fromPex          | number            | tr_stat
     187                          | fromTracker      | number            | tr_stat
     188   -----------------------+--------------------------------------+
     189   priorities             | an array of tr_info.filecount        | tr_info
     190                          | numbers. each is the tr_priority_t   |
     191                          | mode for the corresponding file.     |
     192   -----------------------+--------------------------------------+
     193   trackers               | array of objects, each containing:   |
     194                          +------------------+-------------------+
     195                          | announce         | string            | tr_info
     196                          | scrape           | string            | tr_info
     197                          | tier             | number            | tr_info
     198   -----------------------+--------------------------------------+
     199   wanted                 | an array of tr_info.fileCount        | tr_info
     200                          | 'booleans' true if the corresponding |
     201                          | file is to be downloaded.            |
     202   -----------------------+--------------------------------------+
     203   webseeds               | an array of strings:                 |
     204                          +------------------+-------------------+
     205                          | webseed          | string            | tr_info
     206                          +------------------+-------------------+
    222207
    223208   Example:
    224209
    225210   Say we want to get the name and total size of torrents #7 and #10.
    226    name is in the "id" section (32) and total size is in "size" (2048),
    227    so the "fields" argument will be 32 + 2048 == 2080.
    228211
    229212   Request:
     
    232215         "arguments": {
    233216             "fields": 2080,
    234              "ids": [ 7, 10 ],
     217             "fields": [ "name", "totalSize" ],
    235218             "sort-method": "name"
    236219         }
     
    247230            "torrents": [
    248231               {
    249                    "hashString": "sijioejisoefjiosejfioi",
    250                    "haveUnchecked", 23023,
    251                    "haveValid", 27986795145,
    252                    "leftUntilDone", 0,
     232                   "id": 10,
    253233                   "name": "Fedora x86_64 DVD",
    254                    "sizeWhenDone", 34983493932,
    255234                   "totalSize", 34983493932,
    256                    "uniqueId": 10,
    257235               }
    258236               {
    259                    "hashString": "asdasiofjosejfoasjfiosj",
    260                    "haveUnchecked", 0,
    261                    "haveValid", 9923890123,
    262                    "leftUntilDone", 0,
     237                   "id": 7,
    263238                   "name": "Ubuntu x86_64 DVD",
    264                    "sizeWhenDone", 9923890123,
    265239                   "totalSize", 9923890123,
    266                    "uniqueId": 7,
    267240               },
    268241            ]
Note: See TracChangeset for help on using the changeset viewer.