source: trunk/libtransmission/transmission.h @ 5932

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

(libT) (1) shave a few bytes from tr_peer and tr_ratecontrol's footprints. (2) remove some dead code.

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