source: trunk/libtransmission/transmission.h @ 7646

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

(trunk libT) finally get around to making upload-slots-per-torrent a settings.json option, thanks to friendly prodding from ful in #transmission

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