source: trunk/libtransmission/transmission.h @ 14316

Last change on this file since 14316 was 14316, checked in by livings124, 8 years ago

Use built-in _WIN32 macro instead of WIN32

  • Property svn:keywords set to Date Rev Author Id
File size: 69.3 KB
Line 
1/*
2 * This file Copyright (C) Transmission authors and contributors
3 *
4 * It may be used under the 3-Clause BSD License, the GNU Public License v2,
5 * or v3, or any future license endorsed by Mnemosyne LLC.
6 *
7 * $Id: transmission.h 14316 2014-07-04 00:00:07Z livings124 $
8 */
9
10/*
11 * This file defines the public API for the libtransmission library.
12 * The other public API headers are variant.h and utils.h;
13 * most of the remaining headers in libtransmission are private.
14 */
15
16#ifndef TR_TRANSMISSION_H
17#define TR_TRANSMISSION_H 1
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23/***
24****
25****  Basic Types
26****
27***/
28
29#include <inttypes.h> /* uintN_t */
30#include <time.h> /* time_t */
31
32#ifdef _WIN32
33 #define __USE_MINGW_ANSI_STDIO 1
34 #define __STDC_FORMAT_MACROS 1
35#endif
36
37#if !defined (__cplusplus)
38 #ifdef HAVE_STDBOOL_H
39  #include <stdbool.h>
40 #elif !defined (__bool_true_false_are_defined)
41  #define bool uint8_t
42  #define true 1
43  #define false 0
44 #endif
45#endif
46
47#ifndef PRId64
48 #ifdef _WIN32
49  #define PRId64 "I64"
50 #else
51  #define PRId64 "lld"
52 #endif
53#endif
54
55#ifndef PRIu64
56 #ifdef _WIN32
57  #define PRIu64 "I64u"
58 #else
59  #define PRIu64 "llu"
60 #endif
61#endif
62
63#ifndef PRIu32
64 #ifdef _WIN32
65  #define PRIu32 "u"
66 #else
67  #define PRIu32 "lu"
68 #endif
69#endif
70
71#ifndef TR_PRIuSIZE
72 #ifdef _MSC_VER
73  #define TR_PRIuSIZE "Iu"
74 #else
75  #define TR_PRIuSIZE "zu"
76 #endif
77#endif
78
79#if defined (_WIN32) && defined (_MSC_VER)
80 #define inline __inline
81#endif
82
83#define SHA_DIGEST_LENGTH 20
84#define TR_INET6_ADDRSTRLEN 46
85
86typedef uint32_t tr_file_index_t;
87typedef uint32_t tr_piece_index_t;
88/* assuming a 16 KiB block, a 32-bit block index gives us a maximum torrent size of 63 TiB.
89 * if we ever need to grow past that, change this to uint64_t ;) */
90typedef uint32_t tr_block_index_t;
91typedef uint16_t tr_port;
92
93typedef struct tr_ctor tr_ctor;
94typedef struct tr_info tr_info;
95typedef struct tr_torrent tr_torrent;
96typedef struct tr_session tr_session;
97
98struct tr_variant;
99
100typedef int8_t tr_priority_t;
101
102#define TR_RPC_SESSION_ID_HEADER "X-Transmission-Session-Id"
103
104typedef enum
105{
106    TR_PREALLOCATE_NONE   = 0,
107    TR_PREALLOCATE_SPARSE = 1,
108    TR_PREALLOCATE_FULL   = 2
109}
110tr_preallocation_mode;
111
112typedef enum
113{
114    TR_CLEAR_PREFERRED,
115    TR_ENCRYPTION_PREFERRED,
116    TR_ENCRYPTION_REQUIRED
117}
118tr_encryption_mode;
119
120
121/***
122****
123****  Startup & Shutdown
124****
125***/
126
127/**
128 * @addtogroup tr_session Session
129 *
130 * A libtransmission session is created by calling tr_sessionInit ().
131 * libtransmission creates a thread for itself so that it can operate
132 * independently of the caller's event loop. The session will continue
133 * until tr_sessionClose () is called.
134 *
135 * @{
136 */
137
138/**
139 * @brief returns Transmission's default configuration file directory.
140 *
141 * The default configuration directory is determined this way:
142 * -# If the TRANSMISSION_HOME environment variable is set, its value is used.
143 * -# On Darwin, "${HOME}/Library/Application Support/${appname}" is used.
144 * -# On Windows, "${CSIDL_APPDATA}/${appname}" is used.
145 * -# If XDG_CONFIG_HOME is set, "${XDG_CONFIG_HOME}/${appname}" is used.
146 * -# ${HOME}/.config/${appname}" is used as a last resort.
147 */
148const char* tr_getDefaultConfigDir (const char * appname);
149
150/**
151 * @brief returns Transmisson's default download directory.
152 *
153 * The default download directory is determined this way:
154 * -# If the HOME environment variable is set, "${HOME}/Downloads" is used.
155 * -# On Windows, "${CSIDL_MYDOCUMENTS}/Downloads" is used.
156 * -# Otherwise, getpwuid (getuid ())->pw_dir + "/Downloads" is used.
157 */
158const char* tr_getDefaultDownloadDir (void);
159
160
161#define TR_DEFAULT_BIND_ADDRESS_IPV4        "0.0.0.0"
162#define TR_DEFAULT_BIND_ADDRESS_IPV6             "::"
163#define TR_DEFAULT_RPC_WHITELIST          "127.0.0.1"
164#define TR_DEFAULT_RPC_PORT_STR                "9091"
165#define TR_DEFAULT_RPC_URL_STR       "/transmission/"
166#define TR_DEFAULT_PEER_PORT_STR              "51413"
167#define TR_DEFAULT_PEER_SOCKET_TOS_STR      "default"
168#define TR_DEFAULT_PEER_LIMIT_GLOBAL_STR        "200"
169#define TR_DEFAULT_PEER_LIMIT_TORRENT_STR        "50"
170
171/**
172 * Add libtransmission's default settings to the benc dictionary.
173 *
174 * Example:
175 * @code
176 *     tr_variant settings;
177 *     int64_t i;
178 *
179 *     tr_variantInitDict (&settings, 0);
180 *     tr_sessionGetDefaultSettings (&settings);
181 *     if (tr_variantDictFindInt (&settings, TR_PREFS_KEY_PEER_PORT, &i))
182 *         fprintf (stderr, "the default peer port is %d\n", (int)i);
183 *     tr_variantFree (&settings);
184 * @endcode
185 *
186 * @param initme pointer to a tr_variant dictionary
187 * @see tr_sessionLoadSettings ()
188 * @see tr_sessionInit ()
189 * @see tr_getDefaultConfigDir ()
190 */
191void tr_sessionGetDefaultSettings (struct tr_variant * dictionary);
192
193/**
194 * Add the session's current configuration settings to the benc dictionary.
195 *
196 * FIXME: this probably belongs in libtransmissionapp
197 *
198 * @param session
199 * @param dictionary
200 * @see tr_sessionGetDefaultSettings ()
201 */
202void tr_sessionGetSettings (tr_session *, struct tr_variant * dictionary);
203
204/**
205 * Load settings from the configuration directory's settings.json file,
206 * using libtransmission's default settings as fallbacks for missing keys.
207 *
208 * FIXME: this belongs in libtransmissionapp
209 *
210 * @param dictionary pointer to an uninitialized tr_variant
211 * @param configDir the configuration directory to find settings.json
212 * @param appName if configDir is empty, appName is used to find the default dir.
213 * @return success true if the settings were loaded, false otherwise
214 * @see tr_sessionGetDefaultSettings ()
215 * @see tr_sessionInit ()
216 * @see tr_sessionSaveSettings ()
217 */
218bool tr_sessionLoadSettings (struct tr_variant  * dictionary,
219                             const char         * configDir,
220                             const char         * appName);
221
222/**
223 * Add the session's configuration settings to the benc dictionary
224 * and save it to the configuration directory's settings.json file.
225 *
226 * FIXME: this belongs in libtransmissionapp
227 *
228 * @param session
229 * @param dictionary
230 * @see tr_sessionLoadSettings ()
231 */
232void tr_sessionSaveSettings (tr_session              * session,
233                             const char              * configDir,
234                             const struct tr_variant * dictonary);
235
236/**
237 * @brief Initialize a libtransmission session.
238 *
239 * For example, this will instantiate a session with all the default values:
240 * @code
241 *     tr_variant settings;
242 *     tr_session * session;
243 *     const char * configDir;
244 *
245 *     tr_variantInitDict (&settings, 0);
246 *     tr_sessionGetDefaultSettings (&settings);
247 *     configDir = tr_getDefaultConfigDir ("Transmission");
248 *     session = tr_sessionInit ("mac", configDir, true, &settings);
249 *
250 *     tr_variantFree (&settings);
251 * @endcode
252 *
253 * @param tag "gtk", "macosx", "daemon", etc... this is only for pre-1.30 resume files
254 * @param configDir where Transmission will look for resume files, blocklists, etc.
255 * @param messageQueueingEnabled if false, messages will be dumped to stderr
256 * @param settings libtransmission settings
257 * @see tr_sessionGetDefaultSettings ()
258 * @see tr_sessionLoadSettings ()
259 * @see tr_getDefaultConfigDir ()
260 */
261tr_session * tr_sessionInit (const char        * tag,
262                             const char        * configDir,
263                             bool                messageQueueingEnabled,
264                             struct tr_variant * settings);
265
266/** @brief Update a session's settings from a benc dictionary
267           like to the one used in tr_sessionInit () */
268void tr_sessionSet (tr_session         * session,
269                    struct tr_variant  * settings);
270
271/** @brief Rescan the blocklists directory and
272           reload whatever blocklist files are found there */
273void tr_sessionReloadBlocklists (tr_session * session);
274
275
276/** @brief End a libtransmission session
277    @see tr_sessionInit () */
278void tr_sessionClose (tr_session *);
279
280/**
281 * @brief Return the session's configuration directory.
282 *
283 * This is where transmission stores its .torrent files, .resume files,
284 * blocklists, etc. It's set in tr_transmissionInit () and is immutable
285 * during the session.
286 */
287const char * tr_sessionGetConfigDir (const tr_session *);
288
289/**
290 * @brief Set the per-session default download folder for new torrents.
291 * @see tr_sessionInit ()
292 * @see tr_sessionGetDownloadDir ()
293 * @see tr_ctorSetDownloadDir ()
294 */
295void tr_sessionSetDownloadDir (tr_session * session, const char * downloadDir);
296
297/**
298 * @brief Get the default download folder for new torrents.
299 *
300 * This is set by tr_sessionInit () or tr_sessionSetDownloadDir (),
301 * and can be overridden on a per-torrent basis by tr_ctorSetDownloadDir ().
302 */
303const char * tr_sessionGetDownloadDir (const tr_session * session);
304
305/**
306 * @brief Get available disk space (in bytes) for the specified directory.
307 * @return zero or positive integer on success, -1 in case of error.
308 */
309int64_t tr_sessionGetDirFreeSpace (tr_session * session, const char * dir);
310
311/**
312 * @brief Set the torrent's bandwidth priority.
313 */
314void tr_ctorSetBandwidthPriority (tr_ctor * ctor, tr_priority_t priority);
315
316/**
317 * @brief Get the torrent's bandwidth priority.
318 */
319tr_priority_t tr_ctorGetBandwidthPriority (const tr_ctor * ctor);
320
321
322/**
323 * @brief set the per-session incomplete download folder.
324 *
325 * When you add a new torrent and the session's incomplete directory is enabled,
326 * the new torrent will start downloading into that directory, and then be moved
327 * to tr_torrent.downloadDir when the torrent is finished downloading.
328 *
329 * Torrents aren't moved as a result of changing the session's incomplete dir --
330 * it's applied to new torrents, not existing ones.
331 *
332 * tr_torrentSetLocation () overrules the incomplete dir: when a user specifies
333 * a new location, that becomes the torrent's new downloadDir and the torrent
334 * is moved there immediately regardless of whether or not it's complete.
335 *
336 * @see tr_sessionInit ()
337 * @see tr_sessionGetIncompleteDir ()
338 * @see tr_sessionSetIncompleteDirEnabled ()
339 * @see tr_sessionGetIncompleteDirEnabled ()
340 */
341void tr_sessionSetIncompleteDir (tr_session * session, const char * dir);
342
343/** @brief get the per-session incomplete download folder */
344const char* tr_sessionGetIncompleteDir (const tr_session * session);
345
346/** @brief enable or disable use of the incomplete download folder */
347void tr_sessionSetIncompleteDirEnabled (tr_session * session, bool);
348
349/** @brief get whether or not the incomplete download folder is enabled */
350bool tr_sessionIsIncompleteDirEnabled (const tr_session * session);
351
352
353/**
354 * @brief When enabled, newly-created files will have ".part" appended
355 *        to their filename until the file is fully downloaded
356 *
357 * This is not retroactive -- toggling this will not rename existing files.
358 * It only applies to new files created by Transmission after this API call.
359 *
360 * @see tr_sessionIsIncompleteFileNamingEnabled ()
361 */
362void tr_sessionSetIncompleteFileNamingEnabled (tr_session * session, bool);
363
364/** @brief return true if files will end in ".part" until they're complete */
365bool tr_sessionIsIncompleteFileNamingEnabled (const tr_session * session);
366
367/**
368 * @brief Set whether or not RPC calls are allowed in this session.
369 *
370 * @details If true, libtransmission will open a server socket to listen
371 * for incoming http RPC requests as described in docs/rpc-spec.txt.
372 *
373 * This is intially set by tr_sessionInit () and can be
374 * queried by tr_sessionIsRPCEnabled ().
375 */
376void tr_sessionSetRPCEnabled (tr_session  * session,
377                              bool          isEnabled);
378
379/** @brief Get whether or not RPC calls are allowed in this session.
380    @see tr_sessionInit ()
381    @see tr_sessionSetRPCEnabled () */
382bool tr_sessionIsRPCEnabled (const tr_session * session);
383
384/** @brief Specify which port to listen for RPC requests on.
385    @see tr_sessionInit ()
386    @see tr_sessionGetRPCPort */
387void tr_sessionSetRPCPort (tr_session  * session,
388                           tr_port       port);
389
390/** @brief Get which port to listen for RPC requests on.
391    @see tr_sessionInit ()
392    @see tr_sessionSetRPCPort */
393tr_port tr_sessionGetRPCPort (const tr_session * session);
394
395/**
396 * @brief Specify which base URL to use.
397 *
398 * @detail The RPC API is accessible under <url>/rpc, the web interface under
399 * <url>/web.
400 *
401 *  @see tr_sessionGetRPCUrl
402 */
403void tr_sessionSetRPCUrl (tr_session  * session,
404                          const char * url);
405
406/**
407 * @brief Get the base URL.
408 * @see tr_sessionInit ()
409 * @see tr_sessionSetRPCUrl
410 */
411const char* tr_sessionGetRPCUrl (const tr_session * session);
412
413/**
414 * @brief Specify a whitelist for remote RPC access
415 *
416 * The whitelist is a comma-separated list of dotted-quad IP addresses
417 * to be allowed. Wildmat notation is supported, meaning that
418 * '?' is interpreted as a single-character wildcard and
419 * '*' is interprted as a multi-character wildcard.
420 */
421void   tr_sessionSetRPCWhitelist (tr_session * session,
422                                  const char * whitelist);
423
424/** @brief get the Access Control List for allowing/denying RPC requests.
425    @return a comma-separated string of whitelist domains.
426    @see tr_sessionInit
427    @see tr_sessionSetRPCWhitelist */
428const char* tr_sessionGetRPCWhitelist (const tr_session *);
429
430void  tr_sessionSetRPCWhitelistEnabled (tr_session * session,
431                                        bool         isEnabled);
432
433bool tr_sessionGetRPCWhitelistEnabled (const tr_session * session);
434
435void  tr_sessionSetRPCPassword (tr_session * session,
436                                const char * password);
437
438void  tr_sessionSetRPCUsername (tr_session * session,
439                                const char * username);
440
441/** @brief get the password used to restrict RPC requests.
442    @return the password string.
443    @see tr_sessionInit ()
444    @see tr_sessionSetRPCPassword () */
445const char* tr_sessionGetRPCPassword (const tr_session * session);
446
447const char* tr_sessionGetRPCUsername (const tr_session * session);
448
449void  tr_sessionSetRPCPasswordEnabled (tr_session * session,
450                                       bool         isEnabled);
451
452bool tr_sessionIsRPCPasswordEnabled (const tr_session * session);
453
454const char* tr_sessionGetRPCBindAddress (const tr_session * session);
455
456
457typedef enum
458{
459    TR_RPC_TORRENT_ADDED,
460    TR_RPC_TORRENT_STARTED,
461    TR_RPC_TORRENT_STOPPED,
462    TR_RPC_TORRENT_REMOVING,
463    TR_RPC_TORRENT_TRASHING, /* _REMOVING + delete local data */
464    TR_RPC_TORRENT_CHANGED, /* catch-all for the "torrent-set" rpc method */
465    TR_RPC_TORRENT_MOVED,
466    TR_RPC_SESSION_CHANGED,
467    TR_RPC_SESSION_QUEUE_POSITIONS_CHANGED, /* catch potentially multiple torrents being moved in the queue */
468    TR_RPC_SESSION_CLOSE
469}
470tr_rpc_callback_type;
471
472typedef enum
473{
474    /* no special handling is needed by the caller */
475    TR_RPC_OK            = 0,
476
477    /* indicates to the caller that the client will take care of
478     * removing the torrent itself. For example the client may
479     * need to keep the torrent alive long enough to cleanly close
480     * some resources in another thread. */
481    TR_RPC_NOREMOVE   = (1 << 1)
482}
483tr_rpc_callback_status;
484
485typedef tr_rpc_callback_status (*tr_rpc_func)(tr_session          * session,
486                                              tr_rpc_callback_type  type,
487                                              struct tr_torrent   * tor_or_null,
488                                              void                * user_data);
489
490/**
491 * Register to be notified whenever something is changed via RPC,
492 * such as a torrent being added, removed, started, stopped, etc.
493 *
494 * func is invoked FROM LIBTRANSMISSION'S THREAD!
495 * This means func must be fast (to avoid blocking peers),
496 * shouldn't call libtransmission functions (to avoid deadlock),
497 * and shouldn't modify client-level memory without using a mutex!
498 */
499void tr_sessionSetRPCCallback (tr_session   * session,
500                               tr_rpc_func    func,
501                               void         * user_data);
502
503/**
504***
505**/
506
507/** @brief Used by tr_sessionGetStats () and tr_sessionGetCumulativeStats () */
508typedef struct tr_session_stats
509{
510    float       ratio;        /* TR_RATIO_INF, TR_RATIO_NA, or total up/down */
511    uint64_t    uploadedBytes; /* total up */
512    uint64_t    downloadedBytes; /* total down */
513    uint64_t    filesAdded;   /* number of files added */
514    uint64_t    sessionCount; /* program started N times */
515    uint64_t    secondsActive; /* how long Transmisson's been running */
516}
517tr_session_stats;
518
519/** @brief Get bandwidth use statistics for the current session */
520void tr_sessionGetStats (const tr_session * session,
521                         tr_session_stats * setme);
522
523/** @brief Get cumulative bandwidth statistics for current and past sessions */
524void tr_sessionGetCumulativeStats (const tr_session * session,
525                                   tr_session_stats * setme);
526
527void tr_sessionClearStats (tr_session * session);
528
529/**
530 * @brief Set whether or not torrents are allowed to do peer exchanges.
531 *
532 * PEX is always disabled in private torrents regardless of this.
533 * In public torrents, PEX is enabled by default.
534 */
535void  tr_sessionSetPexEnabled (tr_session  * session, bool isEnabled);
536bool  tr_sessionIsPexEnabled (const tr_session * session);
537
538bool  tr_sessionIsDHTEnabled (const tr_session * session);
539void  tr_sessionSetDHTEnabled (tr_session * session, bool);
540
541bool  tr_sessionIsUTPEnabled (const tr_session * session);
542void  tr_sessionSetUTPEnabled (tr_session * session, bool);
543
544bool  tr_sessionIsLPDEnabled (const tr_session * session);
545void  tr_sessionSetLPDEnabled (tr_session * session, bool enabled);
546
547void  tr_sessionSetCacheLimit_MB (tr_session * session, int mb);
548int   tr_sessionGetCacheLimit_MB (const tr_session * session);
549
550tr_encryption_mode tr_sessionGetEncryption (tr_session * session);
551void               tr_sessionSetEncryption (tr_session * session,
552                                            tr_encryption_mode    mode);
553
554
555/***********************************************************************
556** Incoming Peer Connections Port
557*/
558
559void  tr_sessionSetPortForwardingEnabled (tr_session  * session,
560                                          bool          enabled);
561
562bool tr_sessionIsPortForwardingEnabled (const tr_session  * session);
563
564void  tr_sessionSetPeerPort (tr_session  * session,
565                             tr_port       port);
566
567tr_port tr_sessionGetPeerPort (const tr_session * session);
568
569tr_port tr_sessionSetPeerPortRandom (tr_session  * session);
570
571void  tr_sessionSetPeerPortRandomOnStart (tr_session * session, bool random);
572
573bool  tr_sessionGetPeerPortRandomOnStart (tr_session * session);
574
575typedef enum
576{
577    TR_PORT_ERROR,
578    TR_PORT_UNMAPPED,
579    TR_PORT_UNMAPPING,
580    TR_PORT_MAPPING,
581    TR_PORT_MAPPED
582}
583tr_port_forwarding;
584
585tr_port_forwarding tr_sessionGetPortForwarding (const tr_session * session);
586
587typedef enum
588{
589    TR_CLIENT_TO_PEER = 0, TR_UP = 0,
590    TR_PEER_TO_CLIENT = 1, TR_DOWN = 1
591}
592tr_direction;
593
594/***
595****
596***/
597
598/***
599****  Primary session speed limits
600***/
601
602void         tr_sessionSetSpeedLimit_KBps (tr_session *, tr_direction, unsigned int KBps);
603unsigned int tr_sessionGetSpeedLimit_KBps (const tr_session *, tr_direction);
604
605void  tr_sessionLimitSpeed       (tr_session *, tr_direction, bool);
606bool  tr_sessionIsSpeedLimited   (const tr_session *, tr_direction);
607
608
609/***
610****  Alternative speed limits that are used during scheduled times
611***/
612
613void         tr_sessionSetAltSpeed_KBps (tr_session *, tr_direction, unsigned int Bps);
614unsigned int tr_sessionGetAltSpeed_KBps (const tr_session *, tr_direction);
615
616void     tr_sessionUseAltSpeed      (tr_session *, bool);
617bool     tr_sessionUsesAltSpeed     (const tr_session *);
618
619void     tr_sessionUseAltSpeedTime  (tr_session *, bool);
620bool  tr_sessionUsesAltSpeedTime    (const tr_session *);
621
622void     tr_sessionSetAltSpeedBegin (tr_session *, int minsSinceMidnight);
623int      tr_sessionGetAltSpeedBegin (const tr_session *);
624
625void     tr_sessionSetAltSpeedEnd   (tr_session *, int minsSinceMidnight);
626int      tr_sessionGetAltSpeedEnd   (const tr_session *);
627
628typedef enum
629{
630    TR_SCHED_SUN      = (1<<0),
631    TR_SCHED_MON      = (1<<1),
632    TR_SCHED_TUES     = (1<<2),
633    TR_SCHED_WED      = (1<<3),
634    TR_SCHED_THURS    = (1<<4),
635    TR_SCHED_FRI      = (1<<5),
636    TR_SCHED_SAT      = (1<<6),
637    TR_SCHED_WEEKDAY  = (TR_SCHED_MON|TR_SCHED_TUES|TR_SCHED_WED|
638                         TR_SCHED_THURS|TR_SCHED_FRI),
639    TR_SCHED_WEEKEND  = (TR_SCHED_SUN|TR_SCHED_SAT),
640    TR_SCHED_ALL      = (TR_SCHED_WEEKDAY|TR_SCHED_WEEKEND)
641}
642tr_sched_day;
643
644void         tr_sessionSetAltSpeedDay (tr_session *, tr_sched_day day);
645tr_sched_day tr_sessionGetAltSpeedDay (const tr_session *);
646
647typedef void (*tr_altSpeedFunc)(tr_session *,
648                                  bool active,
649                                  bool userDriven,
650                                  void *);
651
652void  tr_sessionClearAltSpeedFunc (tr_session *);
653void  tr_sessionSetAltSpeedFunc  (tr_session *, tr_altSpeedFunc, void *);
654
655
656bool  tr_sessionGetActiveSpeedLimit_KBps (const tr_session  * session,
657                                          tr_direction        dir,
658                                          double            * setme);
659
660/***
661****
662***/
663
664double     tr_sessionGetRawSpeed_KBps (const tr_session *, tr_direction);
665
666void       tr_sessionSetRatioLimited (tr_session *, bool isLimited);
667bool       tr_sessionIsRatioLimited (const tr_session *);
668
669void       tr_sessionSetRatioLimit  (tr_session *, double desiredRatio);
670double     tr_sessionGetRatioLimit  (const tr_session *);
671
672void       tr_sessionSetIdleLimited (tr_session *, bool isLimited);
673bool       tr_sessionIsIdleLimited (const tr_session *);
674
675void       tr_sessionSetIdleLimit (tr_session *, uint16_t idleMinutes);
676uint16_t   tr_sessionGetIdleLimit (const tr_session *);
677
678void       tr_sessionSetPeerLimit (tr_session *, uint16_t maxGlobalPeers);
679uint16_t   tr_sessionGetPeerLimit (const tr_session *);
680
681void       tr_sessionSetPeerLimitPerTorrent (tr_session *, uint16_t maxPeers);
682uint16_t   tr_sessionGetPeerLimitPerTorrent (const tr_session *);
683
684void       tr_sessionSetPaused      (tr_session *, bool isPaused);
685bool       tr_sessionGetPaused      (const tr_session *);
686
687void       tr_sessionSetDeleteSource (tr_session *, bool deleteSource);
688bool       tr_sessionGetDeleteSource (const tr_session *);
689
690tr_priority_t   tr_torrentGetPriority (const tr_torrent *);
691void            tr_torrentSetPriority (tr_torrent *, tr_priority_t);
692
693/***
694****
695****  Torrent Queueing
696****
697****  There are independent queues for seeding (TR_UP) and leeching (TR_DOWN).
698****
699****  If the session already has enough non-stalled seeds/leeches when
700****  tr_torrentStart () is called, the torrent will be moved into the
701****  appropriate queue and its state will be TR_STATUS_{DOWNLOAD,SEED}_WAIT.
702****
703****  To bypass the queue and unconditionally start the torrent use
704****  tr_torrentStartNow ().
705****
706****  Torrents can be moved in the queue using the simple functions
707****  tr_torrentQueueMove{Top,Up,Down,Bottom}. They can be moved to
708****  arbitrary points in the queue with tr_torrentSetQueuePosition ().
709****
710***/
711
712
713/** @brief Like tr_torrentStart (), but resumes right away regardless of the queues. */
714void tr_torrentStartNow       (tr_torrent *);
715
716/** @brief Return the queued torrent's position in the queue it's in. [0...n) */
717int  tr_torrentGetQueuePosition (const tr_torrent *);
718
719/** @brief Set the queued torrent's position in the queue it's in.
720 * Special cases: pos <= 0 moves to the front; pos >= queue length moves to the back */
721void tr_torrentSetQueuePosition (tr_torrent *, int queuePosition);
722
723/**
724**/
725
726/** @brief Convenience function for moving a batch of torrents to the front of their queue (s) */
727void tr_torrentsQueueMoveTop  (tr_torrent ** torrents, int torrentCount);
728
729/** @brief Convenience function for moving a batch of torrents ahead one step in their queue (s) */
730void tr_torrentsQueueMoveUp   (tr_torrent ** torrents, int torrentCount);
731
732/** @brief Convenience function for moving a batch of torrents back one step in their queue (s) */
733void tr_torrentsQueueMoveDown (tr_torrent ** torrents, int torrentCount);
734
735/** @brief Convenience function for moving a batch of torrents to the back of their queue (s) */
736void tr_torrentsQueueMoveBottom (tr_torrent ** torrents, int torrentCount);
737
738/**
739**/
740
741/** @brief Set the number of torrents allowed to download (if direction is TR_DOWN) or seed (if direction is TR_UP) at the same time */
742void tr_sessionSetQueueSize   (tr_session *, tr_direction, int max_simultaneous_seed_torrents);
743
744/** @brief Return the number of torrents allowed to download (if direction is TR_DOWN) or seed (if direction is TR_UP) at the same time */
745int  tr_sessionGetQueueSize   (const tr_session *, tr_direction);
746
747/** @brief Set whether or not to limit how many torrents can download (TR_DOWN) or seed (TR_UP) at the same time  */
748void tr_sessionSetQueueEnabled (tr_session *, tr_direction, bool do_limit_simultaneous_seed_torrents);
749
750/** @brief Return true if we're limiting how many torrents can concurrently download (TR_DOWN) or seed (TR_UP) at the same time */
751bool tr_sessionGetQueueEnabled (const tr_session *, tr_direction);
752
753/**
754**/
755
756/** @brief Consider torrent as 'stalled' when it's been inactive for N minutes.
757    Stalled torrents are left running but are not counted by tr_sessionGetQueueSize (). */
758void tr_sessionSetQueueStalledMinutes (tr_session *, int minutes);
759
760/** @return the number of minutes a torrent can be idle before being considered as stalled */
761int  tr_sessionGetQueueStalledMinutes (const tr_session *);
762
763/** @brief Set whether or not to count torrents idle for over N minutes as 'stalled' */
764void tr_sessionSetQueueStalledEnabled (tr_session *, bool);
765
766/** @return true if we're torrents idle for over N minutes will be flagged as 'stalled' */
767bool tr_sessionGetQueueStalledEnabled (const tr_session *);
768
769/**
770**/
771
772/** @brief Set a callback that is invoked when the queue starts a torrent */
773void tr_torrentSetQueueStartCallback (tr_torrent * torrent, void (*callback)(tr_torrent *, void *), void * user_data);
774
775
776/***
777****
778****
779***/
780
781/**
782 *  Load all the torrents in tr_getTorrentDir ().
783 *  This can be used at startup to kickstart all the torrents
784 *  from the previous session.
785 */
786tr_torrent ** tr_sessionLoadTorrents (tr_session  * session,
787                                      tr_ctor     * ctor,
788                                      int         * setmeCount);
789
790/**
791***
792**/
793
794bool tr_sessionIsTorrentDoneScriptEnabled (const tr_session *);
795
796void tr_sessionSetTorrentDoneScriptEnabled (tr_session *, bool isEnabled);
797
798const char * tr_sessionGetTorrentDoneScript (const tr_session *);
799
800void tr_sessionSetTorrentDoneScript (tr_session *, const char * scriptFilename);
801
802
803/** @} */
804
805/**
806***
807**/
808
809
810/***********************************************************************
811** Message Logging
812*/
813
814typedef enum
815{
816  TR_LOG_ERROR    = 1,
817  TR_LOG_INFO     = 2,
818  TR_LOG_DEBUG    = 3,
819  TR_LOG_FIREHOSE = 4
820}
821tr_log_level;
822
823void tr_logSetLevel (tr_log_level);
824
825typedef struct tr_log_message
826{
827  /* TR_LOG_ERROR, TR_LOG_INFO, or TR_LOG_DEBUG */
828  tr_log_level level;
829
830  /* The line number in the source file where this message originated */
831  int line;
832
833  /* Time the message was generated */
834  time_t when;
835
836  /* The torrent associated with this message,
837   * or a module name such as "Port Forwarding" for non-torrent messages,
838   * or NULL. */
839  char * name;
840
841  /* The message */
842  char *  message;
843
844  /* The source file where this message originated */
845  const char * file;
846
847  /* linked list of messages */
848  struct tr_log_message * next;
849}
850tr_log_message;
851
852tr_log_message * tr_logGetQueue        (void);
853bool             tr_logGetQueueEnabled (void);
854void             tr_logSetQueueEnabled (bool isEnabled);
855void             tr_logFreeQueue       (tr_log_message * freeme);
856
857/** @addtogroup Blocklists
858    @{ */
859
860/**
861 * Specify a range of IPs for Transmission to block.
862 *
863 * Filename must be an uncompressed ascii file.
864 *
865 * libtransmission does not keep a handle to `filename'
866 * after this call returns, so the caller is free to
867 * keep or delete `filename' as it wishes.
868 * libtransmission makes its own copy of the file
869 * massaged into a binary format easier to search.
870 *
871 * The caller only needs to invoke this when the blocklist
872 * has changed.
873 *
874 * Passing NULL for a filename will clear the blocklist.
875 */
876int     tr_blocklistSetContent (tr_session       * session,
877                                   const char       * filename);
878
879int     tr_blocklistGetRuleCount (const tr_session * session);
880
881bool    tr_blocklistExists     (const tr_session * session);
882
883bool    tr_blocklistIsEnabled  (const tr_session * session);
884
885void    tr_blocklistSetEnabled (tr_session       * session,
886                                   bool               isEnabled);
887
888/** @brief The blocklist that ges updated when an RPC client
889           invokes the "blocklist-update" method */
890void tr_blocklistSetURL       (tr_session *, const char * url);
891
892const char * tr_blocklistGetURL (const tr_session *);
893
894/** @brief the file in the $config/blocklists/ directory that's
895           used by tr_blocklistSetContent () and "blocklist-update" */
896#define DEFAULT_BLOCKLIST_FILENAME "blocklist.bin"
897
898/** @} */
899
900
901/** @addtogroup tr_ctor Torrent Constructors
902    @{
903
904    Instantiating a tr_torrent had gotten more complicated as features were
905    added. At one point there were four functions to check metainfo and five
906    to create a tr_torrent object.
907
908    To remedy this, a Torrent Constructor (struct tr_ctor) has been introduced:
909    - Simplifies the API to two functions: tr_torrentParse () and tr_torrentNew ()
910    - You can set the fields you want; the system sets defaults for the rest.
911    - You can specify whether or not your fields should supercede resume's.
912    - We can add new features to tr_ctor without breaking tr_torrentNew ()'s API.
913
914    All the tr_ctor{Get,Set}* () functions with a return value return
915    an error number, or zero if no error occurred.
916
917    You must call one of the SetMetainfo () functions before creating
918    a torrent with a tr_ctor. The other functions are optional.
919
920    You can reuse a single tr_ctor to create a batch of torrents --
921    just call one of the SetMetainfo () functions between each
922    tr_torrentNew () call.
923
924    Every call to tr_ctorSetMetainfo* () frees the previous metainfo.
925 */
926
927typedef enum
928{
929    TR_FALLBACK, /* indicates the ctor value should be used only
930                    in case of missing resume settings */
931
932    TR_FORCE, /* indicates the ctor value should be used
933                 regardless of what's in the resume settings */
934}
935tr_ctorMode;
936
937/** @brief Create a torrent constructor object used to instantiate a tr_torrent
938    @param session the tr_session. This is required if you're going to call
939                   tr_torrentNew (), but you can use NULL for tr_torrentParse ().
940    @see tr_torrentNew (), tr_torrentParse () */
941tr_ctor* tr_ctorNew (const tr_session * session_or_NULL);
942
943/** @brief Free a torrent constructor object */
944void  tr_ctorFree (tr_ctor * ctor);
945
946/** @brief Set whether or not to delete the source .torrent file
947           when the torrent is added. (Default: False) */
948void  tr_ctorSetDeleteSource (tr_ctor * ctor, bool doDelete);
949
950/** @brief Set the constructor's metainfo from a magnet link */
951int tr_ctorSetMetainfoFromMagnetLink (tr_ctor * ctor, const char * magnet);
952
953/** @brief Set the constructor's metainfo from a raw benc already in memory */
954int tr_ctorSetMetainfo (tr_ctor * ctor, const uint8_t * metainfo, size_t len);
955
956/** @brief Set the constructor's metainfo from a local .torrent file */
957int tr_ctorSetMetainfoFromFile (tr_ctor * ctor, const char * filename);
958
959/**
960 * @brief Set the metainfo from an existing file in tr_getTorrentDir ().
961 *
962 * This is used by the Mac client on startup to pick and choose which
963 * torrents to load
964 */
965int tr_ctorSetMetainfoFromHash (tr_ctor * ctor, const char * hashString);
966
967/** @brief Set how many peers this torrent can connect to. (Default: 50) */
968void tr_ctorSetPeerLimit (tr_ctor * ctor, tr_ctorMode mode, uint16_t limit);
969
970/** @brief Set the download folder for the torrent being added with this ctor.
971    @see tr_ctorSetDownloadDir ()
972    @see tr_sessionInit () */
973void  tr_ctorSetDownloadDir (tr_ctor      * ctor,
974                             tr_ctorMode    mode,
975                             const char   * directory);
976
977/**
978 * @brief Set the incompleteDir for this torrent.
979 *
980 * This is not a supported API call.
981 * It only exists so the mac client can migrate
982 * its older incompleteDir settings, and that's
983 * the only place where it should be used.
984 */
985void tr_ctorSetIncompleteDir (tr_ctor * ctor, const char * directory);
986
987/** Set whether or not the torrent begins downloading/seeding when created.
988  (Default: not paused) */
989void        tr_ctorSetPaused (tr_ctor      * ctor,
990                              tr_ctorMode    mode,
991                              bool           isPaused);
992
993/** @brief Set the priorities for files in a torrent */
994void        tr_ctorSetFilePriorities (tr_ctor                * ctor,
995                                      const tr_file_index_t  * files,
996                                      tr_file_index_t          fileCount,
997                                      tr_priority_t            priority);
998
999/** @brief Set the download flag for files in a torrent */
1000void        tr_ctorSetFilesWanted (tr_ctor                * ctor,
1001                                   const tr_file_index_t  * fileIndices,
1002                                   tr_file_index_t          fileCount,
1003                                   bool                     wanted);
1004
1005
1006/** @brief Get this peer constructor's peer limit */
1007int         tr_ctorGetPeerLimit (const tr_ctor * ctor,
1008                                 tr_ctorMode     mode,
1009                                 uint16_t *      setmeCount);
1010
1011/** @brief Get the "isPaused" flag from this peer constructor */
1012int         tr_ctorGetPaused (const tr_ctor * ctor,
1013                              tr_ctorMode     mode,
1014                              bool          * setmeIsPaused);
1015
1016/** @brief Get the download path from this peer constructor */
1017int         tr_ctorGetDownloadDir (const tr_ctor  * ctor,
1018                                   tr_ctorMode      mode,
1019                                   const char    ** setmeDownloadDir);
1020
1021/** @brief Get the incomplete directory from this peer constructor */
1022int         tr_ctorGetIncompleteDir (const tr_ctor  * ctor,
1023                                     const char    ** setmeIncompleteDir);
1024
1025/** @brief Get the metainfo from this peer constructor */
1026int         tr_ctorGetMetainfo (const tr_ctor            * ctor,
1027                                const struct tr_variant ** setme);
1028
1029/** @brief Get the "delete .torrent file" flag from this peer constructor */
1030int         tr_ctorGetDeleteSource (const tr_ctor  * ctor,
1031                                    bool           * setmeDoDelete);
1032
1033/** @brief Get the tr_session poiner from this peer constructor */
1034tr_session* tr_ctorGetSession (const tr_ctor * ctor);
1035
1036/** @brief Get the .torrent file that this ctor's metainfo came from,
1037           or NULL if tr_ctorSetMetainfoFromFile () wasn't used */
1038const char* tr_ctorGetSourceFile (const tr_ctor * ctor);
1039
1040typedef enum
1041{
1042    TR_PARSE_OK,
1043    TR_PARSE_ERR,
1044    TR_PARSE_DUPLICATE
1045}
1046tr_parse_result;
1047
1048/**
1049 * @brief Parses the specified metainfo
1050 *
1051 * @return TR_PARSE_ERR if parsing failed;
1052 *         TR_PARSE_OK if parsing succeeded and it's not a duplicate;
1053 *         TR_PARSE_DUPLICATE if parsing succeeded but it's a duplicate.
1054 *
1055 * @param setme_info If parsing is successful and setme_info is non-NULL,
1056 *                   the parsed metainfo is stored there and sould be freed
1057 *                   by calling tr_metainfoFree () when no longer needed.
1058 *
1059 * Notes:
1060 *
1061 * 1. tr_torrentParse () won't be able to check for duplicates -- and therefore
1062 *    won't return TR_PARSE_DUPLICATE -- unless ctor's "download-dir" and
1063 *    session variable is set.
1064 *
1065 * 2. setme_info->torrent's value can't be set unless ctor's session variable
1066 *    is set.
1067 */
1068tr_parse_result  tr_torrentParse (const tr_ctor  * ctor,
1069                                  tr_info        * setme_info_or_NULL);
1070
1071/** @brief free a metainfo
1072    @see tr_torrentParse */
1073void tr_metainfoFree (tr_info * inf);
1074
1075
1076/**
1077 * Instantiate a single torrent.
1078 *
1079 * Returns a pointer to the torrent on success, or NULL on failure.
1080 *
1081 * @param setme_error: TR_PARSE_ERR if the parsing failed;
1082 *                     TR_PARSE_OK if parsing succeeded and it's not a duplicate;
1083 *                     TR_PARSE_DUPLICATE if parsing succeeded but it's a duplicate.
1084 *
1085 * @param setme_duplicate_id: when setmeError is TR_PARSE_DUPLICATE,
1086 *                            this field is set to the duplicate torrent's id.
1087 */
1088tr_torrent * tr_torrentNew (const tr_ctor   * ctor,
1089                            int             * setme_error,
1090                            int             * setme_duplicate_id);
1091
1092/** @} */
1093
1094/***********************************************************************
1095 ***
1096 ***  TORRENTS
1097 **/
1098
1099/** @addtogroup tr_torrent Torrents
1100    @{ */
1101
1102typedef int (*tr_fileFunc) (const char * filename);
1103
1104/** @brief Removes our .torrent and .resume files for this torrent */
1105void tr_torrentRemove (tr_torrent  * torrent,
1106                       bool          removeLocalData,
1107                       tr_fileFunc   removeFunc);
1108
1109/** @brief Start a torrent */
1110void tr_torrentStart (tr_torrent * torrent);
1111
1112/** @brief Stop (pause) a torrent */
1113void tr_torrentStop (tr_torrent * torrent);
1114
1115
1116typedef void (*tr_torrent_rename_done_func)(tr_torrent  * torrent,
1117                                            const char  * oldpath,
1118                                            const char  * newname,
1119                                            int           error,
1120                                            void        * user_data);
1121
1122/**
1123 * @brief Rename a file or directory in a torrent.
1124 *
1125 * @tor: the torrent whose path will be renamed.
1126 * @oldpath: the path to the file or folder that will be renamed
1127 * @newname: the file or folder's new name
1128 * @callback: the callback invoked when the renaming finishes, or NULL
1129 * @callback_data: the pointer to pass in the callback's user_data arg
1130 *
1131 * As a special case, renaming the root file in a torrent will also
1132 * update tr_info.name.
1133 *
1134 * EXAMPLES
1135 *
1136 *   Consider a tr_torrent where its
1137 *   info.files[0].name is "frobnitz-linux/checksum" and
1138 *   info.files[1].name is "frobnitz-linux/frobnitz.iso".
1139 *
1140 *   1. tr_torrentRenamePath (tor, "frobnitz-linux", "foo") will rename
1141 *      the "frotbnitz-linux" folder as "foo", and update both info.name
1142 *      and info.files[*].name.
1143 *
1144 *   2. tr_torrentRenamePath (tor, "frobnitz-linux/checksum", "foo") will
1145 *      rename the "frobnitz-linux/checksum" file as "foo" and update
1146 *      files[0].name to "frobnitz-linux/foo".
1147 *
1148 * RETURN
1149 *
1150 *   Changing tr_info's contents requires a session lock, so this function
1151 *   returns asynchronously to avoid blocking. If you don't want to be notified
1152 *   when the function has finished, you can pass NULL as the callback arg.
1153 *
1154 *   On success, the callback's error argument will be 0.
1155 *
1156 *   If oldpath can't be found in files[*].name, or if newname is already
1157 *   in files[*].name, or contains a directory separator, or is NULL, "",
1158 *   ".", or "..", the error argument will be EINVAL.
1159 *
1160 *   If the path exists on disk but can't be renamed, the error argument
1161 *   will be the errno set by rename().
1162 */
1163void tr_torrentRenamePath (tr_torrent                  * tor,
1164                           const char                  * oldpath,
1165                           const char                  * newname,
1166                           tr_torrent_rename_done_func   callback,
1167                           void                        * callback_user_data);
1168
1169enum
1170{
1171    TR_LOC_MOVING,
1172    TR_LOC_DONE,
1173    TR_LOC_ERROR
1174};
1175
1176/**
1177 * @brief Tell transmsision where to find this torrent's local data.
1178 *
1179 * if move_from_previous_location is `true', the torrent's incompleteDir
1180 * will be clobberred s.t. additional files being added will be saved
1181 * to the torrent's downloadDir.
1182 */
1183void tr_torrentSetLocation (tr_torrent       * torrent,
1184                            const char       * location,
1185                            bool               move_from_previous_location,
1186                            volatile double  * setme_progress,
1187                            volatile int     * setme_state);
1188
1189uint64_t tr_torrentGetBytesLeftToAllocate (const tr_torrent * torrent);
1190
1191/**
1192 * @brief Returns this torrent's unique ID.
1193 *
1194 * IDs are good as simple lookup keys, but are not persistent
1195 * between sessions. If you need that, use tr_info.hash or
1196 * tr_info.hashString.
1197 */
1198int tr_torrentId (const tr_torrent * torrent);
1199
1200tr_torrent* tr_torrentFindFromId (tr_session * session, int id);
1201
1202tr_torrent* tr_torrentFindFromHash (tr_session     * session,
1203                                    const uint8_t  * hash);
1204
1205/** @brief Convenience function similar to tr_torrentFindFromHash () */
1206tr_torrent* tr_torrentFindFromMagnetLink (tr_session * session,
1207                                          const char * link);
1208
1209/**
1210 * @return this torrent's name.
1211 */
1212const char* tr_torrentName (const tr_torrent *);
1213
1214/**
1215 * @brief find the location of a torrent's file by looking with and without
1216 *        the ".part" suffix, looking in downloadDir and incompleteDir, etc.
1217 * @return a newly-allocated string (that must be tr_freed () by the caller
1218 *         when done) that gives the location of this file on disk,
1219 *         or NULL if no file exists yet.
1220 * @param tor the torrent whose file we're looking for
1221 * @param fileNum the fileIndex, in [0...tr_info.fileCount)
1222 */
1223char* tr_torrentFindFile (const tr_torrent * tor, tr_file_index_t fileNo);
1224
1225
1226/***
1227****  Torrent speed limits
1228****
1229***/
1230
1231void         tr_torrentSetSpeedLimit_KBps (tr_torrent *, tr_direction, unsigned int KBps);
1232unsigned int tr_torrentGetSpeedLimit_KBps (const tr_torrent *, tr_direction);
1233
1234void         tr_torrentUseSpeedLimit      (tr_torrent *, tr_direction, bool);
1235bool         tr_torrentUsesSpeedLimit     (const tr_torrent *, tr_direction);
1236
1237void         tr_torrentUseSessionLimits   (tr_torrent *, bool);
1238bool         tr_torrentUsesSessionLimits  (const tr_torrent *);
1239
1240
1241/****
1242*****  Ratio Limits
1243****/
1244
1245typedef enum
1246{
1247    /* follow the global settings */
1248    TR_RATIOLIMIT_GLOBAL    = 0,
1249
1250    /* override the global settings, seeding until a certain ratio */
1251    TR_RATIOLIMIT_SINGLE    = 1,
1252
1253    /* override the global settings, seeding regardless of ratio */
1254    TR_RATIOLIMIT_UNLIMITED = 2
1255}
1256tr_ratiolimit;
1257
1258void          tr_torrentSetRatioMode (tr_torrent         * tor,
1259                                      tr_ratiolimit        mode);
1260
1261tr_ratiolimit tr_torrentGetRatioMode (const tr_torrent   * tor);
1262
1263void          tr_torrentSetRatioLimit (tr_torrent        * tor,
1264                                       double              ratio);
1265
1266double        tr_torrentGetRatioLimit (const tr_torrent  * tor);
1267
1268
1269bool          tr_torrentGetSeedRatio  (const tr_torrent *, double * ratio);
1270
1271
1272/****
1273*****  Idle Time Limits
1274****/
1275
1276typedef enum
1277{
1278    /* follow the global settings */
1279    TR_IDLELIMIT_GLOBAL    = 0,
1280
1281    /* override the global settings, seeding until a certain idle time */
1282    TR_IDLELIMIT_SINGLE    = 1,
1283
1284    /* override the global settings, seeding regardless of activity */
1285    TR_IDLELIMIT_UNLIMITED = 2
1286}
1287tr_idlelimit;
1288
1289void          tr_torrentSetIdleMode (tr_torrent         * tor,
1290                                      tr_idlelimit         mode);
1291
1292tr_idlelimit  tr_torrentGetIdleMode (const tr_torrent   * tor);
1293
1294void          tr_torrentSetIdleLimit (tr_torrent         * tor,
1295                                      uint16_t             idleMinutes);
1296
1297uint16_t      tr_torrentGetIdleLimit (const tr_torrent   * tor);
1298
1299
1300bool          tr_torrentGetSeedIdle (const tr_torrent *, uint16_t * minutes);
1301
1302/****
1303*****  Peer Limits
1304****/
1305
1306void          tr_torrentSetPeerLimit (tr_torrent * tor, uint16_t peerLimit);
1307
1308uint16_t      tr_torrentGetPeerLimit (const tr_torrent * tor);
1309
1310/****
1311*****  File Priorities
1312****/
1313
1314enum
1315{
1316    TR_PRI_LOW    = -1,
1317    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
1318    TR_PRI_HIGH   =  1
1319};
1320
1321/**
1322 * @brief Set a batch of files to a particular priority.
1323 *
1324 * @param priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW
1325 */
1326void tr_torrentSetFilePriorities (tr_torrent             * torrent,
1327                                  const tr_file_index_t  * files,
1328                                  tr_file_index_t          fileCount,
1329                                  tr_priority_t            priority);
1330
1331/**
1332 * @brief Get this torrent's file priorities.
1333 *
1334 * @return A malloc ()ed array of tor->info.fileCount items,
1335 *         each holding a TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
1336 *         It's the caller's responsibility to free () this.
1337 */
1338tr_priority_t*  tr_torrentGetFilePriorities (const tr_torrent * torrent);
1339
1340/** @brief Set a batch of files to be downloaded or not. */
1341void tr_torrentSetFileDLs (tr_torrent             * torrent,
1342                           const tr_file_index_t  * files,
1343                           tr_file_index_t          fileCount,
1344                           bool                     do_download);
1345
1346
1347const tr_info * tr_torrentInfo (const tr_torrent * torrent);
1348
1349/* Raw function to change the torrent's downloadDir field.
1350   This should only be used by libtransmission or to bootstrap
1351   a newly-instantiated tr_torrent object. */
1352void tr_torrentSetDownloadDir (tr_torrent  * torrent, const char * path);
1353
1354const char * tr_torrentGetDownloadDir (const tr_torrent * torrent);
1355
1356/**
1357 * Returns the root directory of where the torrent is.
1358 *
1359 * This will usually be the downloadDir. However if the torrent
1360 * has an incompleteDir enabled and hasn't finished downloading
1361 * yet, that will be returned instead.
1362 */
1363const char * tr_torrentGetCurrentDir (const tr_torrent * tor);
1364
1365
1366char* tr_torrentInfoGetMagnetLink (const tr_info * inf);
1367
1368/**
1369 * Returns a newly-allocated string with a magnet link of the torrent.
1370 * Use tr_free () to free the string when done.
1371 */
1372static inline
1373char* tr_torrentGetMagnetLink (const tr_torrent * tor)
1374{
1375    return tr_torrentInfoGetMagnetLink (tr_torrentInfo (tor));
1376}
1377
1378/**
1379***
1380**/
1381
1382
1383/** @brief a part of tr_info that represents a single tracker */
1384typedef struct tr_tracker_info
1385{
1386    int      tier;
1387    char *   announce;
1388    char *   scrape;
1389    uint32_t id; /* unique identifier used to match to a tr_tracker_stat */
1390}
1391tr_tracker_info;
1392
1393/**
1394 * @brief Modify a torrent's tracker list.
1395 *
1396 * This updates both the `torrent' object's tracker list
1397 * and the metainfo file in tr_sessionGetConfigDir ()'s torrent subdirectory.
1398 *
1399 * @param torrent The torrent whose tracker list is to be modified
1400 * @param trackers An array of trackers, sorted by tier from first to last.
1401 *                 NOTE: only the `tier' and `announce' fields are used.
1402 *                 libtransmission derives `scrape' from `announce'
1403 *                 and reassigns 'id'.
1404 * @param trackerCount size of the `trackers' array
1405 */
1406bool
1407tr_torrentSetAnnounceList (tr_torrent             * torrent,
1408                           const tr_tracker_info  * trackers,
1409                           int                      trackerCount);
1410
1411
1412/**
1413***
1414**/
1415
1416typedef enum
1417{
1418    TR_LEECH,        /* doesn't have all the desired pieces */
1419    TR_SEED,         /* has the entire torrent */
1420    TR_PARTIAL_SEED  /* has the desired pieces, but not the entire torrent */
1421}
1422tr_completeness;
1423
1424/**
1425 * @param wasRunning whether or not the torrent was running when
1426 *                   it changed its completeness state
1427 */
1428typedef void (*tr_torrent_completeness_func)(tr_torrent       * torrent,
1429                                             tr_completeness    completeness,
1430                                             bool               wasRunning,
1431                                             void             * user_data);
1432
1433typedef void (*tr_torrent_ratio_limit_hit_func)(tr_torrent   * torrent,
1434                                                void         * user_data);
1435
1436typedef void (*tr_torrent_idle_limit_hit_func)(tr_torrent   * torrent,
1437                                               void         * user_data);
1438
1439
1440/**
1441 * Register to be notified whenever a torrent's "completeness"
1442 * changes. This will be called, for example, when a torrent
1443 * finishes downloading and changes from TR_LEECH to
1444 * either TR_SEED or TR_PARTIAL_SEED.
1445 *
1446 * func is invoked FROM LIBTRANSMISSION'S THREAD!
1447 * This means func must be fast (to avoid blocking peers),
1448 * shouldn't call libtransmission functions (to avoid deadlock),
1449 * and shouldn't modify client-level memory without using a mutex!
1450 *
1451 * @see tr_completeness
1452 */
1453void tr_torrentSetCompletenessCallback (
1454         tr_torrent                    * torrent,
1455         tr_torrent_completeness_func    func,
1456         void                          * user_data);
1457
1458void tr_torrentClearCompletenessCallback (tr_torrent * torrent);
1459
1460
1461
1462typedef void (*tr_torrent_metadata_func)(tr_torrent  * torrent,
1463                                         void        * user_data);
1464/**
1465 * Register to be notified whenever a torrent changes from
1466 * having incomplete metadata to having complete metadata.
1467 * This happens when a magnet link finishes downloading
1468 * metadata from its peers.
1469 */
1470void tr_torrentSetMetadataCallback (
1471         tr_torrent                * tor,
1472         tr_torrent_metadata_func     func,
1473         void                      * user_data);
1474
1475/**
1476 * Register to be notified whenever a torrent's ratio limit
1477 * has been hit. This will be called when the torrent's
1478 * ul/dl ratio has met or exceeded the designated ratio limit.
1479 *
1480 * Has the same restrictions as tr_torrentSetCompletenessCallback
1481 */
1482void tr_torrentSetRatioLimitHitCallback (
1483     tr_torrent                     * torrent,
1484     tr_torrent_ratio_limit_hit_func  func,
1485     void                           * user_data);
1486
1487void tr_torrentClearRatioLimitHitCallback (tr_torrent * torrent);
1488
1489/**
1490 * Register to be notified whenever a torrent's idle limit
1491 * has been hit. This will be called when the seeding torrent's
1492 * idle time has met or exceeded the designated idle limit.
1493 *
1494 * Has the same restrictions as tr_torrentSetCompletenessCallback
1495 */
1496void tr_torrentSetIdleLimitHitCallback (
1497     tr_torrent                          * torrent,
1498     tr_torrent_idle_limit_hit_func        func,
1499     void                                * user_data);
1500
1501void tr_torrentClearIdleLimitHitCallback (tr_torrent * torrent);
1502
1503
1504/**
1505 * MANUAL ANNOUNCE
1506 *
1507 * Trackers usually set an announce interval of 15 or 30 minutes.
1508 * Users can send one-time announce requests that override this
1509 * interval by calling tr_torrentManualUpdate ().
1510 *
1511 * The wait interval for tr_torrentManualUpdate () is much smaller.
1512 * You can test whether or not a manual update is possible
1513 * (for example, to desensitize the button) by calling
1514 * tr_torrentCanManualUpdate ().
1515 */
1516
1517void tr_torrentManualUpdate (tr_torrent * torrent);
1518
1519bool tr_torrentCanManualUpdate (const tr_torrent * torrent);
1520
1521/***
1522****  tr_peer_stat
1523***/
1524
1525typedef struct tr_peer_stat
1526{
1527    bool  isUTP;
1528
1529    bool  isEncrypted;
1530    bool  isDownloadingFrom;
1531    bool  isUploadingTo;
1532    bool  isSeed;
1533
1534    bool  peerIsChoked;
1535    bool  peerIsInterested;
1536    bool  clientIsChoked;
1537    bool  clientIsInterested;
1538    bool  isIncoming;
1539
1540    uint8_t  from;
1541    tr_port  port;
1542
1543    char     addr[TR_INET6_ADDRSTRLEN];
1544    char     client[80];
1545    char     flagStr[32];
1546
1547    float    progress;
1548    double   rateToPeer_KBps;
1549    double   rateToClient_KBps;
1550
1551
1552/***
1553****  THESE NEXT FOUR FIELDS ARE EXPERIMENTAL.
1554****  Don't rely on them; they'll probably go away
1555***/
1556    /* how many blocks we've sent to this peer in the last 120 seconds */
1557    uint32_t  blocksToPeer;
1558    /* how many blocks this client's sent to us in the last 120 seconds */
1559    uint32_t  blocksToClient;
1560    /* how many requests to this peer that we've cancelled in the last 120 seconds */
1561    uint32_t  cancelsToPeer;
1562    /* how many requests this peer made of us, then cancelled, in the last 120 seconds */
1563    uint32_t  cancelsToClient;
1564
1565    /* how many requests the peer has made that we haven't responded to yet */
1566    int      pendingReqsToClient;
1567
1568    /* how many requests we've made and are currently awaiting a response for */
1569    int      pendingReqsToPeer;
1570}
1571tr_peer_stat;
1572
1573tr_peer_stat * tr_torrentPeers (const tr_torrent * torrent,
1574                                int              * peerCount);
1575
1576void           tr_torrentPeersFree (tr_peer_stat * peerStats,
1577                                    int            peerCount);
1578
1579/***
1580****  tr_tracker_stat
1581***/
1582
1583typedef enum
1584{
1585    /* we won't (announce,scrape) this torrent to this tracker because
1586     * the torrent is stopped, or because of an error, or whatever */
1587    TR_TRACKER_INACTIVE = 0,
1588
1589    /* we will (announce,scrape) this torrent to this tracker, and are
1590     * waiting for enough time to pass to satisfy the tracker's interval */
1591    TR_TRACKER_WAITING = 1,
1592
1593    /* it's time to (announce,scrape) this torrent, and we're waiting on a
1594     * a free slot to open up in the announce manager */
1595    TR_TRACKER_QUEUED = 2,
1596
1597    /* we're (announcing,scraping) this torrent right now */
1598    TR_TRACKER_ACTIVE = 3
1599}
1600tr_tracker_state;
1601
1602typedef struct
1603{
1604    /* how many downloads this tracker knows of (-1 means it does not know) */
1605    int downloadCount;
1606
1607    /* whether or not we've ever sent this tracker an announcement */
1608    bool hasAnnounced;
1609
1610    /* whether or not we've ever scraped to this tracker */
1611    bool hasScraped;
1612
1613    /* human-readable string identifying the tracker */
1614    char host[1024];
1615
1616    /* the full announce URL */
1617    char announce[1024];
1618
1619    /* the full scrape URL */
1620    char scrape[1024];
1621
1622    /* Transmission uses one tracker per tier,
1623     * and the others are kept as backups */
1624    bool isBackup;
1625
1626    /* is the tracker announcing, waiting, queued, etc */
1627    tr_tracker_state announceState;
1628
1629    /* is the tracker scraping, waiting, queued, etc */
1630    tr_tracker_state scrapeState;
1631
1632    /* number of peers the tracker told us about last time.
1633     * if "lastAnnounceSucceeded" is false, this field is undefined */
1634    int lastAnnouncePeerCount;
1635
1636    /* human-readable string with the result of the last announce.
1637       if "hasAnnounced" is false, this field is undefined */
1638    char lastAnnounceResult[128];
1639
1640    /* when the last announce was sent to the tracker.
1641     * if "hasAnnounced" is false, this field is undefined */
1642    time_t lastAnnounceStartTime;
1643
1644    /* whether or not the last announce was a success.
1645       if "hasAnnounced" is false, this field is undefined */
1646    bool lastAnnounceSucceeded;
1647
1648    /* whether or not the last announce timed out. */
1649    bool lastAnnounceTimedOut;
1650
1651    /* when the last announce was completed.
1652       if "hasAnnounced" is false, this field is undefined */
1653    time_t lastAnnounceTime;
1654
1655    /* human-readable string with the result of the last scrape.
1656     * if "hasScraped" is false, this field is undefined */
1657    char lastScrapeResult[128];
1658
1659    /* when the last scrape was sent to the tracker.
1660     * if "hasScraped" is false, this field is undefined */
1661    time_t lastScrapeStartTime;
1662
1663    /* whether or not the last scrape was a success.
1664       if "hasAnnounced" is false, this field is undefined */
1665    bool lastScrapeSucceeded;
1666
1667    /* whether or not the last scrape timed out. */
1668    bool lastScrapeTimedOut;
1669
1670    /* when the last scrape was completed.
1671       if "hasScraped" is false, this field is undefined */
1672    time_t lastScrapeTime;
1673
1674    /* number of leechers this tracker knows of (-1 means it does not know) */
1675    int leecherCount;
1676
1677    /* when the next periodic announce message will be sent out.
1678       if announceState isn't TR_TRACKER_WAITING, this field is undefined */
1679    time_t nextAnnounceTime;
1680
1681    /* when the next periodic scrape message will be sent out.
1682       if scrapeState isn't TR_TRACKER_WAITING, this field is undefined */
1683    time_t nextScrapeTime;
1684
1685    /* number of seeders this tracker knows of (-1 means it does not know) */
1686    int seederCount;
1687
1688    /* which tier this tracker is in */
1689    int tier;
1690
1691    /* used to match to a tr_tracker_info */
1692    uint32_t id;
1693}
1694tr_tracker_stat;
1695
1696tr_tracker_stat * tr_torrentTrackers (const tr_torrent * torrent,
1697                                      int              * setmeTrackerCount);
1698
1699void tr_torrentTrackersFree (tr_tracker_stat * trackerStats,
1700                             int               trackerCount);
1701
1702
1703
1704/**
1705 * @brief get the download speeds for each of this torrent's webseed sources.
1706 *
1707 * @return an array of tor->info.webseedCount floats giving download speeds.
1708 *         Each speed in the array corresponds to the webseed at the same
1709 *         array index in tor->info.webseeds.
1710 *         To differentiate "idle" and "stalled" status, idle webseeds will
1711 *         return -1 instead of 0 KiB/s.
1712 *         NOTE: always free this array with tr_free () when you're done with it.
1713 */
1714double*  tr_torrentWebSpeeds_KBps (const tr_torrent * torrent);
1715
1716typedef struct tr_file_stat
1717{
1718    uint64_t    bytesCompleted;
1719    float       progress;
1720}
1721tr_file_stat;
1722
1723tr_file_stat * tr_torrentFiles (const tr_torrent  * torrent,
1724                                tr_file_index_t   * fileCount);
1725
1726void tr_torrentFilesFree (tr_file_stat     * files,
1727                          tr_file_index_t    fileCount);
1728
1729
1730/***********************************************************************
1731 * tr_torrentAvailability
1732 ***********************************************************************
1733 * Use this to draw an advanced progress bar which is 'size' pixels
1734 * wide. Fills 'tab' which you must have allocated: each byte is set
1735 * to either -1 if we have the piece, otherwise it is set to the number
1736 * of connected peers who have the piece.
1737 **********************************************************************/
1738void tr_torrentAvailability (const tr_torrent  * torrent,
1739                             int8_t            * tab,
1740                             int                 size);
1741
1742void tr_torrentAmountFinished (const tr_torrent  * torrent,
1743                               float             * tab,
1744                               int                 size);
1745
1746/**
1747 * Callback function invoked when a torrent finishes being verified.
1748 *
1749 * @param torrent the torrent that was verified
1750 * @param aborted true if the verify ended prematurely for some reason,
1751 *                such as tr_torrentStop() or tr_torrentSetLocation()
1752 *                being called during verification.
1753 * @param callback_data the user-defined pointer from tr_torrentVerify()
1754 */
1755typedef void (*tr_verify_done_func)(tr_torrent  * torrent,
1756                                    bool          aborted,
1757                                    void        * user_data);
1758
1759/**
1760 * Queue a torrent for verification.
1761 *
1762 * If callback_func is non-NULL, it will be called from the libtransmission
1763 * thread after the torrent's completness state is updated after the
1764 * file verification pass.
1765 */
1766void tr_torrentVerify (tr_torrent           * torrent,
1767                       tr_verify_done_func    callback_func_or_NULL,
1768                       void                 * callback_data_or_NULL);
1769
1770/***********************************************************************
1771 * tr_info
1772 **********************************************************************/
1773
1774/** @brief a part of tr_info that represents a single file of the torrent's content */
1775typedef struct tr_file
1776{
1777    uint64_t          length;      /* Length of the file, in bytes */
1778    char *            name;        /* Path to the file */
1779    int8_t            priority;    /* TR_PRI_HIGH, _NORMAL, or _LOW */
1780    int8_t            dnd;         /* "do not download" flag */
1781    int8_t            is_renamed;  /* true if we're using a different path from the one in the metainfo; ie, if the user has renamed it */
1782    tr_piece_index_t  firstPiece;  /* We need pieces [firstPiece... */
1783    tr_piece_index_t  lastPiece;   /* ...lastPiece] to dl this file */
1784    uint64_t          offset;      /* file begins at the torrent's nth byte */
1785}
1786tr_file;
1787
1788/** @brief a part of tr_info that represents a single piece of the torrent's content */
1789typedef struct tr_piece
1790{
1791    time_t   timeChecked;              /* the last time we tested this piece */
1792    uint8_t  hash[SHA_DIGEST_LENGTH];  /* pieces hash */
1793    int8_t   priority;                 /* TR_PRI_HIGH, _NORMAL, or _LOW */
1794    int8_t   dnd;                      /* "do not download" flag */
1795}
1796tr_piece;
1797
1798/** @brief information about a torrent that comes from its metainfo file */
1799struct tr_info
1800{
1801    /* total size of the torrent, in bytes */
1802    uint64_t           totalSize;
1803
1804    /* The original name that came in this torrent's metainfo.
1805     * CLIENT CODE: NOT USE THIS FIELD. */
1806    char             * originalName;
1807
1808    /* The torrent's name. */
1809    char             * name;
1810
1811    /* Path to torrent Transmission's internal copy of the .torrent file. */
1812    char             * torrent;
1813
1814    char            ** webseeds;
1815
1816    char             * comment;
1817    char             * creator;
1818    tr_file          * files;
1819    tr_piece         * pieces;
1820
1821    /* these trackers are sorted by tier */
1822    tr_tracker_info  * trackers;
1823
1824    /* Torrent info */
1825    time_t             dateCreated;
1826
1827    unsigned int       trackerCount;
1828    unsigned int       webseedCount;
1829    tr_file_index_t    fileCount;
1830    uint32_t           pieceSize;
1831    tr_piece_index_t   pieceCount;
1832
1833    /* General info */
1834    uint8_t            hash[SHA_DIGEST_LENGTH];
1835    char               hashString[2 * SHA_DIGEST_LENGTH + 1];
1836
1837    /* Flags */
1838    bool               isPrivate;
1839    bool               isFolder;
1840};
1841
1842static inline bool tr_torrentHasMetadata (const tr_torrent * tor)
1843{
1844    return tr_torrentInfo (tor)->fileCount > 0;
1845}
1846
1847/**
1848 * What the torrent is doing right now.
1849 *
1850 * Note: these values will become a straight enum at some point in the future.
1851 * Do not rely on their current `bitfield' implementation
1852 */
1853typedef enum
1854{
1855    TR_STATUS_STOPPED        = 0, /* Torrent is stopped */
1856    TR_STATUS_CHECK_WAIT     = 1, /* Queued to check files */
1857    TR_STATUS_CHECK          = 2, /* Checking files */
1858    TR_STATUS_DOWNLOAD_WAIT  = 3, /* Queued to download */
1859    TR_STATUS_DOWNLOAD       = 4, /* Downloading */
1860    TR_STATUS_SEED_WAIT      = 5, /* Queued to seed */
1861    TR_STATUS_SEED           = 6  /* Seeding */
1862}
1863tr_torrent_activity;
1864
1865enum
1866{
1867    TR_PEER_FROM_INCOMING  = 0, /* connections made to the listening port */
1868    TR_PEER_FROM_LPD,           /* peers found by local announcements */
1869    TR_PEER_FROM_TRACKER,       /* peers found from a tracker */
1870    TR_PEER_FROM_DHT,           /* peers found from the DHT */
1871    TR_PEER_FROM_PEX,           /* peers found from PEX */
1872    TR_PEER_FROM_RESUME,        /* peers found in the .resume file */
1873    TR_PEER_FROM_LTEP,          /* peer address provided in an LTEP handshake */
1874    TR_PEER_FROM__MAX
1875};
1876
1877typedef enum
1878{
1879    /* everything's fine */
1880    TR_STAT_OK               = 0,
1881
1882    /* when we anounced to the tracker, we got a warning in the response */
1883    TR_STAT_TRACKER_WARNING  = 1,
1884
1885    /* when we anounced to the tracker, we got an error in the response */
1886    TR_STAT_TRACKER_ERROR    = 2,
1887
1888    /* local trouble, such as disk full or permissions error */
1889    TR_STAT_LOCAL_ERROR      = 3
1890}
1891tr_stat_errtype;
1892
1893/** @brief Used by tr_torrentStat () to tell clients about a torrent's state and statistics */
1894typedef struct tr_stat
1895{
1896    /** The torrent's unique Id.
1897        @see tr_torrentId () */
1898    int    id;
1899
1900    /** What is this torrent doing right now? */
1901    tr_torrent_activity activity;
1902
1903    /** Defines what kind of text is in errorString.
1904        @see errorString */
1905    tr_stat_errtype error;
1906
1907    /** A warning or error message regarding the torrent.
1908        @see error */
1909    char errorString[512];
1910
1911    /** When tr_stat.activity is TR_STATUS_CHECK or TR_STATUS_CHECK_WAIT,
1912        this is the percentage of how much of the files has been
1913        verified. When it gets to 1, the verify process is done.
1914        Range is [0..1]
1915        @see tr_stat.activity */
1916    float recheckProgress;
1917
1918    /** How much has been downloaded of the entire torrent.
1919        Range is [0..1] */
1920    float percentComplete;
1921
1922    /** How much of the metadata the torrent has.
1923        For torrents added from a .torrent this will always be 1.
1924        For magnet links, this number will from from 0 to 1 as the metadata is downloaded.
1925        Range is [0..1] */
1926    float metadataPercentComplete;
1927
1928    /** How much has been downloaded of the files the user wants. This differs
1929        from percentComplete if the user wants only some of the torrent's files.
1930        Range is [0..1]
1931        @see tr_stat.leftUntilDone */
1932    float percentDone;
1933
1934    /** How much has been uploaded to satisfy the seed ratio.
1935        This is 1 if the ratio is reached or the torrent is set to seed forever.
1936        Range is [0..1] */
1937    float seedRatioPercentDone;
1938
1939    /** Speed all data being sent for this torrent.
1940        This includes piece data, protocol messages, and TCP overhead */
1941    float rawUploadSpeed_KBps;
1942
1943    /** Speed all data being received for this torrent.
1944        This includes piece data, protocol messages, and TCP overhead */
1945    float rawDownloadSpeed_KBps;
1946
1947    /** Speed all piece being sent for this torrent.
1948        This ONLY counts piece data. */
1949    float pieceUploadSpeed_KBps;
1950
1951    /** Speed all piece being received for this torrent.
1952        This ONLY counts piece data. */
1953    float pieceDownloadSpeed_KBps;
1954
1955#define TR_ETA_NOT_AVAIL -1
1956#define TR_ETA_UNKNOWN -2
1957    /** If downloading, estimated number of seconds left until the torrent is done.
1958        If seeding, estimated number of seconds left until seed ratio is reached. */
1959    int    eta;
1960    /** If seeding, number of seconds left until the idle time limit is reached. */
1961    int    etaIdle;
1962
1963    /** Number of peers that we're connected to */
1964    int    peersConnected;
1965
1966    /** How many peers we found out about from the tracker, or from pex,
1967        or from incoming connections, or from our resume file. */
1968    int    peersFrom[TR_PEER_FROM__MAX];
1969
1970    /** Number of peers that are sending data to us. */
1971    int    peersSendingToUs;
1972
1973    /** Number of peers that we're sending data to */
1974    int    peersGettingFromUs;
1975
1976    /** Number of webseeds that are sending data to us. */
1977    int    webseedsSendingToUs;
1978
1979    /** Byte count of all the piece data we'll have downloaded when we're done,
1980        whether or not we have it yet. This may be less than tr_info.totalSize
1981        if only some of the torrent's files are wanted.
1982        [0...tr_info.totalSize] */
1983    uint64_t    sizeWhenDone;
1984
1985    /** Byte count of how much data is left to be downloaded until we've got
1986        all the pieces that we want. [0...tr_info.sizeWhenDone] */
1987    uint64_t    leftUntilDone;
1988
1989    /** Byte count of all the piece data we want and don't have yet,
1990        but that a connected peer does have. [0...leftUntilDone] */
1991    uint64_t    desiredAvailable;
1992
1993    /** Byte count of all the corrupt data you've ever downloaded for
1994        this torrent. If you're on a poisoned torrent, this number can
1995        grow very large. */
1996    uint64_t    corruptEver;
1997
1998    /** Byte count of all data you've ever uploaded for this torrent. */
1999    uint64_t    uploadedEver;
2000
2001    /** Byte count of all the non-corrupt data you've ever downloaded
2002        for this torrent. If you deleted the files and downloaded a second
2003        time, this will be 2*totalSize.. */
2004    uint64_t    downloadedEver;
2005
2006    /** Byte count of all the checksum-verified data we have for this torrent.
2007      */
2008    uint64_t    haveValid;
2009
2010    /** Byte count of all the partial piece data we have for this torrent.
2011        As pieces become complete, this value may decrease as portions of it
2012        are moved to `corrupt' or `haveValid'. */
2013    uint64_t    haveUnchecked;
2014
2015    /** time when one or more of the torrent's trackers will
2016        allow you to manually ask for more peers,
2017        or 0 if you can't */
2018    time_t manualAnnounceTime;
2019
2020#define TR_RATIO_NA  -1
2021#define TR_RATIO_INF -2
2022    /** TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
2023    float    ratio;
2024
2025    /** When the torrent was first added. */
2026    time_t    addedDate;
2027
2028    /** When the torrent finished downloading. */
2029    time_t    doneDate;
2030
2031    /** When the torrent was last started. */
2032    time_t    startDate;
2033
2034    /** The last time we uploaded or downloaded piece data on this torrent. */
2035    time_t    activityDate;
2036
2037    /** Number of seconds since the last activity (or since started).
2038        -1 if activity is not seeding or downloading. */
2039    int    idleSecs;
2040
2041    /** Cumulative seconds the torrent's ever spent downloading */
2042    int    secondsDownloading;
2043
2044    /** Cumulative seconds the torrent's ever spent seeding */
2045    int    secondsSeeding;
2046
2047    /** A torrent is considered finished if it has met its seed ratio.
2048        As a result, only paused torrents can be finished. */
2049    bool   finished;
2050
2051    /** This torrent's queue position.
2052        All torrents have a queue position, even if it's not queued. */
2053    int queuePosition;
2054
2055    /** True if the torrent is running, but has been idle for long enough
2056        to be considered stalled.  @see tr_sessionGetQueueStalledMinutes () */
2057    bool isStalled;
2058}
2059tr_stat;
2060
2061/** Return a pointer to an tr_stat structure with updated information
2062    on the torrent. This is typically called by the GUI clients every
2063    second or so to get a new snapshot of the torrent's status. */
2064const tr_stat * tr_torrentStat (tr_torrent * torrent);
2065
2066/** Like tr_torrentStat (), but only recalculates the statistics if it's
2067    been longer than a second since they were last calculated. This can
2068    reduce the CPU load if you're calling tr_torrentStat () frequently. */
2069const tr_stat * tr_torrentStatCached (tr_torrent * torrent);
2070
2071/** @deprecated */
2072void tr_torrentSetAddedDate (tr_torrent * torrent,
2073                             time_t       addedDate);
2074
2075/** @deprecated */
2076void tr_torrentSetActivityDate (tr_torrent * torrent,
2077                                time_t       activityDate);
2078
2079/** @deprecated */
2080void tr_torrentSetDoneDate (tr_torrent * torrent, time_t doneDate);
2081
2082/** @} */
2083
2084/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
2085static inline bool tr_isDirection (tr_direction d) { return d==TR_UP || d==TR_DOWN; }
2086
2087/** @brief Sanity checker to test that a bool is true or false */
2088static inline bool tr_isBool (bool b) { return b==1 || b==0; }
2089
2090#ifdef __cplusplus
2091}
2092#endif
2093
2094#endif
Note: See TracBrowser for help on using the repository browser.