source: trunk/libtransmission/transmission.h @ 7195

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

(libT) patch from jhujhiti to add ipv6 support.

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