source: trunk/libtransmission/transmission.h @ 6798

Last change on this file since 6798 was 6798, checked in by charles, 14 years ago

rpc-server cleanups. add true wildmat control. break the Mac build a little harder.

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