source: trunk/libtransmission/transmission.h @ 8072

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

#1276 encrypt the password to access web client interface using SHA-2

  • Property svn:keywords set to Date Rev Author Id
File size: 50.5 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 8072 2009-03-17 21:50:20Z 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
373char* tr_sessionGetRPCUsername( const tr_session * session  );
374
375void  tr_sessionSetRPCPasswordEnabled( tr_session * session,
376                                       tr_bool      isEnabled );
377
378tr_bool tr_sessionIsRPCPasswordEnabled( const tr_session * session );
379
380
381typedef enum
382{
383    TR_RPC_TORRENT_ADDED,
384    TR_RPC_TORRENT_STARTED,
385    TR_RPC_TORRENT_STOPPED,
386    TR_RPC_TORRENT_REMOVING,
387    TR_RPC_TORRENT_CHANGED, /* catch-all for the "torrent-set" rpc method */
388    TR_RPC_SESSION_CHANGED
389}
390tr_rpc_callback_type;
391
392typedef enum
393{
394    /* no special handling is needed by the caller */
395    TR_RPC_OK            = 0,
396
397    /* indicates to the caller that the client will take care of
398     * removing the torrent itself.  For example the client may
399     * need to keep the torrent alive long enough to cleanly close
400     * some resources in another thread. */
401    TR_RPC_NOREMOVE   = ( 1 << 1 )
402}
403tr_rpc_callback_status;
404
405typedef tr_rpc_callback_status (*tr_rpc_func)(tr_session          * session,
406                                              tr_rpc_callback_type  type,
407                                              struct tr_torrent   * tor_or_null,
408                                              void                * user_data );
409
410/**
411 * Register to be notified whenever something is changed via RPC,
412 * such as a torrent being added, removed, started, stopped, etc.
413 *
414 * func is invoked FROM LIBTRANSMISSION'S THREAD!
415 * This means func must be fast (to avoid blocking peers),
416 * shouldn't call libtransmission functions (to avoid deadlock),
417 * and shouldn't modify client-level memory without using a mutex!
418 */
419void tr_sessionSetRPCCallback( tr_session   * session,
420                               tr_rpc_func    func,
421                               void         * user_data );
422
423/**
424***
425**/
426
427tr_bool       tr_sessionIsProxyEnabled( const tr_session * );
428
429tr_bool       tr_sessionIsProxyAuthEnabled( const tr_session * );
430
431const char*   tr_sessionGetProxy( const tr_session * );
432
433tr_port       tr_sessionGetProxyPort( const tr_session * );
434
435tr_proxy_type tr_sessionGetProxyType( const tr_session * );
436
437const char*   tr_sessionGetProxyUsername( const tr_session * );
438
439const char*   tr_sessionGetProxyPassword( const tr_session * );
440
441void          tr_sessionSetProxyEnabled( tr_session * session,
442                                         tr_bool      isEnabled );
443
444void          tr_sessionSetProxyAuthEnabled( tr_session * session,
445                                             tr_bool      isEnabled );
446
447void          tr_sessionSetProxy( tr_session * session,
448                                  const char * proxy );
449
450void          tr_sessionSetProxyPort( tr_session * session,
451                                      tr_port      port );
452
453void          tr_sessionSetProxyType( tr_session    * session,
454                                      tr_proxy_type   proxy_type );
455
456void          tr_sessionSetProxyUsername( tr_session * session,
457                                          const char * username );
458
459void          tr_sessionSetProxyPassword( tr_session * session,
460                                          const char * password );
461
462/**
463***
464**/
465
466typedef struct tr_session_stats
467{
468    float       ratio;        /* TR_RATIO_INF, TR_RATIO_NA, or total up/down */
469    uint64_t    uploadedBytes; /* total up */
470    uint64_t    downloadedBytes; /* total down */
471    uint64_t    filesAdded;   /* number of files added */
472    uint64_t    sessionCount; /* program started N times */
473    uint64_t    secondsActive; /* how long Transmisson's been running */
474}
475tr_session_stats;
476
477/* stats from the current session. */
478void               tr_sessionGetStats( const tr_session * session,
479                                       tr_session_stats * setme );
480
481/* stats from the current and past sessions. */
482void               tr_sessionGetCumulativeStats( const tr_session * session,
483                                                 tr_session_stats * setme );
484
485void               tr_sessionClearStats( tr_session * session );
486
487/**
488 * Set whether or not torrents are allowed to do peer exchanges.
489 * PEX is always disabled in private torrents regardless of this.
490 * In public torrents, PEX is enabled by default.
491 */
492void               tr_sessionSetPexEnabled( tr_session  * session,
493                                            tr_bool       isEnabled );
494
495tr_bool            tr_sessionIsPexEnabled( const tr_session * session );
496
497void               tr_sessionSetLazyBitfieldEnabled( tr_session * session,
498                                                     tr_bool       enabled );
499
500tr_bool            tr_sessionIsLazyBitfieldEnabled( const tr_session * session );
501
502tr_encryption_mode tr_sessionGetEncryption( tr_session * session );
503
504void               tr_sessionSetEncryption( tr_session          * session,
505                                            tr_encryption_mode    mode );
506
507
508/***********************************************************************
509** Incoming Peer Connections Port
510*/
511
512void  tr_sessionSetPortForwardingEnabled( tr_session  * session,
513                                          tr_bool       enabled );
514
515tr_bool tr_sessionIsPortForwardingEnabled( const tr_session  * session );
516
517void  tr_sessionSetPeerPort( tr_session  * session,
518                             tr_port       port);
519
520tr_port tr_sessionSetPeerPortRandom( tr_session  * session );
521
522tr_port tr_sessionGetPeerPort( const tr_session * session );
523
524typedef enum
525{
526    TR_PORT_ERROR,
527    TR_PORT_UNMAPPED,
528    TR_PORT_UNMAPPING,
529    TR_PORT_MAPPING,
530    TR_PORT_MAPPED
531}
532tr_port_forwarding;
533
534tr_port_forwarding tr_sessionGetPortForwarding( const tr_session * session );
535
536int tr_sessionCountTorrents( const tr_session * session );
537
538typedef enum
539{
540    TR_CLIENT_TO_PEER = 0, TR_UP = 0,
541    TR_PEER_TO_CLIENT = 1, TR_DOWN = 1
542}
543tr_direction;
544
545void       tr_sessionSetSpeedLimitEnabled ( tr_session        * session,
546                                            tr_direction        direction,
547                                            tr_bool             isEnabled );
548
549tr_bool    tr_sessionIsSpeedLimitEnabled  ( const tr_session  * session,
550                                            tr_direction        direction );
551
552void       tr_sessionSetSpeedLimit        ( tr_session        * session,
553                                            tr_direction        direction,
554                                            int                 KiB_sec );
555
556int        tr_sessionGetSpeedLimit        ( const tr_session  * session,
557                                            tr_direction        direction );
558
559void       tr_sessionSetRatioLimited      ( tr_session        * session,
560                                            tr_bool             isEnabled );
561
562tr_bool    tr_sessionIsRatioLimited       ( const tr_session  * session);
563
564void       tr_sessionSetRatioLimit        ( tr_session        * session,
565                                            double              desiredRatio);
566
567double     tr_sessionGetRatioLimit        ( const tr_session  * session);
568
569tr_bool    tr_torrentGetSeedRatio         ( const tr_torrent * tor, double * ratio );
570
571double     tr_sessionGetRawSpeed          ( const tr_session  * session,
572                                           tr_direction         direction );
573
574double     tr_sessionGetPieceSpeed        ( const tr_session  * session,
575                                            tr_direction        direction );
576
577
578void       tr_sessionSetPeerLimit( tr_session  * session,
579                                   uint16_t      maxGlobalPeers );
580
581uint16_t   tr_sessionGetPeerLimit( const tr_session * session );
582
583void       tr_sessionSetPeerLimitPerTorrent( tr_session  * session,
584                                             uint16_t      maxGlobalPeers );
585
586uint16_t   tr_sessionGetPeerLimitPerTorrent( const tr_session * session );
587
588
589/**
590 *  Load all the torrents in tr_getTorrentDir().
591 *  This can be used at startup to kickstart all the torrents
592 *  from the previous session.
593 */
594tr_torrent ** tr_sessionLoadTorrents( tr_session  * session,
595                                      tr_ctor     * ctor,
596                                      int         * setmeCount );
597
598int tr_sessionGetActiveTorrentCount( tr_session * session );
599
600/** @} */
601
602/**
603***
604**/
605
606
607/***********************************************************************
608** Message Logging
609*/
610
611enum
612{
613    TR_MSG_ERR = 1,
614    TR_MSG_INF = 2,
615    TR_MSG_DBG = 3
616};
617void tr_setMessageLevel( int );
618
619int  tr_getMessageLevel( void );
620
621typedef struct tr_msg_list
622{
623    /* TR_MSG_ERR, TR_MSG_INF, or TR_MSG_DBG */
624    uint8_t level;
625
626    /* The line number in the source file where this message originated */
627    int line;
628
629    /* Time the message was generated */
630    time_t when;
631
632    /* The torrent associated with this message,
633     * or a module name such as "Port Forwarding" for non-torrent messages,
634     * or NULL. */
635    char *  name;
636
637    /* The message */
638    char *  message;
639
640    /* The source file where this message originated */
641    const char * file;
642
643    /* linked list of messages */
644    struct tr_msg_list * next;
645}
646tr_msg_list;
647
648void          tr_setMessageQueuing( tr_bool isEnabled );
649
650tr_bool       tr_getMessageQueuing( void );
651
652tr_msg_list * tr_getQueuedMessages( void );
653
654void          tr_freeMessageList( tr_msg_list * freeme );
655
656/** @addtogroup Blocklists
657    @{ */
658
659/**
660 * Specify a range of IPs for Transmission to block.
661 *
662 * filename must be an uncompressed ascii file,
663 * using the same format as the bluetack level1 file.
664 *
665 * libtransmission does not keep a handle to `filename'
666 * after this call returns, so the caller is free to
667 * keep or delete `filename' as it wishes.
668 * libtransmission makes its own copy of the file
669 * massaged into a format easier to search.
670 *
671 * The caller only needs to invoke this when the blocklist
672 * has changed.
673 *
674 * Passing NULL for a filename will clear the blocklist.
675 */
676int     tr_blocklistSetContent   ( tr_session       * session,
677                                   const char       * filename );
678
679int     tr_blocklistGetRuleCount ( const tr_session * session );
680
681tr_bool tr_blocklistExists       ( const tr_session * session );
682
683tr_bool tr_blocklistIsEnabled    ( const tr_session * session );
684
685void    tr_blocklistSetEnabled   ( tr_session       * session,
686                                   tr_bool            isEnabled );
687
688
689/** @} */
690
691
692/** @addtogroup tr_ctor Torrent Instantiation
693    @{
694
695    Instantiating a tr_torrent had gotten more complicated as features were
696    added.  At one point there were four functions to check metainfo and five
697    to create tr_torrent.
698
699    To remedy this, a Torrent Constructor (struct tr_ctor) has been introduced:
700    - Simplifies the API to two functions: tr_torrentParse() and tr_torrentNew()
701    - You can set the fields you want; the system sets defaults for the rest.
702    - You can specify whether or not your fields should supercede resume's.
703    - We can add new features to tr_ctor without breaking tr_torrentNew()'s API.
704
705    All the tr_ctor{Get,Set}*() functions with a return value return
706    an error number, or zero if no error occurred.
707
708    You must call one of the SetMetainfo() functions before creating
709    a torrent with a tr_ctor.  The other functions are optional.
710
711    You can reuse a single tr_ctor to create a batch of torrents --
712    just call one of the SetMetainfo() functions between each
713    tr_torrentNew() call.
714
715    Every call to tr_ctorSetMetainfo*() frees the previous metainfo.
716 */
717
718typedef enum
719{
720    TR_FALLBACK, /* indicates the ctor value should be used only
721                    in case of missing resume settings */
722
723    TR_FORCE, /* indicates the ctor value should be used
724                 regardless of what's in the resume settings */
725}
726tr_ctorMode;
727
728struct tr_benc;
729
730tr_ctor*    tr_ctorNew( const tr_session * session );
731
732void        tr_ctorFree( tr_ctor * ctor );
733
734void        tr_ctorSetDeleteSource( tr_ctor * ctor,
735                                    tr_bool   doDelete );
736
737int         tr_ctorSetMetainfo( tr_ctor *       ctor,
738                                const uint8_t * metainfo,
739                                size_t          len );
740
741int         tr_ctorSetMetainfoFromFile( tr_ctor *    ctor,
742                                        const char * filename );
743
744int         tr_ctorSetMetainfoFromHash( tr_ctor *    ctor,
745                                        const char * hashString );
746
747/** Set the maximum number of peers this torrent can connect to.
748    (Default: 50) */
749void        tr_ctorSetPeerLimit( tr_ctor *   ctor,
750                                 tr_ctorMode mode,
751                                 uint16_t    peerLimit  );
752
753/** Set the download folder for the torrent being added with this ctor.
754    @see tr_ctorSetDownloadDir()
755    @see tr_sessionInit() */
756void        tr_ctorSetDownloadDir( tr_ctor *    ctor,
757                                   tr_ctorMode  mode,
758                                   const char * directory );
759
760/** Set whether or not the torrent begins downloading/seeding when created.
761    (Default: not paused) */
762void        tr_ctorSetPaused( tr_ctor      * ctor,
763                              tr_ctorMode    mode,
764                              tr_bool        isPaused );
765
766int         tr_ctorGetPeerLimit( const tr_ctor * ctor,
767                                 tr_ctorMode     mode,
768                                 uint16_t *      setmeCount );
769
770int         tr_ctorGetPaused( const tr_ctor * ctor,
771                              tr_ctorMode     mode,
772                              tr_bool       * setmeIsPaused );
773
774int         tr_ctorGetDownloadDir( const tr_ctor  * ctor,
775                                   tr_ctorMode      mode,
776                                   const char    ** setmeDownloadDir );
777
778int         tr_ctorGetMetainfo( const tr_ctor         * ctor,
779                                const struct tr_benc ** setme );
780
781int         tr_ctorGetDeleteSource( const tr_ctor  * ctor,
782                                    tr_bool        * setmeDoDelete );
783
784/* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
785const char* tr_ctorGetSourceFile( const tr_ctor * ctor );
786
787#define TR_EINVALID     1
788#define TR_EDUPLICATE   2
789
790/**
791 * Parses the specified metainfo.
792 * Returns 0 if it parsed successfully and can be added to Transmission.
793 * Returns TR_EINVALID if it couldn't be parsed.
794 * Returns TR_EDUPLICATE if it parsed but can't be added.
795 *     "download-dir" must be set to test for TR_EDUPLICATE.
796 *
797 * If setme_info is non-NULL and parsing is successful
798 * (that is, if TR_EINVALID is not returned), then the parsed
799 * metainfo is stored in setme_info and should be freed by the
800 * caller via tr_metainfoFree().
801 */
802int tr_torrentParse( const tr_session  * session,
803                     const tr_ctor     * ctor,
804                     tr_info           * setme_info_or_NULL );
805
806/** @brief free a metainfo
807    @see tr_torrentParse */
808void tr_metainfoFree( tr_info * inf );
809
810
811/** Instantiate a single torrent.
812    @return 0 on success,
813            TR_EINVALID if the torrent couldn't be parsed, or
814            TR_EDUPLICATE if there's already a matching torrent object. */
815tr_torrent * tr_torrentNew( tr_session      * session,
816                            const tr_ctor   * ctor,
817                            int             * setmeError );
818
819/** @} */
820
821/***********************************************************************
822 ***
823 ***  TORRENTS
824 **/
825
826/** @addtogroup tr_torrent Torrents
827    @{ */
828
829/** @brief Frees memory allocated by tr_torrentNew().
830           Running torrents are stopped first.  */
831void tr_torrentFree( tr_torrent * torrent );
832
833/** @brief Removes our .torrent and .resume files for
834           this torrent, then calls tr_torrentFree(). */
835void tr_torrentRemove( tr_torrent * torrent );
836
837/** @brief Start a torrent */
838void tr_torrentStart( tr_torrent * torrent );
839
840/** @brief Stop (pause) a torrent */
841void tr_torrentStop( tr_torrent * torrent );
842
843typedef int tr_fileFunc( const char * filename );
844
845/**
846 * @brief Deletes the torrent's local data.
847 * @param torrent
848 * @param fileFunc Pass in "unlink" to destroy the files or, on platforms with
849 *                 recycle bins, pass in a function that uses it instead.
850 *                 tr_torrentDeleteLocalData() ignores fileFunc's return value.
851 */
852void tr_torrentDeleteLocalData( tr_torrent * torrent,  tr_fileFunc fileFunc );
853
854uint64_t tr_torrentGetBytesLeftToAllocate( const tr_torrent * torrent );
855
856/**
857 * @brief Returns this torrent's unique ID.
858 *
859 * IDs are good as simple lookup keys, but are not persistent
860 * between sessions.  If you need that, use tr_info.hash or
861 * tr_info.hashString.
862 */
863int tr_torrentId( const tr_torrent * torrent );
864
865/****
866*****  Speed Limits
867****/
868
869void     tr_torrentSetSpeedLimit( tr_torrent *, tr_direction, int KiB_sec );
870
871int      tr_torrentGetSpeedLimit( const tr_torrent *, tr_direction );
872
873void     tr_torrentUseSpeedLimit( tr_torrent *, tr_direction, tr_bool do_use );
874
875tr_bool  tr_torrentIsUsingSpeedLimit( const tr_torrent *, tr_direction );
876
877void     tr_torrentUseGlobalSpeedLimit( tr_torrent *, tr_direction, tr_bool do_use );
878
879tr_bool  tr_torrentIsUsingGlobalSpeedLimit ( const tr_torrent *, tr_direction );
880
881/****
882*****  Ratio Limits
883****/
884
885typedef enum
886{
887    TR_RATIOLIMIT_GLOBAL    = 0, /* follow the global settings */
888    TR_RATIOLIMIT_SINGLE    = 1, /* override the global settings, seeding until a certain ratio */
889    TR_RATIOLIMIT_UNLIMITED = 2  /* override the global settings, seeding regardless of ratio */
890}
891tr_ratiolimit;
892
893void          tr_torrentSetRatioMode( tr_torrent         * tor,
894                                      tr_ratiolimit        mode );
895
896tr_ratiolimit tr_torrentGetRatioMode( const tr_torrent   * tor );
897
898void          tr_torrentSetRatioLimit( tr_torrent        * tor,
899                                       double              ratio );
900
901double        tr_torrentGetRatioLimit( const tr_torrent  * tor );
902
903/****
904*****  Peer Limits
905****/
906
907void          tr_torrentSetPeerLimit( tr_torrent * tor,
908                                      uint16_t     peerLimit );
909
910uint16_t      tr_torrentGetPeerLimit( const tr_torrent * tor );
911
912/****
913*****  File Priorities
914****/
915
916enum
917{
918    TR_PRI_LOW    = -1,
919    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
920    TR_PRI_HIGH   =  1
921};
922
923typedef int8_t tr_priority_t;
924
925/**
926 * @brief Set a batch of files to a particular priority.
927 *
928 * @param priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW
929 */
930void tr_torrentSetFilePriorities( tr_torrent       * torrent,
931                                  tr_file_index_t  * files,
932                                  tr_file_index_t    fileCount,
933                                  tr_priority_t      priority );
934
935/**
936 * @brief Get this torrent's file priorities.
937 *
938 * @return A malloc()ed array of tor->info.fileCount items,
939 *         each holding a TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
940 *         It's the caller's responsibility to free() this.
941 */
942tr_priority_t*  tr_torrentGetFilePriorities( const tr_torrent * torrent );
943
944/**
945 * @brief Single-file form of tr_torrentGetFilePriorities.
946 * @return TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
947 */
948tr_priority_t   tr_torrentGetFilePriority( const tr_torrent  * torrent,
949                                           tr_file_index_t     file );
950
951/**
952 * @brief See if a file's `download' flag is set.
953 * @return true if the file's `download' flag is set.
954 */
955int tr_torrentGetFileDL( const tr_torrent  * torrent,
956                         tr_file_index_t     file );
957
958/** @brief Set a batch of files to be downloaded or not. */
959void            tr_torrentSetFileDLs( tr_torrent       * torrent,
960                                      tr_file_index_t  * files,
961                                      tr_file_index_t    fileCount,
962                                      tr_bool            do_download );
963
964
965const tr_info * tr_torrentInfo( const tr_torrent * torrent );
966
967void tr_torrentSetDownloadDir( tr_torrent  * torrent,
968                               const char  * path );
969
970const char * tr_torrentGetDownloadDir( const tr_torrent * torrent );
971
972/**
973***
974**/
975
976typedef struct tr_tracker_info
977{
978    int     tier;
979    char *  announce;
980    char *  scrape;
981}
982tr_tracker_info;
983
984/**
985 * @brief Modify a torrent's tracker list.
986 *
987 * This updates both the `torrent' object's tracker list
988 * and the metainfo file in tr_sessionGetConfigDir()'s torrent subdirectory.
989 *
990 * @param torrent The torrent whose tracker list is to be modified
991 * @param trackers An array of trackers, sorted by tier from first to last.
992 *                 NOTE: only the `tier' and `announce' fields are used.
993 *                 libtransmission derives `scrape' from `announce'.
994 * @param trackerCount size of the `trackers' array
995 */
996void tr_torrentSetAnnounceList( tr_torrent *            torrent,
997                                const tr_tracker_info * trackers,
998                                int                     trackerCount );
999
1000
1001/**
1002***
1003**/
1004
1005typedef enum
1006{
1007    TR_LEECH,           /* doesn't have all the desired pieces */
1008    TR_SEED,            /* has the entire torrent */
1009    TR_PARTIAL_SEED     /* has the desired pieces, but not the entire torrent */
1010}
1011tr_completeness;
1012
1013typedef void ( tr_torrent_completeness_func )( tr_torrent       * torrent,
1014                                               tr_completeness    completeness,
1015                                               void             * user_data );
1016
1017typedef void ( tr_torrent_ratio_limit_hit_func )( tr_torrent   * torrent,
1018                                                  void         * user_data );
1019
1020/**
1021 * Register to be notified whenever a torrent's "completeness"
1022 * changes.  This will be called, for example, when a torrent
1023 * finishes downloading and changes from TR_LEECH to
1024 * either TR_SEED or TR_PARTIAL_SEED.
1025 *
1026 * func is invoked FROM LIBTRANSMISSION'S THREAD!
1027 * This means func must be fast (to avoid blocking peers),
1028 * shouldn't call libtransmission functions (to avoid deadlock),
1029 * and shouldn't modify client-level memory without using a mutex!
1030 *
1031 * @see tr_completeness
1032 */
1033void tr_torrentSetCompletenessCallback(
1034         tr_torrent                    * torrent,
1035         tr_torrent_completeness_func    func,
1036         void                          * user_data );
1037
1038void tr_torrentClearCompletenessCallback( tr_torrent * torrent );
1039
1040
1041/**
1042 * Register to be notified whenever a torrent's ratio limit
1043 * has been hit. This will be called when the torrent's
1044 * ul/dl ratio has met or exceeded the designated ratio limit.
1045 *
1046 * Has the same restrictions as tr_torrentSetCompletenessCallback
1047 */
1048void tr_torrentSetRatioLimitHitCallback(
1049     tr_torrent                     * torrent,
1050     tr_torrent_ratio_limit_hit_func  func,
1051     void                           * user_data );
1052
1053void tr_torrentClearRatioLimitHitCallback( tr_torrent * torrent );
1054
1055
1056/**
1057 * MANUAL ANNOUNCE
1058 *
1059 * Trackers usually set an announce interval of 15 or 30 minutes.
1060 * Users can send one-time announce requests that override this
1061 * interval by calling tr_torrentManualUpdate().
1062 *
1063 * The wait interval for tr_torrentManualUpdate() is much smaller.
1064 * You can test whether or not a manual update is possible
1065 * (for example, to desensitize the button) by calling
1066 * tr_torrentCanManualUpdate().
1067 */
1068
1069void tr_torrentManualUpdate( tr_torrent * torrent );
1070
1071int  tr_torrentCanManualUpdate( const tr_torrent * torrent );
1072
1073/***********************************************************************
1074* tr_torrentPeers
1075***********************************************************************/
1076
1077typedef struct tr_peer_stat
1078{
1079    tr_bool      isEncrypted;
1080    tr_bool      isDownloadingFrom;
1081    tr_bool      isUploadingTo;
1082    tr_bool      isSeed;
1083
1084    tr_bool      peerIsChoked;
1085    tr_bool      peerIsInterested;
1086    tr_bool      clientIsChoked;
1087    tr_bool      clientIsInterested;
1088    tr_bool      isIncoming;
1089
1090    uint8_t      from;
1091    tr_port      port;
1092
1093    char         addr[TR_INET6_ADDRSTRLEN];
1094    char         client[80];
1095    char         flagStr[32];
1096
1097    float        progress;
1098    float        rateToPeer;
1099    float        rateToClient;
1100}
1101tr_peer_stat;
1102
1103tr_peer_stat * tr_torrentPeers( const tr_torrent * torrent,
1104                                int *              peerCount );
1105
1106void           tr_torrentPeersFree( tr_peer_stat * peerStats,
1107                                    int            peerCount );
1108
1109/**
1110 * @brief get the download speeds for each of this torrent's webseed sources.
1111 *
1112 * @return an array of tor->info.webseedCount floats giving download speeds.
1113 *         Each speed in the array corresponds to the webseed at the same
1114 *         array index in tor->info.webseeds.
1115 *         To differentiate "idle" and "stalled" status, idle webseeds will
1116 *         return -1 instead of 0 KiB/s.
1117 *         NOTE: always free this array with tr_free() when you're done with it.
1118 */
1119float*         tr_torrentWebSpeeds( const tr_torrent * torrent );
1120
1121typedef struct tr_file_stat
1122{
1123    uint64_t    bytesCompleted;
1124    float       progress;
1125}
1126tr_file_stat;
1127
1128tr_file_stat * tr_torrentFiles( const tr_torrent  * torrent,
1129                                tr_file_index_t   * fileCount );
1130
1131void tr_torrentFilesFree( tr_file_stat     * files,
1132                          tr_file_index_t    fileCount );
1133
1134
1135/***********************************************************************
1136 * tr_torrentAvailability
1137 ***********************************************************************
1138 * Use this to draw an advanced progress bar which is 'size' pixels
1139 * wide. Fills 'tab' which you must have allocated: each byte is set
1140 * to either -1 if we have the piece, otherwise it is set to the number
1141 * of connected peers who have the piece.
1142 **********************************************************************/
1143void tr_torrentAvailability( const tr_torrent  * torrent,
1144                             int8_t            * tab,
1145                             int                  size );
1146
1147void tr_torrentAmountFinished( const tr_torrent  * torrent,
1148                               float *             tab,
1149                               int                 size );
1150
1151void tr_torrentVerify( tr_torrent * torrent );
1152
1153/***********************************************************************
1154 * tr_info
1155 **********************************************************************/
1156
1157typedef struct tr_file
1158{
1159    uint64_t            length;    /* Length of the file, in bytes */
1160    char *              name;      /* Path to the file */
1161    int8_t              priority;  /* TR_PRI_HIGH, _NORMAL, or _LOW */
1162    int8_t              dnd;       /* nonzero if the file shouldn't be
1163                                     downloaded */
1164    tr_piece_index_t    firstPiece; /* We need pieces [firstPiece... */
1165    tr_piece_index_t    lastPiece; /* ...lastPiece] to dl this file */
1166    uint64_t            offset;    /* file begins at the torrent's nth byte */
1167}
1168tr_file;
1169
1170typedef struct tr_piece
1171{
1172    uint8_t    hash[SHA_DIGEST_LENGTH]; /* pieces hash */
1173    int8_t     priority;               /* TR_PRI_HIGH, _NORMAL, or _LOW */
1174    int8_t     dnd;                    /* nonzero if the piece shouldn't be
1175                                         downloaded */
1176}
1177tr_piece;
1178
1179struct tr_info
1180{
1181    /* Flags */
1182    tr_bool            isPrivate;
1183    tr_bool            isMultifile;
1184
1185    /* General info */
1186    uint8_t            hash[SHA_DIGEST_LENGTH];
1187    char               hashString[2 * SHA_DIGEST_LENGTH + 1];
1188    char            *  name;
1189
1190    /* Path to torrent Transmission's internal copy of the .torrent file.
1191       This field exists for compatability reasons in the Mac OS X client
1192       and should not be used in new code. */
1193    char            *  torrent;
1194
1195    /* these trackers are sorted by tier */
1196    tr_tracker_info *  trackers;
1197    int                trackerCount;
1198
1199    char           **  webseeds;
1200    int                webseedCount;
1201
1202    /* Torrent info */
1203    char             * comment;
1204    char             * creator;
1205    time_t             dateCreated;
1206
1207    /* Pieces info */
1208    uint32_t           pieceSize;
1209    tr_piece_index_t   pieceCount;
1210    uint64_t           totalSize;
1211    tr_piece *         pieces;
1212
1213    /* Files info */
1214    tr_file_index_t    fileCount;
1215    tr_file *          files;
1216};
1217
1218/**
1219 * What the torrent is doing right now.
1220 *
1221 * Note: these values will become a straight enum at some point in the future.
1222 * Do not rely on their current `bitfield' implementation
1223 */
1224typedef enum
1225{
1226    TR_STATUS_CHECK_WAIT   = ( 1 << 0 ), /* Waiting in queue to check files */
1227    TR_STATUS_CHECK        = ( 1 << 1 ), /* Checking files */
1228    TR_STATUS_DOWNLOAD     = ( 1 << 2 ), /* Downloading */
1229    TR_STATUS_SEED         = ( 1 << 3 ), /* Seeding */
1230    TR_STATUS_STOPPED      = ( 1 << 4 )  /* Torrent is stopped */
1231}
1232tr_torrent_activity;
1233
1234tr_torrent_activity tr_torrentGetActivity( tr_torrent * );
1235
1236#define TR_STATUS_IS_ACTIVE( s ) ( ( s ) != TR_STATUS_STOPPED )
1237
1238typedef enum
1239{
1240    TR_LOCKFILE_SUCCESS = 0,
1241    TR_LOCKFILE_EOPEN,
1242    TR_LOCKFILE_ELOCK
1243}
1244tr_lockfile_state_t;
1245
1246enum
1247{
1248    TR_PEER_FROM_INCOMING  = 0,  /* connections made to the listening port */
1249    TR_PEER_FROM_TRACKER   = 1,  /* peers received from a tracker */
1250    TR_PEER_FROM_CACHE     = 2,  /* peers read from the peer cache */
1251    TR_PEER_FROM_PEX       = 3,  /* peers discovered via PEX */
1252    TR_PEER_FROM__MAX
1253};
1254
1255/** Can be used as a mnemonic for "no error" errno */
1256#define TR_OK 0
1257
1258/**
1259 * The current status of a torrent.
1260 * @see tr_torrentStat()
1261 */
1262typedef struct tr_stat
1263{
1264    /** The torrent's unique Id.
1265        @see tr_torrentId() */
1266    int    id;
1267
1268    /** What is this torrent doing right now? */
1269    tr_torrent_activity activity;
1270
1271    /** Our current announce URL, or NULL if none.
1272        This URL may change during the session if the torrent's
1273        metainfo has multiple trackers and the current one
1274        becomes unreachable. */
1275    char *  announceURL;
1276
1277    /** Our current scrape 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 *  scrapeURL;
1282
1283    /** The errno status for this torrent.  0 means everything's fine. */
1284    int     error;
1285
1286    /** Typically an error string returned from the tracker. */
1287    char    errorString[128];
1288
1289    /** When tr_stat.status is TR_STATUS_CHECK or TR_STATUS_CHECK_WAIT,
1290        this is the percentage of how much of the files has been
1291        verified.  When it gets to 1, the verify process is done.
1292        Range is [0..1]
1293        @see tr_stat.status */
1294    float    recheckProgress;
1295
1296    /** How much has been downloaded of the entire torrent.
1297        Range is [0..1] */
1298    float    percentComplete;
1299
1300    /** How much has been downloaded of the files the user wants.  This differs
1301        from percentComplete if the user wants only some of the torrent's files.
1302        Range is [0..1]
1303        @see tr_stat.leftUntilDone */
1304    float    percentDone;
1305   
1306    /** The percentage of the actual ratio to the seed ratio.  This will be
1307        equal to 1 if the ratio is reached or the torrent is set to seed forever.
1308        Range is [0..1] */
1309    float    percentRatio;
1310
1311    /** Speed all data being sent for this torrent. (KiB/s)
1312        This includes piece data, protocol messages, and TCP overhead */
1313    double rawUploadSpeed;
1314
1315    /** Speed all data being received for this torrent. (KiB/s)
1316        This includes piece data, protocol messages, and TCP overhead */
1317    double rawDownloadSpeed;
1318
1319    /** Speed all piece being sent for this torrent. (KiB/s)
1320        This ONLY counts piece data. */
1321    double pieceUploadSpeed;
1322
1323    /** Speed all piece being received for this torrent. (KiB/s)
1324        This ONLY counts piece data. */
1325    double pieceDownloadSpeed;
1326
1327#define TR_ETA_NOT_AVAIL -1
1328#define TR_ETA_UNKNOWN -2
1329    /** If downloading, estimated number of seconds left until the torrent is done.
1330        If seeding, estimated number of seconds left until seed ratio is reached. */
1331    int    eta;
1332
1333    /** Number of peers that the tracker says this torrent has */
1334    int    peersKnown;
1335
1336    /** Number of peers that we're connected to */
1337    int    peersConnected;
1338
1339    /** How many peers we found out about from the tracker, or from pex,
1340        or from incoming connections, or from our resume file. */
1341    int    peersFrom[TR_PEER_FROM__MAX];
1342
1343    /** Number of peers that are sending data to us. */
1344    int    peersSendingToUs;
1345
1346    /** Number of peers that we're sending data to */
1347    int    peersGettingFromUs;
1348
1349    /** Number of webseeds that are sending data to us. */
1350    int    webseedsSendingToUs;
1351
1352    /** Number of seeders that the tracker says this torrent has */
1353    int    seeders;
1354
1355    /** Number of leechers that the tracker says this torrent has */
1356    int    leechers;
1357
1358    /** Number of downloaders that the tracker says this torrent has.
1359        This is a new key introduced in BEP 21 and may not be supported by some trackers.
1360        If the tracker doesn't support this key, the value here will be -1. */
1361    int    downloaders;
1362
1363    /** Number of finished downloads that the tracker says torrent has */
1364    int    timesCompleted;
1365
1366    /** Byte count of all the piece data we'll have downloaded when we're done,
1367        whether or not we have it yet.  This may be less than tr_info.totalSize
1368        if only some of the torrent's files are wanted.
1369        [0...tr_info.totalSize] */
1370    uint64_t    sizeWhenDone;
1371
1372    /** Byte count of how much data is left to be downloaded until we've got
1373        all the pieces that we want.  [0...tr_info.sizeWhenDone] */
1374    uint64_t    leftUntilDone;
1375
1376    /** Byte count of all the piece data we want and don't have yet,
1377        but that a connected peer does have. [0...leftUntilDone] */
1378    uint64_t    desiredAvailable;
1379
1380    /** Byte count of all the corrupt data you've ever downloaded for
1381        this torrent.  If you're on a poisoned torrent, this number can
1382        grow very large. */
1383    uint64_t    corruptEver;
1384
1385    /** Byte count of all data you've ever uploaded for this torrent. */
1386    uint64_t    uploadedEver;
1387
1388    /** Byte count of all the non-corrupt data you've ever downloaded
1389        for this torrent.  If you deleted the files and downloaded a second
1390        time, this will be 2*totalSize.. */
1391    uint64_t    downloadedEver;
1392
1393    /** Byte count of all the checksum-verified data we have for this torrent.
1394      */
1395    uint64_t    haveValid;
1396
1397    /** Byte count of all the partial piece data we have for this torrent.
1398        As pieces become complete, this value may decrease as portions of it
1399        are moved to `corrupt' or `haveValid'. */
1400    uint64_t    haveUnchecked;
1401
1402    /** This is the unmodified string returned by the tracker in response
1403        to the torrent's most recent scrape request.  If no request was
1404        sent or there was no response, this string is empty. */
1405    char    scrapeResponse[64];
1406
1407    /** The unmodified string returned by the tracker in response
1408        to the torrent's most recent scrape request.  If no request was
1409        sent or there was no response, this string is empty. */
1410    char    announceResponse[64];
1411
1412    /** Time the most recent scrape request was sent,
1413        or zero if one hasn't been sent yet. */
1414    time_t    lastScrapeTime;
1415
1416    /** Time when the next scrape request will be sent,
1417        or 0 if an error has occured that stops scraping,
1418        or 1 if a scrape is currently in progress s.t.
1419        we haven't set a timer for the next one yet. */
1420    time_t    nextScrapeTime;
1421
1422    /** Time the most recent announce request was sent,
1423        or zero if one hasn't been sent yet. */
1424    time_t    lastAnnounceTime;
1425
1426    /** Time when the next reannounce request will be sent,
1427        or 0 if the torrent is stopped,
1428        or 1 if an announce is currently in progress s.t.
1429        we haven't set a timer for the next one yet */
1430    time_t    nextAnnounceTime;
1431
1432    /** If the torrent is running, this is the time at which
1433        the client can manually ask the torrent's tracker
1434        for more peers,
1435        or 0 if the torrent is stopped or doesn't allow manual,
1436        or 1 if an announce is currently in progress s.t.
1437        we haven't set a timer for the next one yet */
1438    time_t    manualAnnounceTime;
1439
1440    /** A very rough estimate in KiB/s of how quickly data is being
1441        passed around between all the peers we're connected to.
1442        Don't put too much weight in this number. */
1443    float    swarmSpeed;
1444
1445#define TR_RATIO_NA  -1
1446#define TR_RATIO_INF -2
1447    /** TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
1448    float    ratio;
1449
1450    /** When the torrent was first added. */
1451    time_t    addedDate;
1452
1453    /** When the torrent finished downloading. */
1454    time_t    doneDate;
1455
1456    /** When the torrent was last started. */
1457    time_t    startDate;
1458
1459    /** The last time we uploaded or downloaded piece data on this torrent. */
1460    time_t    activityDate;
1461}
1462tr_stat;
1463
1464/** Return a pointer to an tr_stat structure with updated information
1465    on the torrent.  This is typically called by the GUI clients every
1466    second or so to get a new snapshot of the torrent's status. */
1467const tr_stat * tr_torrentStat( tr_torrent * torrent );
1468
1469/** Like tr_torrentStat(), but only recalculates the statistics if it's
1470    been longer than a second since they were last calculated.  This can
1471    reduce the CPU load if you're calling tr_torrentStat() frequently. */
1472const tr_stat * tr_torrentStatCached( tr_torrent * torrent );
1473
1474/** @deprecated this method will be removed in 1.40 */
1475void tr_torrentSetAddedDate( tr_torrent * torrent,
1476                             time_t       addedDate );
1477
1478/** @deprecated this method will be removed in 1.40 */
1479void tr_torrentSetActivityDate( tr_torrent * torrent,
1480                                time_t       activityDate );
1481
1482/** @deprecated this method will be removed in 1.40 */
1483void tr_torrentSetDoneDate( tr_torrent  * torrent,
1484                            time_t        doneDate );
1485
1486/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
1487static TR_INLINE tr_bool tr_isDirection( tr_direction d ) { return d==TR_UP || d==TR_DOWN; }
1488
1489/** @brief Sanity checker to test that a bool is TRUE or FALSE */
1490static TR_INLINE tr_bool tr_isBool( tr_bool b ) { return b==1 || b==0; }
1491
1492/** @} */
1493
1494#ifdef __cplusplus
1495}
1496#endif
1497
1498#endif
Note: See TracBrowser for help on using the repository browser.