source: trunk/libtransmission/transmission.h @ 7370

Last change on this file since 7370 was 7370, checked in by livings124, 12 years ago

#1559 Simplify tr_sessionInitFull - Mac client

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