source: trunk/libtransmission/transmission.h @ 8021

Last change on this file since 8021 was 8021, checked in by charles, 13 years ago

(trunk) libT and gtk+ parts for #1889: per-torrent vs. global speed limit confusion

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