source: trunk/libtransmission/transmission.h @ 10999

Last change on this file since 10999 was 10999, checked in by livings124, 12 years ago

Have libtransmission keep track of idle seconds. Use this value for determining the stalled minutes in the Mac code.

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