source: trunk/libtransmission/transmission.h

Last change on this file was 14724, checked in by jordan, 5 years ago

use '#pragma once' instead of #ifndef..#define..#endif guards

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