source: trunk/libtransmission/transmission.h @ 7456

Last change on this file since 7456 was 7456, checked in by charles, 12 years ago

(trunk libT) minor cleanups found while diffing for backport to 1.4x in r7455

  • Property svn:keywords set to Date Rev Author Id
File size: 47.6 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 7456 2008-12-22 00:52:44Z charles $
3 *
4 * Copyright (c) 2005-2008 Transmission authors and contributors
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a
7 * copy of this software and associated documentation files (the "Software"),
8 * to deal in the Software without restriction, including without limitation
9 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 * and/or sell copies of the Software, and to permit persons to whom the
11 * Software is furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 * DEALINGS IN THE SOFTWARE.
23 *****************************************************************************/
24
25/*
26 * This file defines the public API for the libtransmission library.
27 *
28 * Other headers suitable for public consumption are bencode.h
29 * and utils.h.  Most of the remaining headers in libtransmission
30 * should be considered private to libtransmission.
31 */
32#ifndef TR_TRANSMISSION_H
33#define TR_TRANSMISSION_H 1
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39#include "version.h"
40
41#include <inttypes.h> /* uintN_t */
42#ifndef PRId64
43 #define PRId64 "lld"
44#endif
45#ifndef PRIu64
46 #define PRIu64 "llu"
47#endif
48#ifndef PRIu32
49 #define PRIu32 "lu"
50#endif
51#include <time.h> /* time_t */
52
53#define SHA_DIGEST_LENGTH 20
54#define TR_INET6_ADDRSTRLEN 46
55
56typedef uint32_t tr_file_index_t;
57typedef uint32_t tr_piece_index_t;
58typedef uint64_t tr_block_index_t;
59typedef uint16_t tr_port;
60typedef uint8_t tr_bool;
61
62/**
63 * @brief returns Transmission's default configuration file directory.
64 *
65 * The default configuration directory is determined this way:
66 * 1. If the TRANSMISSION_HOME environmental variable is set, its value is used.
67 * 2. On Darwin, "${HOME}/Library/Application Support/${appname}" is used.
68 * 3. On Windows, "${CSIDL_APPDATA}/${appname}" is used.
69 * 4. If XDG_CONFIG_HOME is set, "${XDG_CONFIG_HOME}/${appname}" is used.
70 * 5. ${HOME}/.config/${appname}" is used as a last resort.
71 */
72const char* tr_getDefaultConfigDir( const char * appname );
73
74/**
75 * @brief returns Transmisson's default download directory.
76 *
77 * The default download directory is determined this way:
78 * 1. If the HOME environmental variable is set, "${HOME}/Downloads" is used.
79 * 2. On Windows, "${CSIDL_MYDOCUMENTS}/Downloads" is used.
80 * 3. Otherwise, getpwuid(getuid())->pw_dir + "/Downloads" is used.
81 */
82const char* tr_getDefaultDownloadDir( void );
83
84typedef struct tr_ctor tr_ctor;
85typedef struct tr_handle tr_handle;
86typedef struct tr_info tr_info;
87typedef struct tr_torrent tr_torrent;
88typedef tr_handle tr_session;
89
90
91/**
92 * @addtogroup tr_session Session
93 *
94 * A libtransmission session is created by calling tr_sessionInit().
95 * libtransmission creates a thread for itself so that it can operate
96 * independently of the caller's event loop.  The session will continue
97 * until tr_sessionClose() is called.
98 *
99 * @{
100 */
101
102typedef enum
103{
104    TR_PROXY_HTTP,
105    TR_PROXY_SOCKS4,
106    TR_PROXY_SOCKS5
107}
108tr_proxy_type;
109
110typedef enum
111{
112    TR_CLEAR_PREFERRED,
113    TR_ENCRYPTION_PREFERRED,
114    TR_ENCRYPTION_REQUIRED
115}
116tr_encryption_mode;
117
118#define TR_DEFAULT_RPC_WHITELIST "127.0.0.1"
119#define TR_DEFAULT_RPC_PORT_STR "9091"
120#define TR_DEFAULT_PEER_PORT_STR "51413"
121#define TR_DEFAULT_PEER_SOCKET_TOS_STR "8"
122
123#define TR_PREFS_KEY_BLOCKLIST_ENABLED          "blocklist-enabled"
124#define TR_PREFS_KEY_DOWNLOAD_DIR               "download-dir"
125#define TR_PREFS_KEY_DSPEED                     "download-limit"
126#define TR_PREFS_KEY_DSPEED_ENABLED             "download-limit-enabled"
127#define TR_PREFS_KEY_ENCRYPTION                 "encryption"
128#define TR_PREFS_KEY_LAZY_BITFIELD              "lazy-bitfield-enabled"
129#define TR_PREFS_KEY_MSGLEVEL                   "message-level"
130#define TR_PREFS_KEY_PEER_LIMIT_GLOBAL          "peer-limit-global"
131#define TR_PREFS_KEY_PEER_LIMIT_TORRENT         "peer-limit-per-torrent"
132#define TR_PREFS_KEY_PEER_PORT                  "peer-port"
133#define TR_PREFS_KEY_PEER_PORT_RANDOM_ENABLED   "peer-port-random-enabled"
134#define TR_PREFS_KEY_PEER_PORT_RANDOM_LOW       "peer-port-random-low"
135#define TR_PREFS_KEY_PEER_PORT_RANDOM_HIGH      "peer-port-random-high"
136#define TR_PREFS_KEY_PEER_SOCKET_TOS            "peer-socket-tos"
137#define TR_PREFS_KEY_PEX_ENABLED                "pex-enabled"
138#define TR_PREFS_KEY_PORT_FORWARDING            "port-forwarding-enabled"
139#define TR_PREFS_KEY_PROXY_AUTH_ENABLED         "proxy-auth-enabled"
140#define TR_PREFS_KEY_PROXY_ENABLED              "proxy-enabled"
141#define TR_PREFS_KEY_PROXY_PASSWORD             "proxy-auth-password"
142#define TR_PREFS_KEY_PROXY_PORT                 "proxy-port"
143#define TR_PREFS_KEY_PROXY                      "proxy"
144#define TR_PREFS_KEY_PROXY_TYPE                 "proxy-type"
145#define TR_PREFS_KEY_PROXY_USERNAME             "proxy-auth-username"
146#define TR_PREFS_KEY_RPC_AUTH_REQUIRED          "rpc-authentication-required"
147#define TR_PREFS_KEY_RPC_ENABLED                "rpc-enabled"
148#define TR_PREFS_KEY_RPC_PASSWORD               "rpc-password"
149#define TR_PREFS_KEY_RPC_PORT                   "rpc-port"
150#define TR_PREFS_KEY_RPC_USERNAME               "rpc-username"
151#define TR_PREFS_KEY_RPC_WHITELIST_ENABLED      "rpc-whitelist-enabled"
152#define TR_PREFS_KEY_RPC_WHITELIST              "rpc-whitelist"
153#define TR_PREFS_KEY_USPEED_ENABLED             "upload-limit-enabled"
154#define TR_PREFS_KEY_USPEED                     "upload-limit"
155
156struct tr_benc;
157
158/**
159 * Add libtransmission's default settings to the benc dictionary.
160 *
161 * Example:
162 * @code
163 *     tr_benc settings;
164 *     int64_t i;
165 *
166 *     tr_bencInitDict( &settings, 0 );
167 *     tr_sessionGetDefaultSettings( &settings );
168 *     if( tr_bencDictFindInt( &settings, TR_PREFS_KEY_PEER_PORT, &i ) )
169 *         fprintf( stderr, "the default peer port is %d\n", (int)i );
170 *     tr_bencFree( &settings );
171 * @endcode
172 *
173 * @param initme pointer to a tr_benc dictionary
174 * @see tr_sessionLoadSettings()
175 * @see tr_sessionInit()
176 * @see tr_getDefaultConfigDir()
177 */
178void tr_sessionGetDefaultSettings( struct tr_benc * dictionary );
179
180/**
181 * Add the session's configuration settings to the benc dictionary.
182 *
183 * FIXME: this probably belongs in libtransmissionapp
184 *
185 * @param session
186 * @param dictionary
187 * @see tr_sessionGetDefaultSettings()
188 */
189void tr_sessionGetSettings( tr_session *, struct tr_benc * dictionary );
190
191/**
192 * Load settings from the configuration directory's settings.json file,
193 * using libtransmission's default settings as fallbacks for missing keys.
194 *
195 * FIXME: this belongs in libtransmissionapp
196 *
197 * @param configDir the configuration directory to find settings.json
198 * @param initme pointer to an uninitialized tr_benc
199 * @param appName examples: Transmission, transmission-daemon
200 * @see tr_sessionGetDefaultSettings()
201 * @see tr_sessionInit()
202 * @see tr_sessionSaveSettings()
203 */
204void tr_sessionLoadSettings( struct tr_benc  * dictionary,
205                             const char      * configDir,
206                             const char      * appName );
207
208/**
209 * Add the session's configuration settings to the benc dictionary
210 * and save it to the configuration directory's settings.json file.
211 *
212 * FIXME: this belongs in libtransmissionapp
213 *
214 * @param session
215 * @param dictionary
216 * @see tr_sessionLoadSettings()
217 */
218void tr_sessionSaveSettings( tr_session     * session,
219                             const char     * configDir,
220                             struct tr_benc * dictonary );
221
222/**
223 * Initialize a libtransmission session.
224 *
225 * For example, this will instantiate a session with all the default values:
226 * @code
227 *     tr_benc settings;
228 *     tr_session * session;
229 *     const char * configDir;
230 *
231 *     tr_bencInitDict( &settings, 0 );
232 *     tr_sessionGetDefaultSettings( &settings );
233 *     configDir = tr_getDefaultConfigDir( "Transmission" );
234 *     session = tr_sessionInit( "mac", configDir, true, &settings );
235 *
236 *     tr_bencFree( &settings );
237 * @encode
238 *
239 * @param tag "gtk", "macosx", "daemon", etc... this is only for pre-1.30 resume files
240 * @param configDir where Transmission will look for resume files, blocklists, etc.
241 * @param messageQueueingEnabled if false, messages will be dumped to stderr
242 * @param settings libtransmission settings
243 * @see tr_sessionGetDefaultSettings()
244 * @see tr_sessionLoadSettings()
245 * @see tr_getDefaultConfigDir()
246 */
247tr_session * tr_sessionInit( const char     * tag,
248                             const char     * configDir,
249                             tr_bool          messageQueueingEnabled,
250                             struct tr_benc * settings );
251
252/** @brief End a libtransmission session
253    @see tr_sessionInit() */
254void tr_sessionClose( tr_session * );
255
256/**
257 * @brief Return the session's configuration directory
258 *
259 * This is where transmission stores its .torrent files, .resume files,
260 * blocklists, etc.
261 */
262const char * tr_sessionGetConfigDir( const tr_session * );
263
264/**
265 * @brief Set the per-session default download folder for new torrents.
266 * @see tr_sessionInit()
267 * @see tr_sessionGetDownloadDir()
268 * @see tr_ctorSetDownloadDir()
269 */
270void tr_sessionSetDownloadDir( tr_session  * session,
271                               const char  * downloadDir );
272
273/**
274 * @brief Get the default download folder for new torrents.
275 *
276 * This is set by tr_sessionInit() or tr_sessionSetDownloadDir(),
277 * and can be overridden on a per-torrent basis by tr_ctorSetDownloadDir().
278 */
279const char * tr_sessionGetDownloadDir( const tr_session * session );
280
281/**
282 * @brief Set whether or not RPC calls are allowed in this session.
283 *
284 * @details If true, libtransmission will open a server socket to listen
285 * for incoming http RPC requests as described in docs/rpc-spec.txt.
286 *
287 * This is intially set by tr_sessionInit() and can be
288 * queried by tr_sessionIsRPCEnabled().
289 */
290void tr_sessionSetRPCEnabled( tr_session  * session,
291                              tr_bool       isEnabled );
292
293/** @brief Get whether or not RPC calls are allowed in this session.
294    @see tr_sessionInit()
295    @see tr_sessionSetRPCEnabled() */
296tr_bool tr_sessionIsRPCEnabled( const tr_session * session );
297
298/** @brief Specify which port to listen for RPC requests on.
299    @see tr_sessionInit()
300    @see tr_sessionGetRPCPort */
301void tr_sessionSetRPCPort( tr_session  * session,
302                           tr_port       port );
303
304/** @brief Get which port to listen for RPC requests on.
305    @see tr_sessionInit()
306    @see tr_sessionSetRPCPort */
307tr_port tr_sessionGetRPCPort( const tr_session * session );
308
309/**
310 * @brief Specify a whitelist for remote RPC access
311 *
312 * The whitelist is a comma-separated list of dotted-quad IP addresses
313 * to be allowed.  Wildmat notation is supported, meaning that
314 * '?' is interpreted as a single-character wildcard and
315 * '*' is interprted as a multi-character wildcard.
316 */
317void   tr_sessionSetRPCWhitelist( tr_session * session,
318                                  const char * whitelist );
319
320/** @brief get the Access Control List for allowing/denying RPC requests.
321    @return a comma-separated string of whitelist domains.  tr_free() when done.
322    @see tr_sessionInit
323    @see tr_sessionSetRPCWhitelist */
324char* tr_sessionGetRPCWhitelist( const tr_session * );
325
326void  tr_sessionSetRPCWhitelistEnabled( tr_session * session,
327                                        tr_bool      isEnabled );
328
329tr_bool tr_sessionGetRPCWhitelistEnabled( const tr_session * session );
330
331void  tr_sessionSetRPCPassword( tr_session * session,
332                                const char * password );
333
334void  tr_sessionSetRPCUsername( tr_session * session,
335                                const char * username );
336
337/** @brief get the password used to restrict RPC requests.
338    @return the password string. tr_free() when done.
339    @see tr_sessionInit()
340    @see tr_sessionSetRPCPassword() */
341char* tr_sessionGetRPCPassword( const tr_session * session );
342
343char* tr_sessionGetRPCUsername( const tr_session * session  );
344
345void  tr_sessionSetRPCPasswordEnabled( tr_session * session,
346                                       tr_bool      isEnabled );
347
348tr_bool tr_sessionIsRPCPasswordEnabled( const tr_session * session );
349
350
351typedef enum
352{
353    TR_RPC_TORRENT_ADDED,
354    TR_RPC_TORRENT_STARTED,
355    TR_RPC_TORRENT_STOPPED,
356    TR_RPC_TORRENT_REMOVING,
357    TR_RPC_TORRENT_CHANGED, /* catch-all for the "torrent-set" rpc method */
358    TR_RPC_SESSION_CHANGED
359}
360tr_rpc_callback_type;
361
362typedef enum
363{
364    /* no special handling is needed by the caller */
365    TR_RPC_OK            = 0,
366
367    /* indicates to the caller that the client will take care of
368     * removing the torrent itself.  For example the client may
369     * need to keep the torrent alive long enough to cleanly close
370     * some resources in another thread. */
371    TR_RPC_NOREMOVE   = ( 1 << 1 )
372}
373tr_rpc_callback_status;
374
375typedef tr_rpc_callback_status (*tr_rpc_func)(tr_session          * session,
376                                              tr_rpc_callback_type  type,
377                                              struct tr_torrent   * tor_or_null,
378                                              void                * user_data );
379
380/**
381 * Register to be notified whenever something is changed via RPC,
382 * such as a torrent being added, removed, started, stopped, etc.
383 *
384 * func is invoked FROM LIBTRANSMISSION'S THREAD!
385 * This means func must be fast (to avoid blocking peers),
386 * shouldn't call libtransmission functions (to avoid deadlock),
387 * and shouldn't modify client-level memory without using a mutex!
388 */
389void tr_sessionSetRPCCallback( tr_session   * session,
390                               tr_rpc_func    func,
391                               void         * user_data );
392
393/**
394***
395**/
396
397tr_bool       tr_sessionIsProxyEnabled( const tr_session * );
398
399tr_bool       tr_sessionIsProxyAuthEnabled( const tr_session * );
400
401const char*   tr_sessionGetProxy( const tr_session * );
402
403tr_port       tr_sessionGetProxyPort( const tr_session * );
404
405tr_proxy_type tr_sessionGetProxyType( const tr_session * );
406
407const char*   tr_sessionGetProxyUsername( const tr_session * );
408
409const char*   tr_sessionGetProxyPassword( const tr_session * );
410
411void          tr_sessionSetProxyEnabled( tr_session * session,
412                                         tr_bool      isEnabled );
413
414void          tr_sessionSetProxyAuthEnabled( tr_session * session,
415                                             tr_bool      isEnabled );
416
417void          tr_sessionSetProxy( tr_session * session,
418                                  const char * proxy );
419
420void          tr_sessionSetProxyPort( tr_session * session,
421                                      tr_port      port );
422
423void          tr_sessionSetProxyType( tr_session    * session,
424                                      tr_proxy_type   proxy_type );
425
426void          tr_sessionSetProxyUsername( tr_session * session,
427                                          const char * username );
428
429void          tr_sessionSetProxyPassword( tr_session * session,
430                                          const char * password );
431
432/**
433***
434**/
435
436typedef struct tr_session_stats
437{
438    float       ratio;        /* TR_RATIO_INF, TR_RATIO_NA, or total up/down */
439    uint64_t    uploadedBytes; /* total up */
440    uint64_t    downloadedBytes; /* total down */
441    uint64_t    filesAdded;   /* number of files added */
442    uint64_t    sessionCount; /* program started N times */
443    uint64_t    secondsActive; /* how long Transmisson's been running */
444}
445tr_session_stats;
446
447/* stats from the current session. */
448void               tr_sessionGetStats( const tr_session * session,
449                                       tr_session_stats * setme );
450
451/* stats from the current and past sessions. */
452void               tr_sessionGetCumulativeStats( const tr_session * session,
453                                                 tr_session_stats * setme );
454
455void               tr_sessionClearStats( tr_session * session );
456
457/**
458 * Set whether or not torrents are allowed to do peer exchanges.
459 * PEX is always disabled in private torrents regardless of this.
460 * In public torrents, PEX is enabled by default.
461 */
462void               tr_sessionSetPexEnabled( tr_session  * session,
463                                            tr_bool       isEnabled );
464
465tr_bool            tr_sessionIsPexEnabled( const tr_session * session );
466
467void               tr_sessionSetLazyBitfieldEnabled( tr_session * session,
468                                                     tr_bool       enabled );
469
470tr_bool            tr_sessionIsLazyBitfieldEnabled( const tr_session * session );
471
472tr_encryption_mode tr_sessionGetEncryption( tr_session * session );
473
474void               tr_sessionSetEncryption( tr_session          * session,
475                                            tr_encryption_mode    mode );
476
477
478/***********************************************************************
479** Incoming Peer Connections Port
480*/
481
482void  tr_sessionSetPortForwardingEnabled( tr_session  * session,
483                                          tr_bool       enabled );
484
485tr_bool tr_sessionIsPortForwardingEnabled( const tr_session  * session );
486
487void  tr_sessionSetPeerPort( tr_session  * session,
488                             tr_port       port);
489
490tr_port tr_sessionSetPeerPortRandom( tr_session  * session );
491
492tr_port tr_sessionGetPeerPort( const tr_session * session );
493
494typedef enum
495{
496    TR_PORT_ERROR,
497    TR_PORT_UNMAPPED,
498    TR_PORT_UNMAPPING,
499    TR_PORT_MAPPING,
500    TR_PORT_MAPPED
501}
502tr_port_forwarding;
503
504tr_port_forwarding tr_sessionGetPortForwarding( const tr_session * session );
505
506int tr_sessionCountTorrents( const tr_session * session );
507
508typedef enum
509{
510    TR_CLIENT_TO_PEER = 0, TR_UP = 0,
511    TR_PEER_TO_CLIENT = 1, TR_DOWN = 1
512}
513tr_direction;
514
515void       tr_sessionSetSpeedLimitEnabled ( tr_session        * session,
516                                            tr_direction        direction,
517                                            tr_bool             isEnabled );
518
519tr_bool    tr_sessionIsSpeedLimitEnabled  ( const tr_session  * session,
520                                            tr_direction        direction );
521
522void       tr_sessionSetSpeedLimit        ( tr_session        * session,
523                                            tr_direction        direction,
524                                            int                 KiB_sec );
525
526int        tr_sessionGetSpeedLimit        ( const tr_session  * session,
527                                            tr_direction        direction );
528
529double     tr_sessionGetRawSpeed          ( const tr_session  * session,
530                                           tr_direction         direction );
531
532double     tr_sessionGetPieceSpeed        ( const tr_session  * session,
533                                            tr_direction        direction );
534
535
536void       tr_sessionSetPeerLimit( tr_session  * session,
537                                   uint16_t      maxGlobalPeers );
538
539uint16_t   tr_sessionGetPeerLimit( const tr_session * session );
540
541void       tr_sessionSetPeerLimitPerTorrent( tr_session  * session,
542                                             uint16_t      maxGlobalPeers );
543
544uint16_t   tr_sessionGetPeerLimitPerTorrent( const tr_session * session );
545
546
547/**
548 *  Load all the torrents in tr_getTorrentDir().
549 *  This can be used at startup to kickstart all the torrents
550 *  from the previous session.
551 */
552tr_torrent ** tr_sessionLoadTorrents( tr_session  * session,
553                                      tr_ctor     * ctor,
554                                      int         * setmeCount );
555
556/** @} */
557
558/**
559***
560**/
561
562
563/***********************************************************************
564** Message Logging
565*/
566
567enum
568{
569    TR_MSG_ERR = 1,
570    TR_MSG_INF = 2,
571    TR_MSG_DBG = 3
572};
573void tr_setMessageLevel( int );
574
575int  tr_getMessageLevel( void );
576
577typedef struct tr_msg_list
578{
579    /* TR_MSG_ERR, TR_MSG_INF, or TR_MSG_DBG */
580    uint8_t level;
581
582    /* The line number in the source file where this message originated */
583    int line;
584
585    /* Time the message was generated */
586    time_t when;
587
588    /* The torrent associated with this message,
589     * or a module name such as "Port Forwarding" for non-torrent messages,
590     * or NULL. */
591    char *  name;
592
593    /* The message */
594    char *  message;
595
596    /* The source file where this message originated */
597    const char * file;
598
599    /* linked list of messages */
600    struct tr_msg_list * next;
601}
602tr_msg_list;
603
604void          tr_setMessageQueuing( tr_bool isEnabled );
605
606tr_bool       tr_getMessageQueuing( void );
607
608tr_msg_list * tr_getQueuedMessages( void );
609
610void          tr_freeMessageList( tr_msg_list * freeme );
611
612/** @addtogroup Blocklists
613    @{ */
614
615/**
616 * Specify a range of IPs for Transmission to block.
617 *
618 * filename must be an uncompressed ascii file,
619 * using the same format as the bluetack level1 file.
620 *
621 * libtransmission does not keep a handle to `filename'
622 * after this call returns, so the caller is free to
623 * keep or delete `filename' as it wishes.
624 * libtransmission makes its own copy of the file
625 * massaged into a format easier to search.
626 *
627 * The caller only needs to invoke this when the blocklist
628 * has changed.
629 *
630 * Passing NULL for a filename will clear the blocklist.
631 */
632int     tr_blocklistSetContent   ( tr_session       * session,
633                                   const char       * filename );
634
635int     tr_blocklistGetRuleCount ( const tr_session * session );
636
637tr_bool tr_blocklistExists       ( const tr_session * session );
638
639tr_bool tr_blocklistIsEnabled    ( const tr_session * session );
640
641void    tr_blocklistSetEnabled   ( tr_session       * session,
642                                   tr_bool            isEnabled );
643
644
645/** @} */
646
647
648/** @addtogroup tr_ctor Torrent Instantiation
649    @{
650
651    Instantiating a tr_torrent had gotten more complicated as features were
652    added.  At one point there were four functions to check metainfo and five
653    to create tr_torrent.
654
655    To remedy this, a Torrent Constructor (struct tr_ctor) has been introduced:
656    - Simplifies the API to two functions: tr_torrentParse() and tr_torrentNew()
657    - You can set the fields you want; the system sets defaults for the rest.
658    - You can specify whether or not your fields should supercede resume's.
659    - We can add new features to tr_ctor without breaking tr_torrentNew()'s API.
660
661    All the tr_ctor{Get,Set}*() functions with a return value return
662    an error number, or zero if no error occurred.
663
664    You must call one of the SetMetainfo() functions before creating
665    a torrent with a tr_ctor.  The other functions are optional.
666
667    You can reuse a single tr_ctor to create a batch of torrents --
668    just call one of the SetMetainfo() functions between each
669    tr_torrentNew() call.
670
671    Every call to tr_ctorSetMetainfo*() frees the previous metainfo.
672 */
673
674typedef enum
675{
676    TR_FALLBACK, /* indicates the ctor value should be used only
677                    in case of missing resume settings */
678
679    TR_FORCE, /* indicates the ctor value should be used
680                 regardless of what's in the resume settings */
681}
682tr_ctorMode;
683
684struct tr_benc;
685
686tr_ctor*    tr_ctorNew( const tr_session * session );
687
688void        tr_ctorFree( tr_ctor * ctor );
689
690void        tr_ctorSetDeleteSource( tr_ctor * ctor,
691                                    tr_bool   doDelete );
692
693int         tr_ctorSetMetainfo( tr_ctor *       ctor,
694                                const uint8_t * metainfo,
695                                size_t          len );
696
697int         tr_ctorSetMetainfoFromFile( tr_ctor *    ctor,
698                                        const char * filename );
699
700int         tr_ctorSetMetainfoFromHash( tr_ctor *    ctor,
701                                        const char * hashString );
702
703/** Set the maximum number of peers this torrent can connect to.
704    (Default: 50) */
705void        tr_ctorSetPeerLimit( tr_ctor *   ctor,
706                                 tr_ctorMode mode,
707                                 uint16_t    peerLimit  );
708
709/** Set the download folder for the torrent being added with this ctor.
710    @see tr_ctorSetDownloadDir()
711    @see tr_sessionInit() */
712void        tr_ctorSetDownloadDir( tr_ctor *    ctor,
713                                   tr_ctorMode  mode,
714                                   const char * directory );
715
716/** Set whether or not the torrent begins downloading/seeding when created.
717    (Default: not paused) */
718void        tr_ctorSetPaused( tr_ctor      * ctor,
719                              tr_ctorMode    mode,
720                              tr_bool        isPaused );
721
722int         tr_ctorGetPeerLimit( const tr_ctor * ctor,
723                                 tr_ctorMode     mode,
724                                 uint16_t *      setmeCount );
725
726int         tr_ctorGetPaused( const tr_ctor * ctor,
727                              tr_ctorMode     mode,
728                              tr_bool       * setmeIsPaused );
729
730int         tr_ctorGetDownloadDir( const tr_ctor  * ctor,
731                                   tr_ctorMode      mode,
732                                   const char    ** setmeDownloadDir );
733
734int         tr_ctorGetMetainfo( const tr_ctor         * ctor,
735                                const struct tr_benc ** setme );
736
737int         tr_ctorGetDeleteSource( const tr_ctor  * ctor,
738                                    tr_bool        * setmeDoDelete );
739
740/* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
741const char* tr_ctorGetSourceFile( const tr_ctor * ctor );
742
743#define TR_EINVALID     1
744#define TR_EDUPLICATE   2
745
746/**
747 * Parses the specified metainfo.
748 * Returns 0 if it parsed successfully and can be added to Transmission.
749 * Returns TR_EINVALID if it couldn't be parsed.
750 * Returns TR_EDUPLICATE if it parsed but can't be added.
751 *     "download-dir" must be set to test for TR_EDUPLICATE.
752 *
753 * If setme_info is non-NULL and parsing is successful
754 * (that is, if TR_EINVALID is not returned), then the parsed
755 * metainfo is stored in setme_info and should be freed by the
756 * caller via tr_metainfoFree().
757 */
758int tr_torrentParse( const tr_session  * session,
759                     const tr_ctor     * ctor,
760                     tr_info           * setme_info_or_NULL );
761
762/** @brief free a metainfo
763    @see tr_torrentParse */
764void tr_metainfoFree( tr_info * inf );
765
766
767/** Instantiate a single torrent.
768    @return 0 on success,
769            TR_EINVALID if the torrent couldn't be parsed, or
770            TR_EDUPLICATE if there's already a matching torrent object. */
771tr_torrent * tr_torrentNew( tr_session      * session,
772                            const tr_ctor   * ctor,
773                            int             * setmeError );
774
775/** @} */
776
777/***********************************************************************
778 ***
779 ***  TORRENTS
780 **/
781
782/** @addtogroup tr_torrent Torrents
783    @{ */
784
785/** @brief Frees memory allocated by tr_torrentNew().
786           Running torrents are stopped first.  */
787void tr_torrentFree( tr_torrent * torrent );
788
789/** @brief Removes our .torrent and .resume files for
790           this torrent, then calls tr_torrentFree(). */
791void tr_torrentRemove( tr_torrent * torrent );
792
793/** @brief Start a torrent */
794void tr_torrentStart( tr_torrent * torrent );
795
796/** @brief Stop (pause) a torrent */
797void tr_torrentStop( tr_torrent * torrent );
798
799/** @brief Deletes the torrent data stored on disk. */
800void tr_torrentDeleteLocalData( tr_torrent * torrent );
801
802/**
803 * @brief Iterate through the torrents.
804 *
805 * Pass in a NULL pointer to get the first torrent.
806 */
807tr_torrent* tr_torrentNext( tr_session  * session,
808                            tr_torrent  * current );
809
810
811uint64_t tr_torrentGetBytesLeftToAllocate( const tr_torrent * torrent );
812
813/**
814 * @brief Returns this torrent's unique ID.
815 *
816 * IDs are good as simple lookup keys, but are not persistent
817 * between sessions.  If you need that, use tr_info.hash or
818 * tr_info.hashString.
819 */
820int tr_torrentId( const tr_torrent * torrent );
821
822/****
823*****  Speed Limits
824****/
825
826typedef enum
827{
828    TR_SPEEDLIMIT_GLOBAL,    /* only follow the overall speed limit */
829    TR_SPEEDLIMIT_SINGLE,    /* only follow the per-torrent limit */
830    TR_SPEEDLIMIT_UNLIMITED  /* no limits at all */
831}
832tr_speedlimit;
833
834void          tr_torrentSetSpeedMode( tr_torrent     * tor,
835                                      tr_direction     up_or_down,
836                                      tr_speedlimit    mode );
837
838tr_speedlimit tr_torrentGetSpeedMode( const tr_torrent * tor,
839                                      tr_direction       direction );
840
841void          tr_torrentSetSpeedLimit( tr_torrent    * tor,
842                                       tr_direction    up_or_down,
843                                       int             KiB_sec );
844
845int           tr_torrentGetSpeedLimit( const tr_torrent  * tor,
846                                       tr_direction        direction );
847
848/****
849*****  Peer Limits
850****/
851
852void          tr_torrentSetPeerLimit( tr_torrent * tor,
853                                      uint16_t     peerLimit );
854
855uint16_t      tr_torrentGetPeerLimit( const tr_torrent * tor );
856
857/****
858*****  File Priorities
859****/
860
861enum
862{
863    TR_PRI_LOW    = -1,
864    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
865    TR_PRI_HIGH   =  1
866};
867
868typedef int8_t tr_priority_t;
869
870/**
871 * @brief Set a batch of files to a particular priority.
872 *
873 * @param priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW
874 */
875void tr_torrentSetFilePriorities( tr_torrent       * torrent,
876                                  tr_file_index_t  * files,
877                                  tr_file_index_t    fileCount,
878                                  tr_priority_t      priority );
879
880/**
881 * @brief Get this torrent's file priorities.
882 *
883 * @return A malloc()ed array of tor->info.fileCount items,
884 *         each holding a TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
885 *         It's the caller's responsibility to free() this.
886 */
887tr_priority_t*  tr_torrentGetFilePriorities( const tr_torrent * torrent );
888
889/**
890 * @brief Single-file form of tr_torrentGetFilePriorities.
891 * @return TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
892 */
893tr_priority_t   tr_torrentGetFilePriority( const tr_torrent  * torrent,
894                                           tr_file_index_t     file );
895
896/**
897 * @brief See if a file's `download' flag is set.
898 * @return true if the file's `download' flag is set.
899 */
900int tr_torrentGetFileDL( const tr_torrent  * torrent,
901                         tr_file_index_t     file );
902
903/** @brief Set a batch of files to be downloaded or not. */
904void            tr_torrentSetFileDLs( tr_torrent       * torrent,
905                                      tr_file_index_t  * files,
906                                      tr_file_index_t    fileCount,
907                                      tr_bool            do_download );
908
909
910const tr_info * tr_torrentInfo( const tr_torrent * torrent );
911
912void tr_torrentSetDownloadDir( tr_torrent  * torrent,
913                               const char  * path );
914
915const char * tr_torrentGetDownloadDir( const tr_torrent * torrent );
916
917/**
918***
919**/
920
921typedef struct tr_tracker_info
922{
923    int     tier;
924    char *  announce;
925    char *  scrape;
926}
927tr_tracker_info;
928
929/**
930 * @brief Modify a torrent's tracker list.
931 *
932 * This updates both the `torrent' object's tracker list
933 * and the metainfo file in tr_sessionGetConfigDir()'s torrent subdirectory.
934 *
935 * @param torrent The torrent whose tracker list is to be modified
936 * @param trackers An array of trackers, sorted by tier from first to last.
937 *                 NOTE: only the `tier' and `announce' fields are used.
938 *                 libtransmission derives `scrape' from `announce'.
939 * @param trackerCount size of the `trackers' array
940 */
941void tr_torrentSetAnnounceList( tr_torrent *            torrent,
942                                const tr_tracker_info * trackers,
943                                int                     trackerCount );
944
945
946/**
947***
948**/
949
950typedef enum
951{
952    TR_LEECH,           /* doesn't have all the desired pieces */
953    TR_SEED,            /* has the entire torrent */
954    TR_PARTIAL_SEED     /* has the desired pieces, but not the entire torrent */
955}
956tr_completeness;
957
958typedef void ( tr_torrent_completeness_func )( tr_torrent       * torrent,
959                                               tr_completeness    completeness,
960                                               void             * user_data );
961
962/**
963 * Register to be notified whenever a torrent's "completeness"
964 * changes.  This will be called, for example, when a torrent
965 * finishes downloading and changes from TR_LEECH to
966 * either TR_SEED or TR_PARTIAL_SEED.
967 *
968 * func is invoked FROM LIBTRANSMISSION'S THREAD!
969 * This means func must be fast (to avoid blocking peers),
970 * shouldn't call libtransmission functions (to avoid deadlock),
971 * and shouldn't modify client-level memory without using a mutex!
972 *
973 * @see tr_completeness
974 */
975void tr_torrentSetCompletenessCallback(
976         tr_torrent                    * torrent,
977         tr_torrent_completeness_func    func,
978         void                          * user_data );
979
980void tr_torrentClearCompletenessCallback( tr_torrent * torrent );
981
982
983/**
984 * MANUAL ANNOUNCE
985 *
986 * Trackers usually set an announce interval of 15 or 30 minutes.
987 * Users can send one-time announce requests that override this
988 * interval by calling tr_torrentManualUpdate().
989 *
990 * The wait interval for tr_torrentManualUpdate() is much smaller.
991 * You can test whether or not a manual update is possible
992 * (for example, to desensitize the button) by calling
993 * tr_torrentCanManualUpdate().
994 */
995
996void tr_torrentManualUpdate( tr_torrent * torrent );
997
998int  tr_torrentCanManualUpdate( const tr_torrent * torrent );
999
1000/***********************************************************************
1001* tr_torrentPeers
1002***********************************************************************/
1003
1004typedef struct tr_peer_stat
1005{
1006    tr_bool      isEncrypted;
1007    tr_bool      isDownloadingFrom;
1008    tr_bool      isUploadingTo;
1009    tr_bool      isSeed;
1010
1011    tr_bool      peerIsChoked;
1012    tr_bool      peerIsInterested;
1013    tr_bool      clientIsChoked;
1014    tr_bool      clientIsInterested;
1015    tr_bool      isIncoming;
1016
1017    uint8_t      from;
1018    tr_port      port;
1019
1020    char         addr[TR_INET6_ADDRSTRLEN];
1021    char         client[80];
1022    char         flagStr[32];
1023
1024    float        progress;
1025    float        rateToPeer;
1026    float        rateToClient;
1027}
1028tr_peer_stat;
1029
1030tr_peer_stat * tr_torrentPeers( const tr_torrent * torrent,
1031                                int *              peerCount );
1032
1033void           tr_torrentPeersFree( tr_peer_stat * peerStats,
1034                                    int            peerCount );
1035
1036/**
1037 * @brief get the download speeds for each of this torrent's webseed sources.
1038 *
1039 * @return an array of tor->info.webseedCount floats giving download speeds.
1040 *         Each speed in the array corresponds to the webseed at the same
1041 *         array index in tor->info.webseeds.
1042 *         To differentiate "idle" and "stalled" status, idle webseeds will
1043 *         return -1 instead of 0 KiB/s.
1044 *         NOTE: always free this array with tr_free() when you're done with it.
1045 */
1046float*         tr_torrentWebSpeeds( const tr_torrent * torrent );
1047
1048typedef struct tr_file_stat
1049{
1050    uint64_t    bytesCompleted;
1051    float       progress;
1052}
1053tr_file_stat;
1054
1055tr_file_stat * tr_torrentFiles( const tr_torrent  * torrent,
1056                                tr_file_index_t   * fileCount );
1057
1058void tr_torrentFilesFree( tr_file_stat     * files,
1059                          tr_file_index_t    fileCount );
1060
1061
1062/***********************************************************************
1063 * tr_torrentAvailability
1064 ***********************************************************************
1065 * Use this to draw an advanced progress bar which is 'size' pixels
1066 * wide. Fills 'tab' which you must have allocated: each byte is set
1067 * to either -1 if we have the piece, otherwise it is set to the number
1068 * of connected peers who have the piece.
1069 **********************************************************************/
1070void tr_torrentAvailability( const tr_torrent  * torrent,
1071                             int8_t            * tab,
1072                             int                  size );
1073
1074void tr_torrentAmountFinished( const tr_torrent  * torrent,
1075                               float *             tab,
1076                               int                 size );
1077
1078void tr_torrentVerify( tr_torrent * torrent );
1079
1080/***********************************************************************
1081 * tr_info
1082 **********************************************************************/
1083
1084typedef struct tr_file
1085{
1086    uint64_t            length;    /* Length of the file, in bytes */
1087    char *              name;      /* Path to the file */
1088    int8_t              priority;  /* TR_PRI_HIGH, _NORMAL, or _LOW */
1089    int8_t              dnd;       /* nonzero if the file shouldn't be
1090                                     downloaded */
1091    tr_piece_index_t    firstPiece; /* We need pieces [firstPiece... */
1092    tr_piece_index_t    lastPiece; /* ...lastPiece] to dl this file */
1093    uint64_t            offset;    /* file begins at the torrent's nth byte */
1094}
1095tr_file;
1096
1097typedef struct tr_piece
1098{
1099    uint8_t    hash[SHA_DIGEST_LENGTH]; /* pieces hash */
1100    int8_t     priority;               /* TR_PRI_HIGH, _NORMAL, or _LOW */
1101    int8_t     dnd;                    /* nonzero if the piece shouldn't be
1102                                         downloaded */
1103}
1104tr_piece;
1105
1106struct tr_info
1107{
1108    /* Flags */
1109    tr_bool            isPrivate;
1110    tr_bool            isMultifile;
1111
1112    /* General info */
1113    uint8_t            hash[SHA_DIGEST_LENGTH];
1114    char               hashString[2 * SHA_DIGEST_LENGTH + 1];
1115    char            *  name;
1116
1117    /* Path to torrent Transmission's internal copy of the .torrent file.
1118       This field exists for compatability reasons in the Mac OS X client
1119       and should not be used in new code. */
1120    char            *  torrent;
1121
1122    /* these trackers are sorted by tier */
1123    tr_tracker_info *  trackers;
1124    int                trackerCount;
1125
1126    char           **  webseeds;
1127    int                webseedCount;
1128
1129    /* Torrent info */
1130    char             * comment;
1131    char             * creator;
1132    time_t             dateCreated;
1133
1134    /* Pieces info */
1135    uint32_t           pieceSize;
1136    tr_piece_index_t   pieceCount;
1137    uint64_t           totalSize;
1138    tr_piece *         pieces;
1139
1140    /* Files info */
1141    tr_file_index_t    fileCount;
1142    tr_file *          files;
1143};
1144
1145/**
1146 * What the torrent is doing right now.
1147 *
1148 * Note: these values will become a straight enum at some point in the future.
1149 * Do not rely on their current `bitfield' implementation
1150 */
1151typedef enum
1152{
1153    TR_STATUS_CHECK_WAIT   = ( 1 << 0 ), /* Waiting in queue to check files */
1154    TR_STATUS_CHECK        = ( 1 << 1 ), /* Checking files */
1155    TR_STATUS_DOWNLOAD     = ( 1 << 2 ), /* Downloading */
1156    TR_STATUS_SEED         = ( 1 << 3 ), /* Seeding */
1157    TR_STATUS_STOPPED      = ( 1 << 4 )  /* Torrent is stopped */
1158}
1159tr_torrent_activity;
1160
1161tr_torrent_activity tr_torrentGetActivity( tr_torrent * );
1162
1163#define TR_STATUS_IS_ACTIVE( s ) ( ( s ) != TR_STATUS_STOPPED )
1164
1165typedef enum
1166{
1167    TR_LOCKFILE_SUCCESS = 0,
1168    TR_LOCKFILE_EOPEN,
1169    TR_LOCKFILE_ELOCK
1170}
1171tr_lockfile_state_t;
1172
1173enum
1174{
1175    TR_PEER_FROM_INCOMING  = 0,  /* connections made to the listening port */
1176    TR_PEER_FROM_TRACKER   = 1,  /* peers received from a tracker */
1177    TR_PEER_FROM_CACHE     = 2,  /* peers read from the peer cache */
1178    TR_PEER_FROM_PEX       = 3,  /* peers discovered via PEX */
1179    TR_PEER_FROM__MAX
1180};
1181
1182/** Can be used as a mnemonic for "no error" errno */
1183#define TR_OK 0
1184
1185/**
1186 * The current status of a torrent.
1187 * @see tr_torrentStat()
1188 */
1189typedef struct tr_stat
1190{
1191    /** The torrent's unique Id.
1192        @see tr_torrentId() */
1193    int    id;
1194
1195    /** What is this torrent doing right now? */
1196    tr_torrent_activity activity;
1197
1198    /** Our current announce URL, or NULL if none.
1199        This URL may change during the session if the torrent's
1200        metainfo has multiple trackers and the current one
1201        becomes unreachable. */
1202    char *  announceURL;
1203
1204    /** Our current scrape URL, or NULL if none.
1205        This URL may change during the session if the torrent's
1206        metainfo has multiple trackers and the current one
1207        becomes unreachable. */
1208    char *  scrapeURL;
1209
1210    /** The errno status for this torrent.  0 means everything's fine. */
1211    int     error;
1212
1213    /** Typically an error string returned from the tracker. */
1214    char    errorString[128];
1215
1216    /** When tr_stat.status is TR_STATUS_CHECK or TR_STATUS_CHECK_WAIT,
1217        this is the percentage of how much of the files has been
1218        verified.  When it gets to 1, the verify process is done.
1219        Range is [0..1]
1220        @see tr_stat.status */
1221    float    recheckProgress;
1222
1223    /** How much has been downloaded of the entire torrent.
1224        Range is [0..1] */
1225    float    percentComplete;
1226
1227    /** How much has been downloaded of the files the user wants.  This differs
1228        from percentComplete if the user wants only some of the torrent's files.
1229        Range is [0..1]
1230        @see tr_stat.leftUntilDone */
1231    float    percentDone;
1232
1233    /** Speed all data being sent for this torrent. (KiB/s)
1234        This includes piece data, protocol messages, and TCP overhead */
1235    double rawUploadSpeed;
1236
1237    /** Speed all data being received for this torrent. (KiB/s)
1238        This includes piece data, protocol messages, and TCP overhead */
1239    double rawDownloadSpeed;
1240
1241    /** Speed all piece being sent for this torrent. (KiB/s)
1242        This ONLY counts piece data. */
1243    double pieceUploadSpeed;
1244
1245    /** Speed all piece being received for this torrent. (KiB/s)
1246        This ONLY counts piece data. */
1247    double pieceDownloadSpeed;
1248
1249#define TR_ETA_NOT_AVAIL -1
1250#define TR_ETA_UNKNOWN -2
1251    /** Estimated number of seconds left until the torrent is done,
1252        or TR_ETA_NOT_AVAIL or TR_ETA_UNKNOWN */
1253    int    eta;
1254
1255    /** Number of peers that the tracker says this torrent has */
1256    int    peersKnown;
1257
1258    /** Number of peers that we're connected to */
1259    int    peersConnected;
1260
1261    /** How many peers we found out about from the tracker, or from pex,
1262        or from incoming connections, or from our resume file. */
1263    int    peersFrom[TR_PEER_FROM__MAX];
1264
1265    /** Number of peers that are sending data to us. */
1266    int    peersSendingToUs;
1267
1268    /** Number of peers that we're sending data to */
1269    int    peersGettingFromUs;
1270
1271    /** Number of webseeds that are sending data to us. */
1272    int    webseedsSendingToUs;
1273
1274    /** Number of seeders that the tracker says this torrent has */
1275    int    seeders;
1276
1277    /** Number of leechers that the tracker says this torrent has */
1278    int    leechers;
1279
1280    /** Number of downloaders that the tracker says this torrent has.
1281        This is a new key introduced in BEP 21 and may not be supported by some trackers.
1282        If the tracker doesn't support this key, the value here will be -1. */
1283    int    downloaders;
1284
1285    /** Number of finished downloads that the tracker says torrent has */
1286    int    timesCompleted;
1287
1288    /** Byte count of all the piece data we'll have downloaded when we're done,
1289        whether or not we have it yet.  This may be less than tr_info.totalSize
1290        if only some of the torrent's files are wanted.
1291        [0...tr_info.totalSize] */
1292    uint64_t    sizeWhenDone;
1293
1294    /** Byte count of how much data is left to be downloaded until we've got
1295        all the pieces that we want.  [0...tr_info.sizeWhenDone] */
1296    uint64_t    leftUntilDone;
1297
1298    /** Byte count of all the piece data we want and don't have yet,
1299        but that a connected peer does have. [0...leftUntilDone] */
1300    uint64_t    desiredAvailable;
1301
1302    /** Byte count of all the corrupt data you've ever downloaded for
1303        this torrent.  If you're on a poisoned torrent, this number can
1304        grow very large. */
1305    uint64_t    corruptEver;
1306
1307    /** Byte count of all data you've ever uploaded for this torrent. */
1308    uint64_t    uploadedEver;
1309
1310    /** Byte count of all the non-corrupt data you've ever downloaded
1311        for this torrent.  If you deleted the files and downloaded a second
1312        time, this will be 2*totalSize.. */
1313    uint64_t    downloadedEver;
1314
1315    /** Byte count of all the checksum-verified data we have for this torrent.
1316      */
1317    uint64_t    haveValid;
1318
1319    /** Byte count of all the partial piece data we have for this torrent.
1320        As pieces become complete, this value may decrease as portions of it
1321        are moved to `corrupt' or `haveValid'. */
1322    uint64_t    haveUnchecked;
1323
1324    /** This is the unmodified string returned by the tracker in response
1325        to the torrent's most recent scrape request.  If no request was
1326        sent or there was no response, this string is empty. */
1327    char    scrapeResponse[64];
1328
1329    /** The unmodified string returned by the tracker in response
1330        to the torrent's most recent scrape request.  If no request was
1331        sent or there was no response, this string is empty. */
1332    char    announceResponse[64];
1333
1334    /** Time the most recent scrape request was sent,
1335        or zero if one hasn't been sent yet. */
1336    time_t    lastScrapeTime;
1337
1338    /** Time when the next scrape request will be sent,
1339        or 0 if an error has occured that stops scraping,
1340        or 1 if a scrape is currently in progress s.t.
1341        we haven't set a timer for the next one yet. */
1342    time_t    nextScrapeTime;
1343
1344    /** Time the most recent announce request was sent,
1345        or zero if one hasn't been sent yet. */
1346    time_t    lastAnnounceTime;
1347
1348    /** Time when the next reannounce request will be sent,
1349        or 0 if the torrent is stopped,
1350        or 1 if an announce is currently in progress s.t.
1351        we haven't set a timer for the next one yet */
1352    time_t    nextAnnounceTime;
1353
1354    /** If the torrent is running, this is the time at which
1355        the client can manually ask the torrent's tracker
1356        for more peers,
1357        or 0 if the torrent is stopped or doesn't allow manual,
1358        or 1 if an announce is currently in progress s.t.
1359        we haven't set a timer for the next one yet */
1360    time_t    manualAnnounceTime;
1361
1362    /** A very rough estimate in KiB/s of how quickly data is being
1363        passed around between all the peers we're connected to.
1364        Don't put too much weight in this number. */
1365    float    swarmSpeed;
1366
1367#define TR_RATIO_NA  -1
1368#define TR_RATIO_INF -2
1369    /** TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
1370    float    ratio;
1371
1372    /** When the torrent was first added. */
1373    time_t    addedDate;
1374
1375    /** When the torrent finished downloading. */
1376    time_t    doneDate;
1377
1378    /** When the torrent was last started. */
1379    time_t    startDate;
1380
1381    /** The last time we uploaded or downloaded piece data on this torrent. */
1382    time_t    activityDate;
1383}
1384tr_stat;
1385
1386/** Return a pointer to an tr_stat structure with updated information
1387    on the torrent.  This is typically called by the GUI clients every
1388    second or so to get a new snapshot of the torrent's status. */
1389const tr_stat * tr_torrentStat( tr_torrent * torrent );
1390
1391/** Like tr_torrentStat(), but only recalculates the statistics if it's
1392    been longer than a second since they were last calculated.  This can
1393    reduce the CPU load if you're calling tr_torrentStat() frequently. */
1394const tr_stat * tr_torrentStatCached( tr_torrent * torrent );
1395
1396/** @deprecated this method will be removed in 1.40 */
1397void tr_torrentSetAddedDate( tr_torrent * torrent,
1398                             time_t       addedDate );
1399
1400/** @deprecated this method will be removed in 1.40 */
1401void tr_torrentSetActivityDate( tr_torrent * torrent,
1402                                time_t       activityDate );
1403
1404/** @deprecated this method will be removed in 1.40 */
1405void tr_torrentSetDoneDate( tr_torrent  * torrent,
1406                            time_t        doneDate );
1407
1408/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
1409tr_bool tr_isDirection( tr_direction );
1410
1411/** @} */
1412
1413#ifdef __TRANSMISSION__
1414 #include "session.h"
1415#endif
1416
1417#ifdef __cplusplus
1418}
1419#endif
1420
1421#endif
Note: See TracBrowser for help on using the repository browser.