source: trunk/libtransmission/transmission.h @ 7368

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

(trunk libT) semantic cleanup: int -> tr_bool

  • Property svn:keywords set to Date Rev Author Id
File size: 47.4 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 7368 2008-12-13 23:39:12Z 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_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 either tr_sessionInit()
95 * or tr_sessionInit().  libtransmission creates a thread for itself so that
96 * it can operate independently of the caller's event loop.  The session will
97 * continue 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_MSGQUEUE_ENABLED           "message-queue-enabled"
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", "mac", "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
542
543/**
544 *  Load all the torrents in tr_getTorrentDir().
545 *  This can be used at startup to kickstart all the torrents
546 *  from the previous session.
547 */
548tr_torrent ** tr_sessionLoadTorrents( tr_session  * session,
549                                      tr_ctor     * ctor,
550                                      int         * setmeCount );
551
552/** @} */
553
554/**
555***
556**/
557
558
559/***********************************************************************
560** Message Logging
561*/
562
563enum
564{
565    TR_MSG_ERR = 1,
566    TR_MSG_INF = 2,
567    TR_MSG_DBG = 3
568};
569void tr_setMessageLevel( int );
570
571int  tr_getMessageLevel( void );
572
573typedef struct tr_msg_list
574{
575    /* TR_MSG_ERR, TR_MSG_INF, or TR_MSG_DBG */
576    uint8_t level;
577
578    /* The line number in the source file where this message originated */
579    int line;
580
581    /* Time the message was generated */
582    time_t when;
583
584    /* The torrent associated with this message,
585     * or a module name such as "Port Forwarding" for non-torrent messages,
586     * or NULL. */
587    char *  name;
588
589    /* The message */
590    char *  message;
591
592    /* The source file where this message originated */
593    const char * file;
594
595    /* linked list of messages */
596    struct tr_msg_list * next;
597}
598tr_msg_list;
599
600void          tr_setMessageQueuing( tr_bool isEnabled );
601
602tr_bool       tr_getMessageQueuing( void );
603
604tr_msg_list * tr_getQueuedMessages( void );
605
606void          tr_freeMessageList( tr_msg_list * freeme );
607
608/** @addtogroup Blocklists
609    @{ */
610
611/**
612 * Specify a range of IPs for Transmission to block.
613 *
614 * filename must be an uncompressed ascii file,
615 * using the same format as the bluetack level1 file.
616 *
617 * libtransmission does not keep a handle to `filename'
618 * after this call returns, so the caller is free to
619 * keep or delete `filename' as it wishes.
620 * libtransmission makes its own copy of the file
621 * massaged into a format easier to search.
622 *
623 * The caller only needs to invoke this when the blocklist
624 * has changed.
625 *
626 * Passing NULL for a filename will clear the blocklist.
627 */
628int     tr_blocklistSetContent   ( tr_session       * session,
629                                   const char       * filename );
630
631int     tr_blocklistGetRuleCount ( const tr_session * session );
632
633tr_bool tr_blocklistExists       ( const tr_session * session );
634
635tr_bool tr_blocklistIsEnabled    ( const tr_session * session );
636
637void    tr_blocklistSetEnabled   ( tr_session       * session,
638                                   tr_bool            isEnabled );
639
640
641/** @} */
642
643
644/** @addtogroup tr_ctor Torrent Instantiation
645    @{
646
647    Instantiating a tr_torrent had gotten more complicated as features were
648    added.  At one point there were four functions to check metainfo and five
649    to create tr_torrent.
650
651    To remedy this, a Torrent Constructor (struct tr_ctor) has been introduced:
652    - Simplifies the API to two functions: tr_torrentParse() and tr_torrentNew()
653    - You can set the fields you want; the system sets defaults for the rest.
654    - You can specify whether or not your fields should supercede resume's.
655    - We can add new features to tr_ctor without breaking tr_torrentNew()'s API.
656
657    All the tr_ctor{Get,Set}*() functions with a return value return
658    an error number, or zero if no error occurred.
659
660    You must call one of the SetMetainfo() functions before creating
661    a torrent with a tr_ctor.  The other functions are optional.
662
663    You can reuse a single tr_ctor to create a batch of torrents --
664    just call one of the SetMetainfo() functions between each
665    tr_torrentNew() call.
666
667    Every call to tr_ctorSetMetainfo*() frees the previous metainfo.
668 */
669
670typedef enum
671{
672    TR_FALLBACK, /* indicates the ctor value should be used only
673                    in case of missing resume settings */
674
675    TR_FORCE, /* indicates the ctor value should be used
676                 regardless of what's in the resume settings */
677}
678tr_ctorMode;
679
680struct tr_benc;
681
682tr_ctor*    tr_ctorNew( const tr_session * session );
683
684void        tr_ctorFree( tr_ctor * ctor );
685
686void        tr_ctorSetDeleteSource( tr_ctor * ctor,
687                                    tr_bool   doDelete );
688
689int         tr_ctorSetMetainfo( tr_ctor *       ctor,
690                                const uint8_t * metainfo,
691                                size_t          len );
692
693int         tr_ctorSetMetainfoFromFile( tr_ctor *    ctor,
694                                        const char * filename );
695
696int         tr_ctorSetMetainfoFromHash( tr_ctor *    ctor,
697                                        const char * hashString );
698
699/** Set the maximum number of peers this torrent can connect to.
700    (Default: 50) */
701void        tr_ctorSetPeerLimit( tr_ctor *   ctor,
702                                 tr_ctorMode mode,
703                                 uint16_t    peerLimit  );
704
705/** Set the download folder for the torrent being added with this ctor.
706    @see tr_ctorSetDownloadDir()
707    @see tr_sessionInit() */
708void        tr_ctorSetDownloadDir( tr_ctor *    ctor,
709                                   tr_ctorMode  mode,
710                                   const char * directory );
711
712/** Set whether or not the torrent begins downloading/seeding when created.
713    (Default: not paused) */
714void        tr_ctorSetPaused( tr_ctor      * ctor,
715                              tr_ctorMode    mode,
716                              tr_bool        isPaused );
717
718int         tr_ctorGetPeerLimit( const tr_ctor * ctor,
719                                 tr_ctorMode     mode,
720                                 uint16_t *      setmeCount );
721
722int         tr_ctorGetPaused( const tr_ctor * ctor,
723                              tr_ctorMode     mode,
724                              tr_bool       * setmeIsPaused );
725
726int         tr_ctorGetDownloadDir( const tr_ctor  * ctor,
727                                   tr_ctorMode      mode,
728                                   const char    ** setmeDownloadDir );
729
730int         tr_ctorGetMetainfo( const tr_ctor         * ctor,
731                                const struct tr_benc ** setme );
732
733int         tr_ctorGetDeleteSource( const tr_ctor  * ctor,
734                                    tr_bool        * setmeDoDelete );
735
736/* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
737const char* tr_ctorGetSourceFile( const tr_ctor * ctor );
738
739#define TR_EINVALID     1
740#define TR_EDUPLICATE   2
741
742/**
743 * Parses the specified metainfo.
744 * Returns 0 if it parsed successfully and can be added to Transmission.
745 * Returns TR_EINVALID if it couldn't be parsed.
746 * Returns TR_EDUPLICATE if it parsed but can't be added.
747 *     "download-dir" must be set to test for TR_EDUPLICATE.
748 *
749 * If setme_info is non-NULL and parsing is successful
750 * (that is, if TR_EINVALID is not returned), then the parsed
751 * metainfo is stored in setme_info and should be freed by the
752 * caller via tr_metainfoFree().
753 */
754int tr_torrentParse( const tr_session  * session,
755                     const tr_ctor     * ctor,
756                     tr_info           * setme_info_or_NULL );
757
758/** @brief free a metainfo
759    @see tr_torrentParse */
760void tr_metainfoFree( tr_info * inf );
761
762
763/** Instantiate a single torrent.
764    @return 0 on success,
765            TR_EINVALID if the torrent couldn't be parsed, or
766            TR_EDUPLICATE if there's already a matching torrent object. */
767tr_torrent * tr_torrentNew( tr_session      * session,
768                            const tr_ctor   * ctor,
769                            int             * setmeError );
770
771/** @} */
772
773/***********************************************************************
774 ***
775 ***  TORRENTS
776 **/
777
778/** @addtogroup tr_torrent Torrents
779    @{ */
780
781/** @brief Frees memory allocated by tr_torrentNew().
782           Running torrents are stopped first.  */
783void tr_torrentFree( tr_torrent * torrent );
784
785/** @brief Removes our .torrent and .resume files for
786           this torrent, then calls tr_torrentFree(). */
787void tr_torrentRemove( tr_torrent * torrent );
788
789/** @brief Start a torrent */
790void tr_torrentStart( tr_torrent * torrent );
791
792/** @brief Stop (pause) a torrent */
793void tr_torrentStop( tr_torrent * torrent );
794
795/** @brief Deletes the torrent data stored on disk. */
796void tr_torrentDeleteLocalData( tr_torrent * torrent );
797
798/**
799 * @brief Iterate through the torrents.
800 *
801 * Pass in a NULL pointer to get the first torrent.
802 */
803tr_torrent* tr_torrentNext( tr_session  * session,
804                            tr_torrent  * current );
805
806
807uint64_t tr_torrentGetBytesLeftToAllocate( const tr_torrent * torrent );
808
809/**
810 * @brief Returns this torrent's unique ID.
811 *
812 * IDs are good as simple lookup keys, but are not persistent
813 * between sessions.  If you need that, use tr_info.hash or
814 * tr_info.hashString.
815 */
816int tr_torrentId( const tr_torrent * torrent );
817
818/****
819*****  Speed Limits
820****/
821
822typedef enum
823{
824    TR_SPEEDLIMIT_GLOBAL,    /* only follow the overall speed limit */
825    TR_SPEEDLIMIT_SINGLE,    /* only follow the per-torrent limit */
826    TR_SPEEDLIMIT_UNLIMITED  /* no limits at all */
827}
828tr_speedlimit;
829
830void          tr_torrentSetSpeedMode( tr_torrent     * tor,
831                                      tr_direction     up_or_down,
832                                      tr_speedlimit    mode );
833
834tr_speedlimit tr_torrentGetSpeedMode( const tr_torrent * tor,
835                                      tr_direction       direction );
836
837void          tr_torrentSetSpeedLimit( tr_torrent    * tor,
838                                       tr_direction    up_or_down,
839                                       int             KiB_sec );
840
841int           tr_torrentGetSpeedLimit( const tr_torrent  * tor,
842                                       tr_direction        direction );
843
844/****
845*****  Peer Limits
846****/
847
848void          tr_torrentSetPeerLimit( tr_torrent * tor,
849                                      uint16_t     peerLimit );
850
851uint16_t      tr_torrentGetPeerLimit( const tr_torrent * tor );
852
853/****
854*****  File Priorities
855****/
856
857enum
858{
859    TR_PRI_LOW    = -1,
860    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
861    TR_PRI_HIGH   =  1
862};
863
864typedef int8_t tr_priority_t;
865
866/**
867 * @brief Set a batch of files to a particular priority.
868 *
869 * @param priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW
870 */
871void tr_torrentSetFilePriorities( tr_torrent       * torrent,
872                                  tr_file_index_t  * files,
873                                  tr_file_index_t    fileCount,
874                                  tr_priority_t      priority );
875
876/**
877 * @brief Get this torrent's file priorities.
878 *
879 * @return A malloc()ed array of tor->info.fileCount items,
880 *         each holding a TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
881 *         It's the caller's responsibility to free() this.
882 */
883tr_priority_t*  tr_torrentGetFilePriorities( const tr_torrent * torrent );
884
885/**
886 * @brief Single-file form of tr_torrentGetFilePriorities.
887 * @return TR_PRI_NORMAL, TR_PRI_HIGH, or TR_PRI_LOW.
888 */
889tr_priority_t   tr_torrentGetFilePriority( const tr_torrent  * torrent,
890                                           tr_file_index_t     file );
891
892/**
893 * @brief See if a file's `download' flag is set.
894 * @return true if the file's `download' flag is set.
895 */
896int tr_torrentGetFileDL( const tr_torrent  * torrent,
897                         tr_file_index_t     file );
898
899/** @brief Set a batch of files to be downloaded or not. */
900void            tr_torrentSetFileDLs( tr_torrent       * torrent,
901                                      tr_file_index_t  * files,
902                                      tr_file_index_t    fileCount,
903                                      tr_bool            do_download );
904
905
906const tr_info * tr_torrentInfo( const tr_torrent * torrent );
907
908void tr_torrentSetDownloadDir( tr_torrent  * torrent,
909                               const char  * path );
910
911const char * tr_torrentGetDownloadDir( const tr_torrent * torrent );
912
913/**
914***
915**/
916
917typedef struct tr_tracker_info
918{
919    int     tier;
920    char *  announce;
921    char *  scrape;
922}
923tr_tracker_info;
924
925/**
926 * @brief Modify a torrent's tracker list.
927 *
928 * This updates both the `torrent' object's tracker list
929 * and the metainfo file in tr_sessionGetConfigDir()'s torrent subdirectory.
930 *
931 * @param torrent The torrent whose tracker list is to be modified
932 * @param trackers An array of trackers, sorted by tier from first to last.
933 *                 NOTE: only the `tier' and `announce' fields are used.
934 *                 libtransmission derives `scrape' from `announce'.
935 * @param trackerCount size of the `trackers' array
936 */
937void tr_torrentSetAnnounceList( tr_torrent *            torrent,
938                                const tr_tracker_info * trackers,
939                                int                     trackerCount );
940
941
942/**
943***
944**/
945
946typedef enum
947{
948    TR_LEECH,           /* doesn't have all the desired pieces */
949    TR_SEED,            /* has the entire torrent */
950    TR_PARTIAL_SEED     /* has the desired pieces, but not the entire torrent */
951}
952tr_completeness;
953
954typedef void ( tr_torrent_completeness_func )( tr_torrent       * torrent,
955                                               tr_completeness    completeness,
956                                               void             * user_data );
957
958/**
959 * Register to be notified whenever a torrent's "completeness"
960 * changes.  This will be called, for example, when a torrent
961 * finishes downloading and changes from TR_LEECH to
962 * either TR_SEED or TR_PARTIAL_SEED.
963 *
964 * func is invoked FROM LIBTRANSMISSION'S THREAD!
965 * This means func must be fast (to avoid blocking peers),
966 * shouldn't call libtransmission functions (to avoid deadlock),
967 * and shouldn't modify client-level memory without using a mutex!
968 *
969 * @see tr_completeness
970 */
971void tr_torrentSetCompletenessCallback(
972         tr_torrent                    * torrent,
973         tr_torrent_completeness_func    func,
974         void                          * user_data );
975
976void tr_torrentClearCompletenessCallback( tr_torrent * torrent );
977
978
979/**
980 * MANUAL ANNOUNCE
981 *
982 * Trackers usually set an announce interval of 15 or 30 minutes.
983 * Users can send one-time announce requests that override this
984 * interval by calling tr_torrentManualUpdate().
985 *
986 * The wait interval for tr_torrentManualUpdate() is much smaller.
987 * You can test whether or not a manual update is possible
988 * (for example, to desensitize the button) by calling
989 * tr_torrentCanManualUpdate().
990 */
991
992void tr_torrentManualUpdate( tr_torrent * torrent );
993
994int  tr_torrentCanManualUpdate( const tr_torrent * torrent );
995
996/***********************************************************************
997* tr_torrentPeers
998***********************************************************************/
999
1000typedef struct tr_peer_stat
1001{
1002    tr_bool      isEncrypted;
1003    tr_bool      isDownloadingFrom;
1004    tr_bool      isUploadingTo;
1005    tr_bool      isSeed;
1006
1007    tr_bool      peerIsChoked;
1008    tr_bool      peerIsInterested;
1009    tr_bool      clientIsChoked;
1010    tr_bool      clientIsInterested;
1011    tr_bool      isIncoming;
1012
1013    uint8_t      from;
1014    tr_port      port;
1015
1016    char         addr[TR_INET6_ADDRSTRLEN];
1017    char         client[80];
1018    char         flagStr[32];
1019
1020    float        progress;
1021    float        rateToPeer;
1022    float        rateToClient;
1023}
1024tr_peer_stat;
1025
1026tr_peer_stat * tr_torrentPeers( const tr_torrent * torrent,
1027                                int *              peerCount );
1028
1029void           tr_torrentPeersFree( tr_peer_stat * peerStats,
1030                                    int            peerCount );
1031
1032/**
1033 * @brief get the download speeds for each of this torrent's webseed sources.
1034 *
1035 * @return an array of tor->info.webseedCount floats giving download speeds.
1036 *         Each speed in the array corresponds to the webseed at the same
1037 *         array index in tor->info.webseeds.
1038 *         To differentiate "idle" and "stalled" status, idle webseeds will
1039 *         return -1 instead of 0 KiB/s.
1040 *         NOTE: always free this array with tr_free() when you're done with it.
1041 */
1042float*         tr_torrentWebSpeeds( const tr_torrent * torrent );
1043
1044typedef struct tr_file_stat
1045{
1046    uint64_t    bytesCompleted;
1047    float       progress;
1048}
1049tr_file_stat;
1050
1051tr_file_stat * tr_torrentFiles( const tr_torrent  * torrent,
1052                                tr_file_index_t   * fileCount );
1053
1054void tr_torrentFilesFree( tr_file_stat     * files,
1055                          tr_file_index_t    fileCount );
1056
1057
1058/***********************************************************************
1059 * tr_torrentAvailability
1060 ***********************************************************************
1061 * Use this to draw an advanced progress bar which is 'size' pixels
1062 * wide. Fills 'tab' which you must have allocated: each byte is set
1063 * to either -1 if we have the piece, otherwise it is set to the number
1064 * of connected peers who have the piece.
1065 **********************************************************************/
1066void tr_torrentAvailability( const tr_torrent  * torrent,
1067                             int8_t            * tab,
1068                             int                  size );
1069
1070void tr_torrentAmountFinished( const tr_torrent  * torrent,
1071                               float *             tab,
1072                               int                 size );
1073
1074void tr_torrentVerify( tr_torrent * torrent );
1075
1076/***********************************************************************
1077 * tr_info
1078 **********************************************************************/
1079
1080typedef struct tr_file
1081{
1082    uint64_t            length;    /* Length of the file, in bytes */
1083    char *              name;      /* Path to the file */
1084    int8_t              priority;  /* TR_PRI_HIGH, _NORMAL, or _LOW */
1085    int8_t              dnd;       /* nonzero if the file shouldn't be
1086                                     downloaded */
1087    tr_piece_index_t    firstPiece; /* We need pieces [firstPiece... */
1088    tr_piece_index_t    lastPiece; /* ...lastPiece] to dl this file */
1089    uint64_t            offset;    /* file begins at the torrent's nth byte */
1090}
1091tr_file;
1092
1093typedef struct tr_piece
1094{
1095    uint8_t    hash[SHA_DIGEST_LENGTH]; /* pieces hash */
1096    int8_t     priority;               /* TR_PRI_HIGH, _NORMAL, or _LOW */
1097    int8_t     dnd;                    /* nonzero if the piece shouldn't be
1098                                         downloaded */
1099}
1100tr_piece;
1101
1102struct tr_info
1103{
1104    /* Flags */
1105    tr_bool            isPrivate;
1106    tr_bool            isMultifile;
1107
1108    /* General info */
1109    uint8_t            hash[SHA_DIGEST_LENGTH];
1110    char               hashString[2 * SHA_DIGEST_LENGTH + 1];
1111    char            *  name;
1112
1113    /* Path to torrent Transmission's internal copy of the .torrent file.
1114       This field exists for compatability reasons in the Mac OS X client
1115       and should not be used in new code. */
1116    char            *  torrent;
1117
1118    /* these trackers are sorted by tier */
1119    tr_tracker_info *  trackers;
1120    int                trackerCount;
1121
1122    char           **  webseeds;
1123    int                webseedCount;
1124
1125    /* Torrent info */
1126    char             * comment;
1127    char             * creator;
1128    time_t             dateCreated;
1129
1130    /* Pieces info */
1131    uint32_t           pieceSize;
1132    tr_piece_index_t   pieceCount;
1133    uint64_t           totalSize;
1134    tr_piece *         pieces;
1135
1136    /* Files info */
1137    tr_file_index_t    fileCount;
1138    tr_file *          files;
1139};
1140
1141/**
1142 * What the torrent is doing right now.
1143 *
1144 * Note: these values will become a straight enum at some point in the future.
1145 * Do not rely on their current `bitfield' implementation
1146 */
1147typedef enum
1148{
1149    TR_STATUS_CHECK_WAIT   = ( 1 << 0 ), /* Waiting in queue to check files */
1150    TR_STATUS_CHECK        = ( 1 << 1 ), /* Checking files */
1151    TR_STATUS_DOWNLOAD     = ( 1 << 2 ), /* Downloading */
1152    TR_STATUS_SEED         = ( 1 << 3 ), /* Seeding */
1153    TR_STATUS_STOPPED      = ( 1 << 4 )  /* Torrent is stopped */
1154}
1155tr_torrent_activity;
1156
1157tr_torrent_activity tr_torrentGetActivity( tr_torrent * );
1158
1159#define TR_STATUS_IS_ACTIVE( s ) ( ( s ) != TR_STATUS_STOPPED )
1160
1161typedef enum
1162{
1163    TR_LOCKFILE_SUCCESS = 0,
1164    TR_LOCKFILE_EOPEN,
1165    TR_LOCKFILE_ELOCK
1166}
1167tr_lockfile_state_t;
1168
1169enum
1170{
1171    TR_PEER_FROM_INCOMING  = 0,  /* connections made to the listening port */
1172    TR_PEER_FROM_TRACKER   = 1,  /* peers received from a tracker */
1173    TR_PEER_FROM_CACHE     = 2,  /* peers read from the peer cache */
1174    TR_PEER_FROM_PEX       = 3,  /* peers discovered via PEX */
1175    TR_PEER_FROM__MAX
1176};
1177
1178/** Can be used as a mnemonic for "no error" errno */
1179#define TR_OK 0
1180
1181/**
1182 * The current status of a torrent.
1183 * @see tr_torrentStat()
1184 */
1185typedef struct tr_stat
1186{
1187    /** The torrent's unique Id.
1188        @see tr_torrentId() */
1189    int    id;
1190
1191    /** What is this torrent doing right now? */
1192    tr_torrent_activity activity;
1193
1194    /** Our current announce URL, or NULL if none.
1195        This URL may change during the session if the torrent's
1196        metainfo has multiple trackers and the current one
1197        becomes unreachable. */
1198    char *  announceURL;
1199
1200    /** Our current scrape URL, or NULL if none.
1201        This URL may change during the session if the torrent's
1202        metainfo has multiple trackers and the current one
1203        becomes unreachable. */
1204    char *  scrapeURL;
1205
1206    /** The errno status for this torrent.  0 means everything's fine. */
1207    int     error;
1208
1209    /** Typically an error string returned from the tracker. */
1210    char    errorString[128];
1211
1212    /** When tr_stat.status is TR_STATUS_CHECK or TR_STATUS_CHECK_WAIT,
1213        this is the percentage of how much of the files has been
1214        verified.  When it gets to 1, the verify process is done.
1215        Range is [0..1]
1216        @see tr_stat.status */
1217    float    recheckProgress;
1218
1219    /** How much has been downloaded of the entire torrent.
1220        Range is [0..1] */
1221    float    percentComplete;
1222
1223    /** How much has been downloaded of the files the user wants.  This differs
1224        from percentComplete if the user wants only some of the torrent's files.
1225        Range is [0..1]
1226        @see tr_stat.leftUntilDone */
1227    float    percentDone;
1228
1229    /** Speed all data being sent for this torrent. (KiB/s)
1230        This includes piece data, protocol messages, and TCP overhead */
1231    double rawUploadSpeed;
1232
1233    /** Speed all data being received for this torrent. (KiB/s)
1234        This includes piece data, protocol messages, and TCP overhead */
1235    double rawDownloadSpeed;
1236
1237    /** Speed all piece being sent for this torrent. (KiB/s)
1238        This ONLY counts piece data. */
1239    double pieceUploadSpeed;
1240
1241    /** Speed all piece being received for this torrent. (KiB/s)
1242        This ONLY counts piece data. */
1243    double pieceDownloadSpeed;
1244
1245#define TR_ETA_NOT_AVAIL -1
1246#define TR_ETA_UNKNOWN -2
1247    /** Estimated number of seconds left until the torrent is done,
1248        or TR_ETA_NOT_AVAIL or TR_ETA_UNKNOWN */
1249    int    eta;
1250
1251    /** Number of peers that the tracker says this torrent has */
1252    int    peersKnown;
1253
1254    /** Number of peers that we're connected to */
1255    int    peersConnected;
1256
1257    /** How many peers we found out about from the tracker, or from pex,
1258        or from incoming connections, or from our resume file. */
1259    int    peersFrom[TR_PEER_FROM__MAX];
1260
1261    /** Number of peers that are sending data to us. */
1262    int    peersSendingToUs;
1263
1264    /** Number of peers that we're sending data to */
1265    int    peersGettingFromUs;
1266
1267    /** Number of webseeds that are sending data to us. */
1268    int    webseedsSendingToUs;
1269
1270    /** Number of seeders that the tracker says this torrent has */
1271    int    seeders;
1272
1273    /** Number of leechers that the tracker says this torrent has */
1274    int    leechers;
1275
1276    /** Number of downloaders that the tracker says this torrent has.
1277        This is a new key introduced in BEP 21 and may not be supported by some trackers.
1278        If the tracker doesn't support this key, the value here will be -1. */
1279    int    downloaders;
1280
1281    /** Number of finished downloads that the tracker says torrent has */
1282    int    timesCompleted;
1283
1284    /** Byte count of all the piece data we'll have downloaded when we're done,
1285        whether or not we have it yet.  This may be less than tr_info.totalSize
1286        if only some of the torrent's files are wanted.
1287        [0...tr_info.totalSize] */
1288    uint64_t    sizeWhenDone;
1289
1290    /** Byte count of how much data is left to be downloaded until we've got
1291        all the pieces that we want.  [0...tr_info.sizeWhenDone] */
1292    uint64_t    leftUntilDone;
1293
1294    /** Byte count of all the piece data we want and don't have yet,
1295        but that a connected peer does have. [0...leftUntilDone] */
1296    uint64_t    desiredAvailable;
1297
1298    /** Byte count of all the corrupt data you've ever downloaded for
1299        this torrent.  If you're on a poisoned torrent, this number can
1300        grow very large. */
1301    uint64_t    corruptEver;
1302
1303    /** Byte count of all data you've ever uploaded for this torrent. */
1304    uint64_t    uploadedEver;
1305
1306    /** Byte count of all the non-corrupt data you've ever downloaded
1307        for this torrent.  If you deleted the files and downloaded a second
1308        time, this will be 2*totalSize.. */
1309    uint64_t    downloadedEver;
1310
1311    /** Byte count of all the checksum-verified data we have for this torrent.
1312      */
1313    uint64_t    haveValid;
1314
1315    /** Byte count of all the partial piece data we have for this torrent.
1316        As pieces become complete, this value may decrease as portions of it
1317        are moved to `corrupt' or `haveValid'. */
1318    uint64_t    haveUnchecked;
1319
1320    /** This is the unmodified string returned by the tracker in response
1321        to the torrent's most recent scrape request.  If no request was
1322        sent or there was no response, this string is empty. */
1323    char    scrapeResponse[64];
1324
1325    /** The unmodified string returned by the tracker in response
1326        to the torrent's most recent scrape request.  If no request was
1327        sent or there was no response, this string is empty. */
1328    char    announceResponse[64];
1329
1330    /** Time the most recent scrape request was sent,
1331        or zero if one hasn't been sent yet. */
1332    time_t    lastScrapeTime;
1333
1334    /** Time when the next scrape request will be sent,
1335        or 0 if an error has occured that stops scraping,
1336        or 1 if a scrape is currently in progress s.t.
1337        we haven't set a timer for the next one yet. */
1338    time_t    nextScrapeTime;
1339
1340    /** Time the most recent announce request was sent,
1341        or zero if one hasn't been sent yet. */
1342    time_t    lastAnnounceTime;
1343
1344    /** Time when the next reannounce request will be sent,
1345        or 0 if the torrent is stopped,
1346        or 1 if an announce is currently in progress s.t.
1347        we haven't set a timer for the next one yet */
1348    time_t    nextAnnounceTime;
1349
1350    /** If the torrent is running, this is the time at which
1351        the client can manually ask the torrent's tracker
1352        for more peers,
1353        or 0 if the torrent is stopped or doesn't allow manual,
1354        or 1 if an announce is currently in progress s.t.
1355        we haven't set a timer for the next one yet */
1356    time_t    manualAnnounceTime;
1357
1358    /** A very rough estimate in KiB/s of how quickly data is being
1359        passed around between all the peers we're connected to.
1360        Don't put too much weight in this number. */
1361    float    swarmSpeed;
1362
1363#define TR_RATIO_NA  -1
1364#define TR_RATIO_INF -2
1365    /** TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
1366    float    ratio;
1367
1368    /** When the torrent was first added. */
1369    time_t    addedDate;
1370
1371    /** When the torrent finished downloading. */
1372    time_t    doneDate;
1373
1374    /** When the torrent was last started. */
1375    time_t    startDate;
1376
1377    /** The last time we uploaded or downloaded piece data on this torrent. */
1378    time_t    activityDate;
1379}
1380tr_stat;
1381
1382/** Return a pointer to an tr_stat structure with updated information
1383    on the torrent.  This is typically called by the GUI clients every
1384    second or so to get a new snapshot of the torrent's status. */
1385const tr_stat * tr_torrentStat( tr_torrent * torrent );
1386
1387/** Like tr_torrentStat(), but only recalculates the statistics if it's
1388    been longer than a second since they were last calculated.  This can
1389    reduce the CPU load if you're calling tr_torrentStat() frequently. */
1390const tr_stat * tr_torrentStatCached( tr_torrent * torrent );
1391
1392/** @deprecated this method will be removed in 1.40 */
1393void tr_torrentSetAddedDate( tr_torrent * torrent,
1394                             time_t       addedDate );
1395
1396/** @deprecated this method will be removed in 1.40 */
1397void tr_torrentSetActivityDate( tr_torrent * torrent,
1398                                time_t       activityDate );
1399
1400/** @deprecated this method will be removed in 1.40 */
1401void tr_torrentSetDoneDate( tr_torrent  * torrent,
1402                            time_t        doneDate );
1403
1404/** @} */
1405
1406#ifdef __TRANSMISSION__
1407 #include "session.h"
1408#endif
1409
1410#ifdef __cplusplus
1411}
1412#endif
1413
1414#endif
Note: See TracBrowser for help on using the repository browser.