source: trunk/libtransmission/transmission.h @ 6920

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

make MAX_PATH_LENGTH private to libtransmission. add tr_dirname() and tr_basename() utility / portability wrappers

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