source: trunk/libtransmission/transmission.h @ 7051

Last change on this file since 7051 was 7051, checked in by charles, 10 years ago

(libT) #849: preallocate files when possible to prevent disk fragmentation

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