source: trunk/libtransmission/transmission.h @ 8233

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

(trunk) make it possible to #include "version.h" without having to add -I${TOP}/libtransmission/ to your CFLAGS

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