source: trunk/libtransmission/transmission.h @ 6490

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

lots of C correctness tweaks suggested by sparse/cgcc

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