source: trunk/libtransmission/transmission.h @ 14581

Last change on this file since 14581 was 14581, checked in by mikedld, 6 years ago

Remove unused session tag

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