source: trunk/libtransmission/transmission.h @ 6556

Last change on this file since 6556 was 6556, checked in by charles, 13 years ago

#220: lazy bitfields

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