source: trunk/libtransmission/transmission.h @ 7988

Last change on this file since 7988 was 7988, checked in by livings124, 13 years ago

move the percent to the stop ratio into libtransmission

  • Property svn:keywords set to Date Rev Author Id
File size: 51.1 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 7988 2009-03-01 23:48:04Z livings124 $
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
875typedef enum
876{
877    TR_SPEEDLIMIT_GLOBAL,    /* only follow the overall speed limit */
878    TR_SPEEDLIMIT_SINGLE,    /* only follow the per-torrent limit */
879    TR_SPEEDLIMIT_UNLIMITED  /* no limits at all */
880}
881tr_speedlimit;
882
883typedef enum
884{
885    TR_RATIOLIMIT_GLOBAL    = 0, /* follow the global settings */
886    TR_RATIOLIMIT_SINGLE    = 1, /* override the global settings, seeding until a certain ratio */
887    TR_RATIOLIMIT_UNLIMITED = 2  /* override the global settings, seeding regardless of ratio */
888}
889tr_ratiolimit;
890
891void          tr_torrentSetSpeedMode( tr_torrent     * tor,
892                                      tr_direction     up_or_down,
893                                      tr_speedlimit    mode );
894
895tr_speedlimit tr_torrentGetSpeedMode( const tr_torrent * tor,
896                                      tr_direction       direction );
897
898void          tr_torrentSetSpeedLimit( tr_torrent    * tor,
899                                       tr_direction    up_or_down,
900                                       int             KiB_sec );
901
902int           tr_torrentGetSpeedLimit( const tr_torrent  * tor,
903                                       tr_direction        direction );
904
905void          tr_torrentSetRatioMode( tr_torrent         * tor,
906                                      tr_ratiolimit        mode );
907
908tr_ratiolimit tr_torrentGetRatioMode( const tr_torrent   * tor );
909
910void          tr_torrentSetRatioLimit( tr_torrent        * tor,
911                                       double              ratio );
912
913double        tr_torrentGetRatioLimit( const tr_torrent  * tor );
914
915/****
916*****  Peer Limits
917****/
918
919void          tr_torrentSetPeerLimit( tr_torrent * tor,
920                                      uint16_t     peerLimit );
921
922uint16_t      tr_torrentGetPeerLimit( const tr_torrent * tor );
923
924/****
925*****  File Priorities
926****/
927
928enum
929{
930    TR_PRI_LOW    = -1,
931    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
932    TR_PRI_HIGH   =  1
933};
934
935typedef int8_t tr_priority_t;
936
937/**
938 * @brief Set a batch of files to a particular priority.
939 *
940 * @param priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW
941 */
942void tr_torrentSetFilePriorities( tr_torrent       * torrent,
943                                  tr_file_index_t  * files,
944                                  tr_file_index_t    fileCount,
945                                  tr_priority_t      priority );
946
947/**
948 * @brief Get this torrent's file priorities.
949 *
950 * @return A malloc()ed array of tor->info.fileCount items,
951 *         each holding a TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
952 *         It's the caller's responsibility to free() this.
953 */
954tr_priority_t*  tr_torrentGetFilePriorities( const tr_torrent * torrent );
955
956/**
957 * @brief Single-file form of tr_torrentGetFilePriorities.
958 * @return TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
959 */
960tr_priority_t   tr_torrentGetFilePriority( const tr_torrent  * torrent,
961                                           tr_file_index_t     file );
962
963/**
964 * @brief See if a file's `download' flag is set.
965 * @return true if the file's `download' flag is set.
966 */
967int tr_torrentGetFileDL( const tr_torrent  * torrent,
968                         tr_file_index_t     file );
969
970/** @brief Set a batch of files to be downloaded or not. */
971void            tr_torrentSetFileDLs( tr_torrent       * torrent,
972                                      tr_file_index_t  * files,
973                                      tr_file_index_t    fileCount,
974                                      tr_bool            do_download );
975
976
977const tr_info * tr_torrentInfo( const tr_torrent * torrent );
978
979void tr_torrentSetDownloadDir( tr_torrent  * torrent,
980                               const char  * path );
981
982const char * tr_torrentGetDownloadDir( const tr_torrent * torrent );
983
984/**
985***
986**/
987
988typedef struct tr_tracker_info
989{
990    int     tier;
991    char *  announce;
992    char *  scrape;
993}
994tr_tracker_info;
995
996/**
997 * @brief Modify a torrent's tracker list.
998 *
999 * This updates both the `torrent' object's tracker list
1000 * and the metainfo file in tr_sessionGetConfigDir()'s torrent subdirectory.
1001 *
1002 * @param torrent The torrent whose tracker list is to be modified
1003 * @param trackers An array of trackers, sorted by tier from first to last.
1004 *                 NOTE: only the `tier' and `announce' fields are used.
1005 *                 libtransmission derives `scrape' from `announce'.
1006 * @param trackerCount size of the `trackers' array
1007 */
1008void tr_torrentSetAnnounceList( tr_torrent *            torrent,
1009                                const tr_tracker_info * trackers,
1010                                int                     trackerCount );
1011
1012
1013/**
1014***
1015**/
1016
1017typedef enum
1018{
1019    TR_LEECH,           /* doesn't have all the desired pieces */
1020    TR_SEED,            /* has the entire torrent */
1021    TR_PARTIAL_SEED     /* has the desired pieces, but not the entire torrent */
1022}
1023tr_completeness;
1024
1025typedef void ( tr_torrent_completeness_func )( tr_torrent       * torrent,
1026                                               tr_completeness    completeness,
1027                                               void             * user_data );
1028
1029typedef void ( tr_torrent_ratio_limit_hit_func )( tr_torrent   * torrent,
1030                                                  void         * user_data );
1031
1032/**
1033 * Register to be notified whenever a torrent's "completeness"
1034 * changes.  This will be called, for example, when a torrent
1035 * finishes downloading and changes from TR_LEECH to
1036 * either TR_SEED or TR_PARTIAL_SEED.
1037 *
1038 * func is invoked FROM LIBTRANSMISSION'S THREAD!
1039 * This means func must be fast (to avoid blocking peers),
1040 * shouldn't call libtransmission functions (to avoid deadlock),
1041 * and shouldn't modify client-level memory without using a mutex!
1042 *
1043 * @see tr_completeness
1044 */
1045void tr_torrentSetCompletenessCallback(
1046         tr_torrent                    * torrent,
1047         tr_torrent_completeness_func    func,
1048         void                          * user_data );
1049
1050void tr_torrentClearCompletenessCallback( tr_torrent * torrent );
1051
1052
1053/**
1054 * Register to be notified whenever a torrent's ratio limit
1055 * has been hit. This will be called when the torrent's
1056 * ul/dl ratio has met or exceeded the designated ratio limit.
1057 *
1058 * Has the same restrictions as tr_torrentSetCompletenessCallback
1059 */
1060void tr_torrentSetRatioLimitHitCallback(
1061     tr_torrent                     * torrent,
1062     tr_torrent_ratio_limit_hit_func  func,
1063     void                           * user_data );
1064
1065void tr_torrentClearRatioLimitHitCallback( tr_torrent * torrent );
1066
1067
1068/**
1069 * MANUAL ANNOUNCE
1070 *
1071 * Trackers usually set an announce interval of 15 or 30 minutes.
1072 * Users can send one-time announce requests that override this
1073 * interval by calling tr_torrentManualUpdate().
1074 *
1075 * The wait interval for tr_torrentManualUpdate() is much smaller.
1076 * You can test whether or not a manual update is possible
1077 * (for example, to desensitize the button) by calling
1078 * tr_torrentCanManualUpdate().
1079 */
1080
1081void tr_torrentManualUpdate( tr_torrent * torrent );
1082
1083int  tr_torrentCanManualUpdate( const tr_torrent * torrent );
1084
1085/***********************************************************************
1086* tr_torrentPeers
1087***********************************************************************/
1088
1089typedef struct tr_peer_stat
1090{
1091    tr_bool      isEncrypted;
1092    tr_bool      isDownloadingFrom;
1093    tr_bool      isUploadingTo;
1094    tr_bool      isSeed;
1095
1096    tr_bool      peerIsChoked;
1097    tr_bool      peerIsInterested;
1098    tr_bool      clientIsChoked;
1099    tr_bool      clientIsInterested;
1100    tr_bool      isIncoming;
1101
1102    uint8_t      from;
1103    tr_port      port;
1104
1105    char         addr[TR_INET6_ADDRSTRLEN];
1106    char         client[80];
1107    char         flagStr[32];
1108
1109    float        progress;
1110    float        rateToPeer;
1111    float        rateToClient;
1112}
1113tr_peer_stat;
1114
1115tr_peer_stat * tr_torrentPeers( const tr_torrent * torrent,
1116                                int *              peerCount );
1117
1118void           tr_torrentPeersFree( tr_peer_stat * peerStats,
1119                                    int            peerCount );
1120
1121/**
1122 * @brief get the download speeds for each of this torrent's webseed sources.
1123 *
1124 * @return an array of tor->info.webseedCount floats giving download speeds.
1125 *         Each speed in the array corresponds to the webseed at the same
1126 *         array index in tor->info.webseeds.
1127 *         To differentiate "idle" and "stalled" status, idle webseeds will
1128 *         return -1 instead of 0 KiB/s.
1129 *         NOTE: always free this array with tr_free() when you're done with it.
1130 */
1131float*         tr_torrentWebSpeeds( const tr_torrent * torrent );
1132
1133typedef struct tr_file_stat
1134{
1135    uint64_t    bytesCompleted;
1136    float       progress;
1137}
1138tr_file_stat;
1139
1140tr_file_stat * tr_torrentFiles( const tr_torrent  * torrent,
1141                                tr_file_index_t   * fileCount );
1142
1143void tr_torrentFilesFree( tr_file_stat     * files,
1144                          tr_file_index_t    fileCount );
1145
1146
1147/***********************************************************************
1148 * tr_torrentAvailability
1149 ***********************************************************************
1150 * Use this to draw an advanced progress bar which is 'size' pixels
1151 * wide. Fills 'tab' which you must have allocated: each byte is set
1152 * to either -1 if we have the piece, otherwise it is set to the number
1153 * of connected peers who have the piece.
1154 **********************************************************************/
1155void tr_torrentAvailability( const tr_torrent  * torrent,
1156                             int8_t            * tab,
1157                             int                  size );
1158
1159void tr_torrentAmountFinished( const tr_torrent  * torrent,
1160                               float *             tab,
1161                               int                 size );
1162
1163void tr_torrentVerify( tr_torrent * torrent );
1164
1165/***********************************************************************
1166 * tr_info
1167 **********************************************************************/
1168
1169typedef struct tr_file
1170{
1171    uint64_t            length;    /* Length of the file, in bytes */
1172    char *              name;      /* Path to the file */
1173    int8_t              priority;  /* TR_PRI_HIGH, _NORMAL, or _LOW */
1174    int8_t              dnd;       /* nonzero if the file shouldn't be
1175                                     downloaded */
1176    tr_piece_index_t    firstPiece; /* We need pieces [firstPiece... */
1177    tr_piece_index_t    lastPiece; /* ...lastPiece] to dl this file */
1178    uint64_t            offset;    /* file begins at the torrent's nth byte */
1179}
1180tr_file;
1181
1182typedef struct tr_piece
1183{
1184    uint8_t    hash[SHA_DIGEST_LENGTH]; /* pieces hash */
1185    int8_t     priority;               /* TR_PRI_HIGH, _NORMAL, or _LOW */
1186    int8_t     dnd;                    /* nonzero if the piece shouldn't be
1187                                         downloaded */
1188}
1189tr_piece;
1190
1191struct tr_info
1192{
1193    /* Flags */
1194    tr_bool            isPrivate;
1195    tr_bool            isMultifile;
1196
1197    /* General info */
1198    uint8_t            hash[SHA_DIGEST_LENGTH];
1199    char               hashString[2 * SHA_DIGEST_LENGTH + 1];
1200    char            *  name;
1201
1202    /* Path to torrent Transmission's internal copy of the .torrent file.
1203       This field exists for compatability reasons in the Mac OS X client
1204       and should not be used in new code. */
1205    char            *  torrent;
1206
1207    /* these trackers are sorted by tier */
1208    tr_tracker_info *  trackers;
1209    int                trackerCount;
1210
1211    char           **  webseeds;
1212    int                webseedCount;
1213
1214    /* Torrent info */
1215    char             * comment;
1216    char             * creator;
1217    time_t             dateCreated;
1218
1219    /* Pieces info */
1220    uint32_t           pieceSize;
1221    tr_piece_index_t   pieceCount;
1222    uint64_t           totalSize;
1223    tr_piece *         pieces;
1224
1225    /* Files info */
1226    tr_file_index_t    fileCount;
1227    tr_file *          files;
1228};
1229
1230/**
1231 * What the torrent is doing right now.
1232 *
1233 * Note: these values will become a straight enum at some point in the future.
1234 * Do not rely on their current `bitfield' implementation
1235 */
1236typedef enum
1237{
1238    TR_STATUS_CHECK_WAIT   = ( 1 << 0 ), /* Waiting in queue to check files */
1239    TR_STATUS_CHECK        = ( 1 << 1 ), /* Checking files */
1240    TR_STATUS_DOWNLOAD     = ( 1 << 2 ), /* Downloading */
1241    TR_STATUS_SEED         = ( 1 << 3 ), /* Seeding */
1242    TR_STATUS_STOPPED      = ( 1 << 4 )  /* Torrent is stopped */
1243}
1244tr_torrent_activity;
1245
1246tr_torrent_activity tr_torrentGetActivity( tr_torrent * );
1247
1248#define TR_STATUS_IS_ACTIVE( s ) ( ( s ) != TR_STATUS_STOPPED )
1249
1250typedef enum
1251{
1252    TR_LOCKFILE_SUCCESS = 0,
1253    TR_LOCKFILE_EOPEN,
1254    TR_LOCKFILE_ELOCK
1255}
1256tr_lockfile_state_t;
1257
1258enum
1259{
1260    TR_PEER_FROM_INCOMING  = 0,  /* connections made to the listening port */
1261    TR_PEER_FROM_TRACKER   = 1,  /* peers received from a tracker */
1262    TR_PEER_FROM_CACHE     = 2,  /* peers read from the peer cache */
1263    TR_PEER_FROM_PEX       = 3,  /* peers discovered via PEX */
1264    TR_PEER_FROM__MAX
1265};
1266
1267/** Can be used as a mnemonic for "no error" errno */
1268#define TR_OK 0
1269
1270/**
1271 * The current status of a torrent.
1272 * @see tr_torrentStat()
1273 */
1274typedef struct tr_stat
1275{
1276    /** The torrent's unique Id.
1277        @see tr_torrentId() */
1278    int    id;
1279
1280    /** What is this torrent doing right now? */
1281    tr_torrent_activity activity;
1282
1283    /** Our current announce 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 *  announceURL;
1288
1289    /** Our current scrape URL, or NULL if none.
1290        This URL may change during the session if the torrent's
1291        metainfo has multiple trackers and the current one
1292        becomes unreachable. */
1293    char *  scrapeURL;
1294
1295    /** The errno status for this torrent.  0 means everything's fine. */
1296    int     error;
1297
1298    /** Typically an error string returned from the tracker. */
1299    char    errorString[128];
1300
1301    /** When tr_stat.status is TR_STATUS_CHECK or TR_STATUS_CHECK_WAIT,
1302        this is the percentage of how much of the files has been
1303        verified.  When it gets to 1, the verify process is done.
1304        Range is [0..1]
1305        @see tr_stat.status */
1306    float    recheckProgress;
1307
1308    /** How much has been downloaded of the entire torrent.
1309        Range is [0..1] */
1310    float    percentComplete;
1311
1312    /** How much has been downloaded of the files the user wants.  This differs
1313        from percentComplete if the user wants only some of the torrent's files.
1314        Range is [0..1]
1315        @see tr_stat.leftUntilDone */
1316    float    percentDone;
1317   
1318    /** The percentage of the actual ratio to the seed ratio.  This will be
1319        equal to 1 if the ratio is reached or the torrent is set to seed forever.
1320        Range is [0..1] */
1321    float    percentRatio;
1322
1323    /** Speed all data being sent for this torrent. (KiB/s)
1324        This includes piece data, protocol messages, and TCP overhead */
1325    double rawUploadSpeed;
1326
1327    /** Speed all data being received for this torrent. (KiB/s)
1328        This includes piece data, protocol messages, and TCP overhead */
1329    double rawDownloadSpeed;
1330
1331    /** Speed all piece being sent for this torrent. (KiB/s)
1332        This ONLY counts piece data. */
1333    double pieceUploadSpeed;
1334
1335    /** Speed all piece being received for this torrent. (KiB/s)
1336        This ONLY counts piece data. */
1337    double pieceDownloadSpeed;
1338
1339#define TR_ETA_NOT_AVAIL -1
1340#define TR_ETA_UNKNOWN -2
1341    /** If downloading, estimated number of seconds left until the torrent is done.
1342        If seeding, estimated number of seconds left until seed ratio is reached. */
1343    int    eta;
1344
1345    /** Number of peers that the tracker says this torrent has */
1346    int    peersKnown;
1347
1348    /** Number of peers that we're connected to */
1349    int    peersConnected;
1350
1351    /** How many peers we found out about from the tracker, or from pex,
1352        or from incoming connections, or from our resume file. */
1353    int    peersFrom[TR_PEER_FROM__MAX];
1354
1355    /** Number of peers that are sending data to us. */
1356    int    peersSendingToUs;
1357
1358    /** Number of peers that we're sending data to */
1359    int    peersGettingFromUs;
1360
1361    /** Number of webseeds that are sending data to us. */
1362    int    webseedsSendingToUs;
1363
1364    /** Number of seeders that the tracker says this torrent has */
1365    int    seeders;
1366
1367    /** Number of leechers that the tracker says this torrent has */
1368    int    leechers;
1369
1370    /** Number of downloaders that the tracker says this torrent has.
1371        This is a new key introduced in BEP 21 and may not be supported by some trackers.
1372        If the tracker doesn't support this key, the value here will be -1. */
1373    int    downloaders;
1374
1375    /** Number of finished downloads that the tracker says torrent has */
1376    int    timesCompleted;
1377
1378    /** Byte count of all the piece data we'll have downloaded when we're done,
1379        whether or not we have it yet.  This may be less than tr_info.totalSize
1380        if only some of the torrent's files are wanted.
1381        [0...tr_info.totalSize] */
1382    uint64_t    sizeWhenDone;
1383
1384    /** Byte count of how much data is left to be downloaded until we've got
1385        all the pieces that we want.  [0...tr_info.sizeWhenDone] */
1386    uint64_t    leftUntilDone;
1387
1388    /** Byte count of all the piece data we want and don't have yet,
1389        but that a connected peer does have. [0...leftUntilDone] */
1390    uint64_t    desiredAvailable;
1391
1392    /** Byte count of all the corrupt data you've ever downloaded for
1393        this torrent.  If you're on a poisoned torrent, this number can
1394        grow very large. */
1395    uint64_t    corruptEver;
1396
1397    /** Byte count of all data you've ever uploaded for this torrent. */
1398    uint64_t    uploadedEver;
1399
1400    /** Byte count of all the non-corrupt data you've ever downloaded
1401        for this torrent.  If you deleted the files and downloaded a second
1402        time, this will be 2*totalSize.. */
1403    uint64_t    downloadedEver;
1404
1405    /** Byte count of all the checksum-verified data we have for this torrent.
1406      */
1407    uint64_t    haveValid;
1408
1409    /** Byte count of all the partial piece data we have for this torrent.
1410        As pieces become complete, this value may decrease as portions of it
1411        are moved to `corrupt' or `haveValid'. */
1412    uint64_t    haveUnchecked;
1413
1414    /** This is the unmodified string returned by the tracker in response
1415        to the torrent's most recent scrape request.  If no request was
1416        sent or there was no response, this string is empty. */
1417    char    scrapeResponse[64];
1418
1419    /** The unmodified string returned by the tracker in response
1420        to the torrent's most recent scrape request.  If no request was
1421        sent or there was no response, this string is empty. */
1422    char    announceResponse[64];
1423
1424    /** Time the most recent scrape request was sent,
1425        or zero if one hasn't been sent yet. */
1426    time_t    lastScrapeTime;
1427
1428    /** Time when the next scrape request will be sent,
1429        or 0 if an error has occured that stops scraping,
1430        or 1 if a scrape is currently in progress s.t.
1431        we haven't set a timer for the next one yet. */
1432    time_t    nextScrapeTime;
1433
1434    /** Time the most recent announce request was sent,
1435        or zero if one hasn't been sent yet. */
1436    time_t    lastAnnounceTime;
1437
1438    /** Time when the next reannounce request will be sent,
1439        or 0 if the torrent is stopped,
1440        or 1 if an announce is currently in progress s.t.
1441        we haven't set a timer for the next one yet */
1442    time_t    nextAnnounceTime;
1443
1444    /** If the torrent is running, this is the time at which
1445        the client can manually ask the torrent's tracker
1446        for more peers,
1447        or 0 if the torrent is stopped or doesn't allow manual,
1448        or 1 if an announce is currently in progress s.t.
1449        we haven't set a timer for the next one yet */
1450    time_t    manualAnnounceTime;
1451
1452    /** A very rough estimate in KiB/s of how quickly data is being
1453        passed around between all the peers we're connected to.
1454        Don't put too much weight in this number. */
1455    float    swarmSpeed;
1456
1457#define TR_RATIO_NA  -1
1458#define TR_RATIO_INF -2
1459    /** TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
1460    float    ratio;
1461
1462    /** When the torrent was first added. */
1463    time_t    addedDate;
1464
1465    /** When the torrent finished downloading. */
1466    time_t    doneDate;
1467
1468    /** When the torrent was last started. */
1469    time_t    startDate;
1470
1471    /** The last time we uploaded or downloaded piece data on this torrent. */
1472    time_t    activityDate;
1473}
1474tr_stat;
1475
1476/** Return a pointer to an tr_stat structure with updated information
1477    on the torrent.  This is typically called by the GUI clients every
1478    second or so to get a new snapshot of the torrent's status. */
1479const tr_stat * tr_torrentStat( tr_torrent * torrent );
1480
1481/** Like tr_torrentStat(), but only recalculates the statistics if it's
1482    been longer than a second since they were last calculated.  This can
1483    reduce the CPU load if you're calling tr_torrentStat() frequently. */
1484const tr_stat * tr_torrentStatCached( tr_torrent * torrent );
1485
1486/** @deprecated this method will be removed in 1.40 */
1487void tr_torrentSetAddedDate( tr_torrent * torrent,
1488                             time_t       addedDate );
1489
1490/** @deprecated this method will be removed in 1.40 */
1491void tr_torrentSetActivityDate( tr_torrent * torrent,
1492                                time_t       activityDate );
1493
1494/** @deprecated this method will be removed in 1.40 */
1495void tr_torrentSetDoneDate( tr_torrent  * torrent,
1496                            time_t        doneDate );
1497
1498/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
1499static TR_INLINE tr_bool tr_isDirection( tr_direction d ) { return d==TR_UP || d==TR_DOWN; }
1500
1501/** @brief Sanity checker to test that a bool is TRUE or FALSE */
1502static TR_INLINE tr_bool tr_isBool( tr_bool b ) { return b==1 || b==0; }
1503
1504/** @} */
1505
1506#ifdef __cplusplus
1507}
1508#endif
1509
1510#endif
Note: See TracBrowser for help on using the repository browser.