source: trunk/libtransmission/transmission.h @ 9403

Last change on this file since 9403 was 9403, checked in by livings124, 13 years ago

since the Mac UI is the only one to use it, move percentRatio calculation into the Mac code

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