source: trunk/libtransmission/transmission.h @ 8118

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

(trunk) add a did-the-user-do-this flag to the "alt speed toggled" callback

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