source: branches/1.4x/libtransmission/transmission.h @ 7455

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

(1.4x libT) backport handshake, peer, bandwidth, peer-io to 1.4x.

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