source: trunk/libtransmission/transmission.h @ 8903

Last change on this file since 8903 was 8903, checked in by charles, 12 years ago

(trunk) all this commit does is remove trailing whitespace from some c, c++, and javascript source

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