source: trunk/libtransmission/transmission.h @ 8133

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

fix oops

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