source: trunk/libtransmission/transmission.h @ 8252

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

(trunk) remove obscure macro

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