source: trunk/libtransmission/transmission.h @ 7331

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

(daemon) #1510: kysucix's patch to give an option to delete local data via RPC when removing a torrent.

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