source: trunk/libtransmission/transmission.h @ 6795

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

run libT, cli, daemon, gtk through the source-code formatter "uncrustify" as promised/threatened

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