source: trunk/libtransmission/transmission.h @ 7366

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

(trunk libT) #1593: Setting upload to 0 kills all download

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