source: trunk/libtransmission/transmission.h @ 14181

Last change on this file since 14181 was 14181, checked in by jordan, 8 years ago

add windows-friendly definitions for PRIu64, PRId64, PRIu32

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