source: trunk/libtransmission/transmission.h @ 7574

Last change on this file since 7574 was 7574, checked in by charles, 12 years ago

(trunk libT) make tr_isAddress() and tr_isDirection() inline

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