source: branches/1.5x/libtransmission/transmission.h @ 7722

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

(1.5x) sync with trunk's libtransmission bugfixes & enhancements

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