source: trunk/libtransmission/transmission.h @ 7468

Last change on this file since 7468 was 7468, checked in by charles, 12 years ago

(trunk) patch from wereHamster to finish off tr_handle

  • Property svn:keywords set to Date Rev Author Id
File size: 47.6 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 7468 2008-12-22 19:14:43Z charles $
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 suitable for public consumption are bencode.h
29 * and utils.h.  Most of the remaining headers in libtransmission
30 * should be considered private to libtransmission.
31 */
32#ifndef TR_TRANSMISSION_H
33#define TR_TRANSMISSION_H 1
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39#include "version.h"
40
41#include <inttypes.h> /* uintN_t */
42#ifndef PRId64
43 #define PRId64 "lld"
44#endif
45#ifndef PRIu64
46 #define PRIu64 "llu"
47#endif
48#ifndef PRIu32
49 #define PRIu32 "lu"
50#endif
51#include <time.h> /* time_t */
52
53#define SHA_DIGEST_LENGTH 20
54#define TR_INET6_ADDRSTRLEN 46
55
56typedef uint32_t tr_file_index_t;
57typedef uint32_t tr_piece_index_t;
58typedef uint64_t tr_block_index_t;
59typedef uint16_t tr_port;
60typedef uint8_t tr_bool;
61
62/**
63 * @brief returns Transmission's default configuration file directory.
64 *
65 * The default configuration directory is determined this way:
66 * 1. If the TRANSMISSION_HOME environmental variable is set, its value is used.
67 * 2. On Darwin, "${HOME}/Library/Application Support/${appname}" is used.
68 * 3. On Windows, "${CSIDL_APPDATA}/${appname}" is used.
69 * 4. If XDG_CONFIG_HOME is set, "${XDG_CONFIG_HOME}/${appname}" is used.
70 * 5. ${HOME}/.config/${appname}" is used as a last resort.
71 */
72const char* tr_getDefaultConfigDir( const char * appname );
73
74/**
75 * @brief returns Transmisson's default download directory.
76 *
77 * The default download directory is determined this way:
78 * 1. If the HOME environmental variable is set, "${HOME}/Downloads" is used.
79 * 2. On Windows, "${CSIDL_MYDOCUMENTS}/Downloads" is used.
80 * 3. Otherwise, getpwuid(getuid())->pw_dir + "/Downloads" is used.
81 */
82const char* tr_getDefaultDownloadDir( void );
83
84typedef struct tr_ctor tr_ctor;
85typedef struct tr_info tr_info;
86typedef struct tr_torrent tr_torrent;
87typedef struct tr_session tr_session;
88
89
90/**
91 * @addtogroup tr_session Session
92 *
93 * A libtransmission session is created by calling tr_sessionInit().
94 * libtransmission creates a thread for itself so that it can operate
95 * independently of the caller's event loop.  The session will continue
96 * until tr_sessionClose() is called.
97 *
98 * @{
99 */
100
101typedef enum
102{
103    TR_PROXY_HTTP,
104    TR_PROXY_SOCKS4,
105    TR_PROXY_SOCKS5
106}
107tr_proxy_type;
108
109typedef enum
110{
111    TR_CLEAR_PREFERRED,
112    TR_ENCRYPTION_PREFERRED,
113    TR_ENCRYPTION_REQUIRED
114}
115tr_encryption_mode;
116
117#define TR_DEFAULT_RPC_WHITELIST "127.0.0.1"
118#define TR_DEFAULT_RPC_PORT_STR "9091"
119#define TR_DEFAULT_PEER_PORT_STR "51413"
120#define TR_DEFAULT_PEER_SOCKET_TOS_STR "8"
121
122#define TR_PREFS_KEY_BLOCKLIST_ENABLED          "blocklist-enabled"
123#define TR_PREFS_KEY_DOWNLOAD_DIR               "download-dir"
124#define TR_PREFS_KEY_DSPEED                     "download-limit"
125#define TR_PREFS_KEY_DSPEED_ENABLED             "download-limit-enabled"
126#define TR_PREFS_KEY_ENCRYPTION                 "encryption"
127#define TR_PREFS_KEY_LAZY_BITFIELD              "lazy-bitfield-enabled"
128#define TR_PREFS_KEY_MSGLEVEL                   "message-level"
129#define TR_PREFS_KEY_PEER_LIMIT_GLOBAL          "peer-limit-global"
130#define TR_PREFS_KEY_PEER_LIMIT_TORRENT         "peer-limit-per-torrent"
131#define TR_PREFS_KEY_PEER_PORT                  "peer-port"
132#define TR_PREFS_KEY_PEER_PORT_RANDOM_ENABLED   "peer-port-random-enabled"
133#define TR_PREFS_KEY_PEER_PORT_RANDOM_LOW       "peer-port-random-low"
134#define TR_PREFS_KEY_PEER_PORT_RANDOM_HIGH      "peer-port-random-high"
135#define TR_PREFS_KEY_PEER_SOCKET_TOS            "peer-socket-tos"
136#define TR_PREFS_KEY_PEX_ENABLED                "pex-enabled"
137#define TR_PREFS_KEY_PORT_FORWARDING            "port-forwarding-enabled"
138#define TR_PREFS_KEY_PROXY_AUTH_ENABLED         "proxy-auth-enabled"
139#define TR_PREFS_KEY_PROXY_ENABLED              "proxy-enabled"
140#define TR_PREFS_KEY_PROXY_PASSWORD             "proxy-auth-password"
141#define TR_PREFS_KEY_PROXY_PORT                 "proxy-port"
142#define TR_PREFS_KEY_PROXY                      "proxy"
143#define TR_PREFS_KEY_PROXY_TYPE                 "proxy-type"
144#define TR_PREFS_KEY_PROXY_USERNAME             "proxy-auth-username"
145#define TR_PREFS_KEY_RPC_AUTH_REQUIRED          "rpc-authentication-required"
146#define TR_PREFS_KEY_RPC_ENABLED                "rpc-enabled"
147#define TR_PREFS_KEY_RPC_PASSWORD               "rpc-password"
148#define TR_PREFS_KEY_RPC_PORT                   "rpc-port"
149#define TR_PREFS_KEY_RPC_USERNAME               "rpc-username"
150#define TR_PREFS_KEY_RPC_WHITELIST_ENABLED      "rpc-whitelist-enabled"
151#define TR_PREFS_KEY_RPC_WHITELIST              "rpc-whitelist"
152#define TR_PREFS_KEY_USPEED_ENABLED             "upload-limit-enabled"
153#define TR_PREFS_KEY_USPEED                     "upload-limit"
154
155struct tr_benc;
156
157/**
158 * Add libtransmission's default settings to the benc dictionary.
159 *
160 * Example:
161 * @code
162 *     tr_benc settings;
163 *     int64_t i;
164 *
165 *     tr_bencInitDict( &settings, 0 );
166 *     tr_sessionGetDefaultSettings( &settings );
167 *     if( tr_bencDictFindInt( &settings, TR_PREFS_KEY_PEER_PORT, &i ) )
168 *         fprintf( stderr, "the default peer port is %d\n", (int)i );
169 *     tr_bencFree( &settings );
170 * @endcode
171 *
172 * @param initme pointer to a tr_benc dictionary
173 * @see tr_sessionLoadSettings()
174 * @see tr_sessionInit()
175 * @see tr_getDefaultConfigDir()
176 */
177void tr_sessionGetDefaultSettings( struct tr_benc * dictionary );
178
179/**
180 * Add the session's configuration settings to the benc dictionary.
181 *
182 * FIXME: this probably belongs in libtransmissionapp
183 *
184 * @param session
185 * @param dictionary
186 * @see tr_sessionGetDefaultSettings()
187 */
188void tr_sessionGetSettings( tr_session *, struct tr_benc * dictionary );
189
190/**
191 * Load settings from the configuration directory's settings.json file,
192 * using libtransmission's default settings as fallbacks for missing keys.
193 *
194 * FIXME: this belongs in libtransmissionapp
195 *
196 * @param configDir the configuration directory to find settings.json
197 * @param initme pointer to an uninitialized tr_benc
198 * @param appName examples: Transmission, transmission-daemon
199 * @see tr_sessionGetDefaultSettings()
200 * @see tr_sessionInit()
201 * @see tr_sessionSaveSettings()
202 */
203void tr_sessionLoadSettings( struct tr_benc  * dictionary,
204                             const char      * configDir,
205                             const char      * appName );
206
207/**
208 * Add the session's configuration settings to the benc dictionary
209 * and save it to the configuration directory's settings.json file.
210 *
211 * FIXME: this belongs in libtransmissionapp
212 *
213 * @param session
214 * @param dictionary
215 * @see tr_sessionLoadSettings()
216 */
217void tr_sessionSaveSettings( tr_session     * session,
218                             const char     * configDir,
219                             struct tr_benc * dictonary );
220
221/**
222 * Initialize a libtransmission session.
223 *
224 * For example, this will instantiate a session with all the default values:
225 * @code
226 *     tr_benc settings;
227 *     tr_session * session;
228 *     const char * configDir;
229 *
230 *     tr_bencInitDict( &settings, 0 );
231 *     tr_sessionGetDefaultSettings( &settings );
232 *     configDir = tr_getDefaultConfigDir( "Transmission" );
233 *     session = tr_sessionInit( "mac", configDir, true, &settings );
234 *
235 *     tr_bencFree( &settings );
236 * @encode
237 *
238 * @param tag "gtk", "macosx", "daemon", etc... this is only for pre-1.30 resume files
239 * @param configDir where Transmission will look for resume files, blocklists, etc.
240 * @param messageQueueingEnabled if false, messages will be dumped to stderr
241 * @param settings libtransmission settings
242 * @see tr_sessionGetDefaultSettings()
243 * @see tr_sessionLoadSettings()
244 * @see tr_getDefaultConfigDir()
245 */
246tr_session * tr_sessionInit( const char     * tag,
247                             const char     * configDir,
248                             tr_bool          messageQueueingEnabled,
249                             struct tr_benc * settings );
250
251/** @brief End a libtransmission session
252    @see tr_sessionInit() */
253void tr_sessionClose( tr_session * );
254
255/**
256 * @brief Return the session's configuration directory
257 *
258 * This is where transmission stores its .torrent files, .resume files,
259 * blocklists, etc.
260 */
261const char * tr_sessionGetConfigDir( const tr_session * );
262
263/**
264 * @brief Set the per-session default download folder for new torrents.
265 * @see tr_sessionInit()
266 * @see tr_sessionGetDownloadDir()
267 * @see tr_ctorSetDownloadDir()
268 */
269void tr_sessionSetDownloadDir( tr_session  * session,
270                               const char  * downloadDir );
271
272/**
273 * @brief Get the default download folder for new torrents.
274 *
275 * This is set by tr_sessionInit() or tr_sessionSetDownloadDir(),
276 * and can be overridden on a per-torrent basis by tr_ctorSetDownloadDir().
277 */
278const char * tr_sessionGetDownloadDir( const tr_session * session );
279
280/**
281 * @brief Set whether or not RPC calls are allowed in this session.
282 *
283 * @details If true, libtransmission will open a server socket to listen
284 * for incoming http RPC requests as described in docs/rpc-spec.txt.
285 *
286 * This is intially set by tr_sessionInit() and can be
287 * queried by tr_sessionIsRPCEnabled().
288 */
289void tr_sessionSetRPCEnabled( tr_session  * session,
290                              tr_bool       isEnabled );
291
292/** @brief Get whether or not RPC calls are allowed in this session.
293    @see tr_sessionInit()
294    @see tr_sessionSetRPCEnabled() */
295tr_bool tr_sessionIsRPCEnabled( const tr_session * session );
296
297/** @brief Specify which port to listen for RPC requests on.
298    @see tr_sessionInit()
299    @see tr_sessionGetRPCPort */
300void tr_sessionSetRPCPort( tr_session  * session,
301                           tr_port       port );
302
303/** @brief Get which port to listen for RPC requests on.
304    @see tr_sessionInit()
305    @see tr_sessionSetRPCPort */
306tr_port tr_sessionGetRPCPort( const tr_session * session );
307
308/**
309 * @brief Specify a whitelist for remote RPC access
310 *
311 * The whitelist is a comma-separated list of dotted-quad IP addresses
312 * to be allowed.  Wildmat notation is supported, meaning that
313 * '?' is interpreted as a single-character wildcard and
314 * '*' is interprted as a multi-character wildcard.
315 */
316void   tr_sessionSetRPCWhitelist( tr_session * session,
317                                  const char * whitelist );
318
319/** @brief get the Access Control List for allowing/denying RPC requests.
320    @return a comma-separated string of whitelist domains.  tr_free() when done.
321    @see tr_sessionInit
322    @see tr_sessionSetRPCWhitelist */
323char* tr_sessionGetRPCWhitelist( const tr_session * );
324
325void  tr_sessionSetRPCWhitelistEnabled( tr_session * session,
326                                        tr_bool      isEnabled );
327
328tr_bool tr_sessionGetRPCWhitelistEnabled( const tr_session * session );
329
330void  tr_sessionSetRPCPassword( tr_session * session,
331                                const char * password );
332
333void  tr_sessionSetRPCUsername( tr_session * session,
334                                const char * username );
335
336/** @brief get the password used to restrict RPC requests.
337    @return the password string. tr_free() when done.
338    @see tr_sessionInit()
339    @see tr_sessionSetRPCPassword() */
340char* tr_sessionGetRPCPassword( const tr_session * session );
341
342char* tr_sessionGetRPCUsername( const tr_session * session  );
343
344void  tr_sessionSetRPCPasswordEnabled( tr_session * session,
345                                       tr_bool      isEnabled );
346
347tr_bool tr_sessionIsRPCPasswordEnabled( const tr_session * session );
348
349
350typedef enum
351{
352    TR_RPC_TORRENT_ADDED,
353    TR_RPC_TORRENT_STARTED,
354    TR_RPC_TORRENT_STOPPED,
355    TR_RPC_TORRENT_REMOVING,
356    TR_RPC_TORRENT_CHANGED, /* catch-all for the "torrent-set" rpc method */
357    TR_RPC_SESSION_CHANGED
358}
359tr_rpc_callback_type;
360
361typedef enum
362{
363    /* no special handling is needed by the caller */
364    TR_RPC_OK            = 0,
365
366    /* indicates to the caller that the client will take care of
367     * removing the torrent itself.  For example the client may
368     * need to keep the torrent alive long enough to cleanly close
369     * some resources in another thread. */
370    TR_RPC_NOREMOVE   = ( 1 << 1 )
371}
372tr_rpc_callback_status;
373
374typedef tr_rpc_callback_status (*tr_rpc_func)(tr_session          * session,
375                                              tr_rpc_callback_type  type,
376                                              struct tr_torrent   * tor_or_null,
377                                              void                * user_data );
378
379/**
380 * Register to be notified whenever something is changed via RPC,
381 * such as a torrent being added, removed, started, stopped, etc.
382 *
383 * func is invoked FROM LIBTRANSMISSION'S THREAD!
384 * This means func must be fast (to avoid blocking peers),
385 * shouldn't call libtransmission functions (to avoid deadlock),
386 * and shouldn't modify client-level memory without using a mutex!
387 */
388void tr_sessionSetRPCCallback( tr_session   * session,
389                               tr_rpc_func    func,
390                               void         * user_data );
391
392/**
393***
394**/
395
396tr_bool       tr_sessionIsProxyEnabled( const tr_session * );
397
398tr_bool       tr_sessionIsProxyAuthEnabled( const tr_session * );
399
400const char*   tr_sessionGetProxy( const tr_session * );
401
402tr_port       tr_sessionGetProxyPort( const tr_session * );
403
404tr_proxy_type tr_sessionGetProxyType( const tr_session * );
405
406const char*   tr_sessionGetProxyUsername( const tr_session * );
407
408const char*   tr_sessionGetProxyPassword( const tr_session * );
409
410void          tr_sessionSetProxyEnabled( tr_session * session,
411                                         tr_bool      isEnabled );
412
413void          tr_sessionSetProxyAuthEnabled( tr_session * session,
414                                             tr_bool      isEnabled );
415
416void          tr_sessionSetProxy( tr_session * session,
417                                  const char * proxy );
418
419void          tr_sessionSetProxyPort( tr_session * session,
420                                      tr_port      port );
421
422void          tr_sessionSetProxyType( tr_session    * session,
423                                      tr_proxy_type   proxy_type );
424
425void          tr_sessionSetProxyUsername( tr_session * session,
426                                          const char * username );
427
428void          tr_sessionSetProxyPassword( tr_session * session,
429                                          const char * password );
430
431/**
432***
433**/
434
435typedef struct tr_session_stats
436{
437    float       ratio;        /* TR_RATIO_INF, TR_RATIO_NA, or total up/down */
438    uint64_t    uploadedBytes; /* total up */
439    uint64_t    downloadedBytes; /* total down */
440    uint64_t    filesAdded;   /* number of files added */
441    uint64_t    sessionCount; /* program started N times */
442    uint64_t    secondsActive; /* how long Transmisson's been running */
443}
444tr_session_stats;
445
446/* stats from the current session. */
447void               tr_sessionGetStats( const tr_session * session,
448                                       tr_session_stats * setme );
449
450/* stats from the current and past sessions. */
451void               tr_sessionGetCumulativeStats( const tr_session * session,
452                                                 tr_session_stats * setme );
453
454void               tr_sessionClearStats( tr_session * session );
455
456/**
457 * Set whether or not torrents are allowed to do peer exchanges.
458 * PEX is always disabled in private torrents regardless of this.
459 * In public torrents, PEX is enabled by default.
460 */
461void               tr_sessionSetPexEnabled( tr_session  * session,
462                                            tr_bool       isEnabled );
463
464tr_bool            tr_sessionIsPexEnabled( const tr_session * session );
465
466void               tr_sessionSetLazyBitfieldEnabled( tr_session * session,
467                                                     tr_bool       enabled );
468
469tr_bool            tr_sessionIsLazyBitfieldEnabled( const tr_session * session );
470
471tr_encryption_mode tr_sessionGetEncryption( tr_session * session );
472
473void               tr_sessionSetEncryption( tr_session          * session,
474                                            tr_encryption_mode    mode );
475
476
477/***********************************************************************
478** Incoming Peer Connections Port
479*/
480
481void  tr_sessionSetPortForwardingEnabled( tr_session  * session,
482                                          tr_bool       enabled );
483
484tr_bool tr_sessionIsPortForwardingEnabled( const tr_session  * session );
485
486void  tr_sessionSetPeerPort( tr_session  * session,
487                             tr_port       port);
488
489tr_port tr_sessionSetPeerPortRandom( tr_session  * session );
490
491tr_port tr_sessionGetPeerPort( const tr_session * session );
492
493typedef enum
494{
495    TR_PORT_ERROR,
496    TR_PORT_UNMAPPED,
497    TR_PORT_UNMAPPING,
498    TR_PORT_MAPPING,
499    TR_PORT_MAPPED
500}
501tr_port_forwarding;
502
503tr_port_forwarding tr_sessionGetPortForwarding( const tr_session * session );
504
505int tr_sessionCountTorrents( const tr_session * session );
506
507typedef enum
508{
509    TR_CLIENT_TO_PEER = 0, TR_UP = 0,
510    TR_PEER_TO_CLIENT = 1, TR_DOWN = 1
511}
512tr_direction;
513
514void       tr_sessionSetSpeedLimitEnabled ( tr_session        * session,
515                                            tr_direction        direction,
516                                            tr_bool             isEnabled );
517
518tr_bool    tr_sessionIsSpeedLimitEnabled  ( const tr_session  * session,
519                                            tr_direction        direction );
520
521void       tr_sessionSetSpeedLimit        ( tr_session        * session,
522                                            tr_direction        direction,
523                                            int                 KiB_sec );
524
525int        tr_sessionGetSpeedLimit        ( const tr_session  * session,
526                                            tr_direction        direction );
527
528double     tr_sessionGetRawSpeed          ( const tr_session  * session,
529                                           tr_direction         direction );
530
531double     tr_sessionGetPieceSpeed        ( const tr_session  * session,
532                                            tr_direction        direction );
533
534
535void       tr_sessionSetPeerLimit( tr_session  * session,
536                                   uint16_t      maxGlobalPeers );
537
538uint16_t   tr_sessionGetPeerLimit( const tr_session * session );
539
540void       tr_sessionSetPeerLimitPerTorrent( tr_session  * session,
541                                             uint16_t      maxGlobalPeers );
542
543uint16_t   tr_sessionGetPeerLimitPerTorrent( const tr_session * session );
544
545
546/**
547 *  Load all the torrents in tr_getTorrentDir().
548 *  This can be used at startup to kickstart all the torrents
549 *  from the previous session.
550 */
551tr_torrent ** tr_sessionLoadTorrents( tr_session  * session,
552                                      tr_ctor     * ctor,
553                                      int         * setmeCount );
554
555/** @} */
556
557/**
558***
559**/
560
561
562/***********************************************************************
563** Message Logging
564*/
565
566enum
567{
568    TR_MSG_ERR = 1,
569    TR_MSG_INF = 2,
570    TR_MSG_DBG = 3
571};
572void tr_setMessageLevel( int );
573
574int  tr_getMessageLevel( void );
575
576typedef struct tr_msg_list
577{
578    /* TR_MSG_ERR, TR_MSG_INF, or TR_MSG_DBG */
579    uint8_t level;
580
581    /* The line number in the source file where this message originated */
582    int line;
583
584    /* Time the message was generated */
585    time_t when;
586
587    /* The torrent associated with this message,
588     * or a module name such as "Port Forwarding" for non-torrent messages,
589     * or NULL. */
590    char *  name;
591
592    /* The message */
593    char *  message;
594
595    /* The source file where this message originated */
596    const char * file;
597
598    /* linked list of messages */
599    struct tr_msg_list * next;
600}
601tr_msg_list;
602
603void          tr_setMessageQueuing( tr_bool isEnabled );
604
605tr_bool       tr_getMessageQueuing( void );
606
607tr_msg_list * tr_getQueuedMessages( void );
608
609void          tr_freeMessageList( tr_msg_list * freeme );
610
611/** @addtogroup Blocklists
612    @{ */
613
614/**
615 * Specify a range of IPs for Transmission to block.
616 *
617 * filename must be an uncompressed ascii file,
618 * using the same format as the bluetack level1 file.
619 *
620 * libtransmission does not keep a handle to `filename'
621 * after this call returns, so the caller is free to
622 * keep or delete `filename' as it wishes.
623 * libtransmission makes its own copy of the file
624 * massaged into a format easier to search.
625 *
626 * The caller only needs to invoke this when the blocklist
627 * has changed.
628 *
629 * Passing NULL for a filename will clear the blocklist.
630 */
631int     tr_blocklistSetContent   ( tr_session       * session,
632                                   const char       * filename );
633
634int     tr_blocklistGetRuleCount ( const tr_session * session );
635
636tr_bool tr_blocklistExists       ( const tr_session * session );
637
638tr_bool tr_blocklistIsEnabled    ( const tr_session * session );
639
640void    tr_blocklistSetEnabled   ( tr_session       * session,
641                                   tr_bool            isEnabled );
642
643
644/** @} */
645
646
647/** @addtogroup tr_ctor Torrent Instantiation
648    @{
649
650    Instantiating a tr_torrent had gotten more complicated as features were
651    added.  At one point there were four functions to check metainfo and five
652    to create tr_torrent.
653
654    To remedy this, a Torrent Constructor (struct tr_ctor) has been introduced:
655    - Simplifies the API to two functions: tr_torrentParse() and tr_torrentNew()
656    - You can set the fields you want; the system sets defaults for the rest.
657    - You can specify whether or not your fields should supercede resume's.
658    - We can add new features to tr_ctor without breaking tr_torrentNew()'s API.
659
660    All the tr_ctor{Get,Set}*() functions with a return value return
661    an error number, or zero if no error occurred.
662
663    You must call one of the SetMetainfo() functions before creating
664    a torrent with a tr_ctor.  The other functions are optional.
665
666    You can reuse a single tr_ctor to create a batch of torrents --
667    just call one of the SetMetainfo() functions between each
668    tr_torrentNew() call.
669
670    Every call to tr_ctorSetMetainfo*() frees the previous metainfo.
671 */
672
673typedef enum
674{
675    TR_FALLBACK, /* indicates the ctor value should be used only
676                    in case of missing resume settings */
677
678    TR_FORCE, /* indicates the ctor value should be used
679                 regardless of what's in the resume settings */
680}
681tr_ctorMode;
682
683struct tr_benc;
684
685tr_ctor*    tr_ctorNew( const tr_session * session );
686
687void        tr_ctorFree( tr_ctor * ctor );
688
689void        tr_ctorSetDeleteSource( tr_ctor * ctor,
690                                    tr_bool   doDelete );
691
692int         tr_ctorSetMetainfo( tr_ctor *       ctor,
693                                const uint8_t * metainfo,
694                                size_t          len );
695
696int         tr_ctorSetMetainfoFromFile( tr_ctor *    ctor,
697                                        const char * filename );
698
699int         tr_ctorSetMetainfoFromHash( tr_ctor *    ctor,
700                                        const char * hashString );
701
702/** Set the maximum number of peers this torrent can connect to.
703    (Default: 50) */
704void        tr_ctorSetPeerLimit( tr_ctor *   ctor,
705                                 tr_ctorMode mode,
706                                 uint16_t    peerLimit  );
707
708/** Set the download folder for the torrent being added with this ctor.
709    @see tr_ctorSetDownloadDir()
710    @see tr_sessionInit() */
711void        tr_ctorSetDownloadDir( tr_ctor *    ctor,
712                                   tr_ctorMode  mode,
713                                   const char * directory );
714
715/** Set whether or not the torrent begins downloading/seeding when created.
716    (Default: not paused) */
717void        tr_ctorSetPaused( tr_ctor      * ctor,
718                              tr_ctorMode    mode,
719                              tr_bool        isPaused );
720
721int         tr_ctorGetPeerLimit( const tr_ctor * ctor,
722                                 tr_ctorMode     mode,
723                                 uint16_t *      setmeCount );
724
725int         tr_ctorGetPaused( const tr_ctor * ctor,
726                              tr_ctorMode     mode,
727                              tr_bool       * setmeIsPaused );
728
729int         tr_ctorGetDownloadDir( const tr_ctor  * ctor,
730                                   tr_ctorMode      mode,
731                                   const char    ** setmeDownloadDir );
732
733int         tr_ctorGetMetainfo( const tr_ctor         * ctor,
734                                const struct tr_benc ** setme );
735
736int         tr_ctorGetDeleteSource( const tr_ctor  * ctor,
737                                    tr_bool        * setmeDoDelete );
738
739/* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
740const char* tr_ctorGetSourceFile( const tr_ctor * ctor );
741
742#define TR_EINVALID     1
743#define TR_EDUPLICATE   2
744
745/**
746 * Parses the specified metainfo.
747 * Returns 0 if it parsed successfully and can be added to Transmission.
748 * Returns TR_EINVALID if it couldn't be parsed.
749 * Returns TR_EDUPLICATE if it parsed but can't be added.
750 *     "download-dir" must be set to test for TR_EDUPLICATE.
751 *
752 * If setme_info is non-NULL and parsing is successful
753 * (that is, if TR_EINVALID is not returned), then the parsed
754 * metainfo is stored in setme_info and should be freed by the
755 * caller via tr_metainfoFree().
756 */
757int tr_torrentParse( const tr_session  * session,
758                     const tr_ctor     * ctor,
759                     tr_info           * setme_info_or_NULL );
760
761/** @brief free a metainfo
762    @see tr_torrentParse */
763void tr_metainfoFree( tr_info * inf );
764
765
766/** Instantiate a single torrent.
767    @return 0 on success,
768            TR_EINVALID if the torrent couldn't be parsed, or
769            TR_EDUPLICATE if there's already a matching torrent object. */
770tr_torrent * tr_torrentNew( tr_session      * session,
771                            const tr_ctor   * ctor,
772                            int             * setmeError );
773
774/** @} */
775
776/***********************************************************************
777 ***
778 ***  TORRENTS
779 **/
780
781/** @addtogroup tr_torrent Torrents
782    @{ */
783
784/** @brief Frees memory allocated by tr_torrentNew().
785           Running torrents are stopped first.  */
786void tr_torrentFree( tr_torrent * torrent );
787
788/** @brief Removes our .torrent and .resume files for
789           this torrent, then calls tr_torrentFree(). */
790void tr_torrentRemove( tr_torrent * torrent );
791
792/** @brief Start a torrent */
793void tr_torrentStart( tr_torrent * torrent );
794
795/** @brief Stop (pause) a torrent */
796void tr_torrentStop( tr_torrent * torrent );
797
798/** @brief Deletes the torrent data stored on disk. */
799void tr_torrentDeleteLocalData( tr_torrent * torrent );
800
801/**
802 * @brief Iterate through the torrents.
803 *
804 * Pass in a NULL pointer to get the first torrent.
805 */
806tr_torrent* tr_torrentNext( tr_session  * session,
807                            tr_torrent  * current );
808
809
810uint64_t tr_torrentGetBytesLeftToAllocate( const tr_torrent * torrent );
811
812/**
813 * @brief Returns this torrent's unique ID.
814 *
815 * IDs are good as simple lookup keys, but are not persistent
816 * between sessions.  If you need that, use tr_info.hash or
817 * tr_info.hashString.
818 */
819int tr_torrentId( const tr_torrent * torrent );
820
821/****
822*****  Speed Limits
823****/
824
825typedef enum
826{
827    TR_SPEEDLIMIT_GLOBAL,    /* only follow the overall speed limit */
828    TR_SPEEDLIMIT_SINGLE,    /* only follow the per-torrent limit */
829    TR_SPEEDLIMIT_UNLIMITED  /* no limits at all */
830}
831tr_speedlimit;
832
833void          tr_torrentSetSpeedMode( tr_torrent     * tor,
834                                      tr_direction     up_or_down,
835                                      tr_speedlimit    mode );
836
837tr_speedlimit tr_torrentGetSpeedMode( const tr_torrent * tor,
838                                      tr_direction       direction );
839
840void          tr_torrentSetSpeedLimit( tr_torrent    * tor,
841                                       tr_direction    up_or_down,
842                                       int             KiB_sec );
843
844int           tr_torrentGetSpeedLimit( const tr_torrent  * tor,
845                                       tr_direction        direction );
846
847/****
848*****  Peer Limits
849****/
850
851void          tr_torrentSetPeerLimit( tr_torrent * tor,
852                                      uint16_t     peerLimit );
853
854uint16_t      tr_torrentGetPeerLimit( const tr_torrent * tor );
855
856/****
857*****  File Priorities
858****/
859
860enum
861{
862    TR_PRI_LOW    = -1,
863    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
864    TR_PRI_HIGH   =  1
865};
866
867typedef int8_t tr_priority_t;
868
869/**
870 * @brief Set a batch of files to a particular priority.
871 *
872 * @param priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW
873 */
874void tr_torrentSetFilePriorities( tr_torrent       * torrent,
875                                  tr_file_index_t  * files,
876                                  tr_file_index_t    fileCount,
877                                  tr_priority_t      priority );
878
879/**
880 * @brief Get this torrent's file priorities.
881 *
882 * @return A malloc()ed array of tor->info.fileCount items,
883 *         each holding a TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
884 *         It's the caller's responsibility to free() this.
885 */
886tr_priority_t*  tr_torrentGetFilePriorities( const tr_torrent * torrent );
887
888/**
889 * @brief Single-file form of tr_torrentGetFilePriorities.
890 * @return TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
891 */
892tr_priority_t   tr_torrentGetFilePriority( const tr_torrent  * torrent,
893                                           tr_file_index_t     file );
894
895/**
896 * @brief See if a file's `download' flag is set.
897 * @return true if the file's `download' flag is set.
898 */
899int tr_torrentGetFileDL( const tr_torrent  * torrent,
900                         tr_file_index_t     file );
901
902/** @brief Set a batch of files to be downloaded or not. */
903void            tr_torrentSetFileDLs( tr_torrent       * torrent,
904                                      tr_file_index_t  * files,
905                                      tr_file_index_t    fileCount,
906                                      tr_bool            do_download );
907
908
909const tr_info * tr_torrentInfo( const tr_torrent * torrent );
910
911void tr_torrentSetDownloadDir( tr_torrent  * torrent,
912                               const char  * path );
913
914const char * tr_torrentGetDownloadDir( const tr_torrent * torrent );
915
916/**
917***
918**/
919
920typedef struct tr_tracker_info
921{
922    int     tier;
923    char *  announce;
924    char *  scrape;
925}
926tr_tracker_info;
927
928/**
929 * @brief Modify a torrent's tracker list.
930 *
931 * This updates both the `torrent' object's tracker list
932 * and the metainfo file in tr_sessionGetConfigDir()'s torrent subdirectory.
933 *
934 * @param torrent The torrent whose tracker list is to be modified
935 * @param trackers An array of trackers, sorted by tier from first to last.
936 *                 NOTE: only the `tier' and `announce' fields are used.
937 *                 libtransmission derives `scrape' from `announce'.
938 * @param trackerCount size of the `trackers' array
939 */
940void tr_torrentSetAnnounceList( tr_torrent *            torrent,
941                                const tr_tracker_info * trackers,
942                                int                     trackerCount );
943
944
945/**
946***
947**/
948
949typedef enum
950{
951    TR_LEECH,           /* doesn't have all the desired pieces */
952    TR_SEED,            /* has the entire torrent */
953    TR_PARTIAL_SEED     /* has the desired pieces, but not the entire torrent */
954}
955tr_completeness;
956
957typedef void ( tr_torrent_completeness_func )( tr_torrent       * torrent,
958                                               tr_completeness    completeness,
959                                               void             * user_data );
960
961/**
962 * Register to be notified whenever a torrent's "completeness"
963 * changes.  This will be called, for example, when a torrent
964 * finishes downloading and changes from TR_LEECH to
965 * either TR_SEED or TR_PARTIAL_SEED.
966 *
967 * func is invoked FROM LIBTRANSMISSION'S THREAD!
968 * This means func must be fast (to avoid blocking peers),
969 * shouldn't call libtransmission functions (to avoid deadlock),
970 * and shouldn't modify client-level memory without using a mutex!
971 *
972 * @see tr_completeness
973 */
974void tr_torrentSetCompletenessCallback(
975         tr_torrent                    * torrent,
976         tr_torrent_completeness_func    func,
977         void                          * user_data );
978
979void tr_torrentClearCompletenessCallback( tr_torrent * torrent );
980
981
982/**
983 * MANUAL ANNOUNCE
984 *
985 * Trackers usually set an announce interval of 15 or 30 minutes.
986 * Users can send one-time announce requests that override this
987 * interval by calling tr_torrentManualUpdate().
988 *
989 * The wait interval for tr_torrentManualUpdate() is much smaller.
990 * You can test whether or not a manual update is possible
991 * (for example, to desensitize the button) by calling
992 * tr_torrentCanManualUpdate().
993 */
994
995void tr_torrentManualUpdate( tr_torrent * torrent );
996
997int  tr_torrentCanManualUpdate( const tr_torrent * torrent );
998
999/***********************************************************************
1000* tr_torrentPeers
1001***********************************************************************/
1002
1003typedef struct tr_peer_stat
1004{
1005    tr_bool      isEncrypted;
1006    tr_bool      isDownloadingFrom;
1007    tr_bool      isUploadingTo;
1008    tr_bool      isSeed;
1009
1010    tr_bool      peerIsChoked;
1011    tr_bool      peerIsInterested;
1012    tr_bool      clientIsChoked;
1013    tr_bool      clientIsInterested;
1014    tr_bool      isIncoming;
1015
1016    uint8_t      from;
1017    tr_port      port;
1018
1019    char         addr[TR_INET6_ADDRSTRLEN];
1020    char         client[80];
1021    char         flagStr[32];
1022
1023    float        progress;
1024    float        rateToPeer;
1025    float        rateToClient;
1026}
1027tr_peer_stat;
1028
1029tr_peer_stat * tr_torrentPeers( const tr_torrent * torrent,
1030                                int *              peerCount );
1031
1032void           tr_torrentPeersFree( tr_peer_stat * peerStats,
1033                                    int            peerCount );
1034
1035/**
1036 * @brief get the download speeds for each of this torrent's webseed sources.
1037 *
1038 * @return an array of tor->info.webseedCount floats giving download speeds.
1039 *         Each speed in the array corresponds to the webseed at the same
1040 *         array index in tor->info.webseeds.
1041 *         To differentiate "idle" and "stalled" status, idle webseeds will
1042 *         return -1 instead of 0 KiB/s.
1043 *         NOTE: always free this array with tr_free() when you're done with it.
1044 */
1045float*         tr_torrentWebSpeeds( const tr_torrent * torrent );
1046
1047typedef struct tr_file_stat
1048{
1049    uint64_t    bytesCompleted;
1050    float       progress;
1051}
1052tr_file_stat;
1053
1054tr_file_stat * tr_torrentFiles( const tr_torrent  * torrent,
1055                                tr_file_index_t   * fileCount );
1056
1057void tr_torrentFilesFree( tr_file_stat     * files,
1058                          tr_file_index_t    fileCount );
1059
1060
1061/***********************************************************************
1062 * tr_torrentAvailability
1063 ***********************************************************************
1064 * Use this to draw an advanced progress bar which is 'size' pixels
1065 * wide. Fills 'tab' which you must have allocated: each byte is set
1066 * to either -1 if we have the piece, otherwise it is set to the number
1067 * of connected peers who have the piece.
1068 **********************************************************************/
1069void tr_torrentAvailability( const tr_torrent  * torrent,
1070                             int8_t            * tab,
1071                             int                  size );
1072
1073void tr_torrentAmountFinished( const tr_torrent  * torrent,
1074                               float *             tab,
1075                               int                 size );
1076
1077void tr_torrentVerify( tr_torrent * torrent );
1078
1079/***********************************************************************
1080 * tr_info
1081 **********************************************************************/
1082
1083typedef struct tr_file
1084{
1085    uint64_t            length;    /* Length of the file, in bytes */
1086    char *              name;      /* Path to the file */
1087    int8_t              priority;  /* TR_PRI_HIGH, _NORMAL, or _LOW */
1088    int8_t              dnd;       /* nonzero if the file shouldn't be
1089                                     downloaded */
1090    tr_piece_index_t    firstPiece; /* We need pieces [firstPiece... */
1091    tr_piece_index_t    lastPiece; /* ...lastPiece] to dl this file */
1092    uint64_t            offset;    /* file begins at the torrent's nth byte */
1093}
1094tr_file;
1095
1096typedef struct tr_piece
1097{
1098    uint8_t    hash[SHA_DIGEST_LENGTH]; /* pieces hash */
1099    int8_t     priority;               /* TR_PRI_HIGH, _NORMAL, or _LOW */
1100    int8_t     dnd;                    /* nonzero if the piece shouldn't be
1101                                         downloaded */
1102}
1103tr_piece;
1104
1105struct tr_info
1106{
1107    /* Flags */
1108    tr_bool            isPrivate;
1109    tr_bool            isMultifile;
1110
1111    /* General info */
1112    uint8_t            hash[SHA_DIGEST_LENGTH];
1113    char               hashString[2 * SHA_DIGEST_LENGTH + 1];
1114    char            *  name;
1115
1116    /* Path to torrent Transmission's internal copy of the .torrent file.
1117       This field exists for compatability reasons in the Mac OS X client
1118       and should not be used in new code. */
1119    char            *  torrent;
1120
1121    /* these trackers are sorted by tier */
1122    tr_tracker_info *  trackers;
1123    int                trackerCount;
1124
1125    char           **  webseeds;
1126    int                webseedCount;
1127
1128    /* Torrent info */
1129    char             * comment;
1130    char             * creator;
1131    time_t             dateCreated;
1132
1133    /* Pieces info */
1134    uint32_t           pieceSize;
1135    tr_piece_index_t   pieceCount;
1136    uint64_t           totalSize;
1137    tr_piece *         pieces;
1138
1139    /* Files info */
1140    tr_file_index_t    fileCount;
1141    tr_file *          files;
1142};
1143
1144/**
1145 * What the torrent is doing right now.
1146 *
1147 * Note: these values will become a straight enum at some point in the future.
1148 * Do not rely on their current `bitfield' implementation
1149 */
1150typedef enum
1151{
1152    TR_STATUS_CHECK_WAIT   = ( 1 << 0 ), /* Waiting in queue to check files */
1153    TR_STATUS_CHECK        = ( 1 << 1 ), /* Checking files */
1154    TR_STATUS_DOWNLOAD     = ( 1 << 2 ), /* Downloading */
1155    TR_STATUS_SEED         = ( 1 << 3 ), /* Seeding */
1156    TR_STATUS_STOPPED      = ( 1 << 4 )  /* Torrent is stopped */
1157}
1158tr_torrent_activity;
1159
1160tr_torrent_activity tr_torrentGetActivity( tr_torrent * );
1161
1162#define TR_STATUS_IS_ACTIVE( s ) ( ( s ) != TR_STATUS_STOPPED )
1163
1164typedef enum
1165{
1166    TR_LOCKFILE_SUCCESS = 0,
1167    TR_LOCKFILE_EOPEN,
1168    TR_LOCKFILE_ELOCK
1169}
1170tr_lockfile_state_t;
1171
1172enum
1173{
1174    TR_PEER_FROM_INCOMING  = 0,  /* connections made to the listening port */
1175    TR_PEER_FROM_TRACKER   = 1,  /* peers received from a tracker */
1176    TR_PEER_FROM_CACHE     = 2,  /* peers read from the peer cache */
1177    TR_PEER_FROM_PEX       = 3,  /* peers discovered via PEX */
1178    TR_PEER_FROM__MAX
1179};
1180
1181/** Can be used as a mnemonic for "no error" errno */
1182#define TR_OK 0
1183
1184/**
1185 * The current status of a torrent.
1186 * @see tr_torrentStat()
1187 */
1188typedef struct tr_stat
1189{
1190    /** The torrent's unique Id.
1191        @see tr_torrentId() */
1192    int    id;
1193
1194    /** What is this torrent doing right now? */
1195    tr_torrent_activity activity;
1196
1197    /** Our current announce URL, or NULL if none.
1198        This URL may change during the session if the torrent's
1199        metainfo has multiple trackers and the current one
1200        becomes unreachable. */
1201    char *  announceURL;
1202
1203    /** Our current scrape URL, or NULL if none.
1204        This URL may change during the session if the torrent's
1205        metainfo has multiple trackers and the current one
1206        becomes unreachable. */
1207    char *  scrapeURL;
1208
1209    /** The errno status for this torrent.  0 means everything's fine. */
1210    int     error;
1211
1212    /** Typically an error string returned from the tracker. */
1213    char    errorString[128];
1214
1215    /** When tr_stat.status is TR_STATUS_CHECK or TR_STATUS_CHECK_WAIT,
1216        this is the percentage of how much of the files has been
1217        verified.  When it gets to 1, the verify process is done.
1218        Range is [0..1]
1219        @see tr_stat.status */
1220    float    recheckProgress;
1221
1222    /** How much has been downloaded of the entire torrent.
1223        Range is [0..1] */
1224    float    percentComplete;
1225
1226    /** How much has been downloaded of the files the user wants.  This differs
1227        from percentComplete if the user wants only some of the torrent's files.
1228        Range is [0..1]
1229        @see tr_stat.leftUntilDone */
1230    float    percentDone;
1231
1232    /** Speed all data being sent for this torrent. (KiB/s)
1233        This includes piece data, protocol messages, and TCP overhead */
1234    double rawUploadSpeed;
1235
1236    /** Speed all data being received for this torrent. (KiB/s)
1237        This includes piece data, protocol messages, and TCP overhead */
1238    double rawDownloadSpeed;
1239
1240    /** Speed all piece being sent for this torrent. (KiB/s)
1241        This ONLY counts piece data. */
1242    double pieceUploadSpeed;
1243
1244    /** Speed all piece being received for this torrent. (KiB/s)
1245        This ONLY counts piece data. */
1246    double pieceDownloadSpeed;
1247
1248#define TR_ETA_NOT_AVAIL -1
1249#define TR_ETA_UNKNOWN -2
1250    /** Estimated number of seconds left until the torrent is done,
1251        or TR_ETA_NOT_AVAIL or TR_ETA_UNKNOWN */
1252    int    eta;
1253
1254    /** Number of peers that the tracker says this torrent has */
1255    int    peersKnown;
1256
1257    /** Number of peers that we're connected to */
1258    int    peersConnected;
1259
1260    /** How many peers we found out about from the tracker, or from pex,
1261        or from incoming connections, or from our resume file. */
1262    int    peersFrom[TR_PEER_FROM__MAX];
1263
1264    /** Number of peers that are sending data to us. */
1265    int    peersSendingToUs;
1266
1267    /** Number of peers that we're sending data to */
1268    int    peersGettingFromUs;
1269
1270    /** Number of webseeds that are sending data to us. */
1271    int    webseedsSendingToUs;
1272
1273    /** Number of seeders that the tracker says this torrent has */
1274    int    seeders;
1275
1276    /** Number of leechers that the tracker says this torrent has */
1277    int    leechers;
1278
1279    /** Number of downloaders that the tracker says this torrent has.
1280        This is a new key introduced in BEP 21 and may not be supported by some trackers.
1281        If the tracker doesn't support this key, the value here will be -1. */
1282    int    downloaders;
1283
1284    /** Number of finished downloads that the tracker says torrent has */
1285    int    timesCompleted;
1286
1287    /** Byte count of all the piece data we'll have downloaded when we're done,
1288        whether or not we have it yet.  This may be less than tr_info.totalSize
1289        if only some of the torrent's files are wanted.
1290        [0...tr_info.totalSize] */
1291    uint64_t    sizeWhenDone;
1292
1293    /** Byte count of how much data is left to be downloaded until we've got
1294        all the pieces that we want.  [0...tr_info.sizeWhenDone] */
1295    uint64_t    leftUntilDone;
1296
1297    /** Byte count of all the piece data we want and don't have yet,
1298        but that a connected peer does have. [0...leftUntilDone] */
1299    uint64_t    desiredAvailable;
1300
1301    /** Byte count of all the corrupt data you've ever downloaded for
1302        this torrent.  If you're on a poisoned torrent, this number can
1303        grow very large. */
1304    uint64_t    corruptEver;
1305
1306    /** Byte count of all data you've ever uploaded for this torrent. */
1307    uint64_t    uploadedEver;
1308
1309    /** Byte count of all the non-corrupt data you've ever downloaded
1310        for this torrent.  If you deleted the files and downloaded a second
1311        time, this will be 2*totalSize.. */
1312    uint64_t    downloadedEver;
1313
1314    /** Byte count of all the checksum-verified data we have for this torrent.
1315      */
1316    uint64_t    haveValid;
1317
1318    /** Byte count of all the partial piece data we have for this torrent.
1319        As pieces become complete, this value may decrease as portions of it
1320        are moved to `corrupt' or `haveValid'. */
1321    uint64_t    haveUnchecked;
1322
1323    /** This is the unmodified string returned by the tracker in response
1324        to the torrent's most recent scrape request.  If no request was
1325        sent or there was no response, this string is empty. */
1326    char    scrapeResponse[64];
1327
1328    /** The unmodified string returned by the tracker in response
1329        to the torrent's most recent scrape request.  If no request was
1330        sent or there was no response, this string is empty. */
1331    char    announceResponse[64];
1332
1333    /** Time the most recent scrape request was sent,
1334        or zero if one hasn't been sent yet. */
1335    time_t    lastScrapeTime;
1336
1337    /** Time when the next scrape request will be sent,
1338        or 0 if an error has occured that stops scraping,
1339        or 1 if a scrape is currently in progress s.t.
1340        we haven't set a timer for the next one yet. */
1341    time_t    nextScrapeTime;
1342
1343    /** Time the most recent announce request was sent,
1344        or zero if one hasn't been sent yet. */
1345    time_t    lastAnnounceTime;
1346
1347    /** Time when the next reannounce request will be sent,
1348        or 0 if the torrent is stopped,
1349        or 1 if an announce is currently in progress s.t.
1350        we haven't set a timer for the next one yet */
1351    time_t    nextAnnounceTime;
1352
1353    /** If the torrent is running, this is the time at which
1354        the client can manually ask the torrent's tracker
1355        for more peers,
1356        or 0 if the torrent is stopped or doesn't allow manual,
1357        or 1 if an announce is currently in progress s.t.
1358        we haven't set a timer for the next one yet */
1359    time_t    manualAnnounceTime;
1360
1361    /** A very rough estimate in KiB/s of how quickly data is being
1362        passed around between all the peers we're connected to.
1363        Don't put too much weight in this number. */
1364    float    swarmSpeed;
1365
1366#define TR_RATIO_NA  -1
1367#define TR_RATIO_INF -2
1368    /** TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
1369    float    ratio;
1370
1371    /** When the torrent was first added. */
1372    time_t    addedDate;
1373
1374    /** When the torrent finished downloading. */
1375    time_t    doneDate;
1376
1377    /** When the torrent was last started. */
1378    time_t    startDate;
1379
1380    /** The last time we uploaded or downloaded piece data on this torrent. */
1381    time_t    activityDate;
1382}
1383tr_stat;
1384
1385/** Return a pointer to an tr_stat structure with updated information
1386    on the torrent.  This is typically called by the GUI clients every
1387    second or so to get a new snapshot of the torrent's status. */
1388const tr_stat * tr_torrentStat( tr_torrent * torrent );
1389
1390/** Like tr_torrentStat(), but only recalculates the statistics if it's
1391    been longer than a second since they were last calculated.  This can
1392    reduce the CPU load if you're calling tr_torrentStat() frequently. */
1393const tr_stat * tr_torrentStatCached( tr_torrent * torrent );
1394
1395/** @deprecated this method will be removed in 1.40 */
1396void tr_torrentSetAddedDate( tr_torrent * torrent,
1397                             time_t       addedDate );
1398
1399/** @deprecated this method will be removed in 1.40 */
1400void tr_torrentSetActivityDate( tr_torrent * torrent,
1401                                time_t       activityDate );
1402
1403/** @deprecated this method will be removed in 1.40 */
1404void tr_torrentSetDoneDate( tr_torrent  * torrent,
1405                            time_t        doneDate );
1406
1407/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
1408tr_bool tr_isDirection( tr_direction );
1409
1410/** @} */
1411
1412#ifdef __TRANSMISSION__
1413 #include "session.h"
1414#endif
1415
1416#ifdef __cplusplus
1417}
1418#endif
1419
1420#endif
Note: See TracBrowser for help on using the repository browser.