source: trunk/libtransmission/transmission.h @ 8763

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

(trunk, gtk/qt) use Monsoon's strings for encryption preferences and Deluge's system tray tooltip.

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