source: trunk/libtransmission/transmission.h @ 8254

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

(trunk) experimental support for tr_torrentSetPriority()

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