source: trunk/libtransmission/transmission.h @ 6496

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

readability improvments #1, #2, #3, #4. (muks)

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