source: trunk/libtransmission/transmission.h @ 5585

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

tidy up some libtransmission filenames.

  • Property svn:keywords set to Date Rev Author Id
File size: 29.8 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 5585 2008-04-11 17:01:13Z 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
51#define TR_DEFAULT_PORT   51413
52
53typedef uint32_t tr_file_index_t;
54typedef uint32_t tr_piece_index_t;
55typedef uint64_t tr_block_index_t;
56
57enum
58{
59    TR_PEER_FROM_INCOMING  = 0,  /* connections made to the listening port */
60    TR_PEER_FROM_TRACKER   = 1,  /* peers received from a tracker */
61    TR_PEER_FROM_CACHE     = 2,  /* peers read from the peer cache */
62    TR_PEER_FROM_PEX       = 3,  /* peers discovered via PEX */
63    TR_PEER_FROM__MAX
64};
65
66/***********************************************************************
67 * tr_init
68 ***********************************************************************
69 * Initializes and returns an opaque libtransmission handle
70 * to be passed to functions below. The tag argument is a short string
71 * unique to the program invoking tr_init(), it is currently used as
72 * part of saved torrent files' names to prevent one frontend from
73 * deleting a torrent used by another. The following tags are used:
74 *   beos cli daemon gtk macosx wx
75 **********************************************************************/
76
77typedef struct tr_handle tr_handle;
78
79const char* tr_getDefaultConfigDir( void );
80
81tr_handle * tr_initFull( const char * configDir,
82                         const char * tag,
83                         int          isPexEnabled,
84                         int          isNatEnabled,
85                         int          publicPort,
86                         int          encryptionMode,
87                         int          isUploadLimitEnabled,
88                         int          uploadLimit,
89                         int          isDownloadLimitEnabled,
90                         int          downloadLimit,
91                         int          globalPeerLimit,
92                         int          messageLevel,
93                         int          isMessageQueueingEnabled,
94                         int          isBlocklistEnabled );
95
96/**
97 * Like tr_initFull() but with default values supplied.
98 */ 
99tr_handle * tr_init( const char * configDir,
100                     const char * tag );
101
102/**
103 * Shut down a libtransmission instance created by tr_init*()
104 */
105void tr_close( tr_handle * );
106
107
108/**
109***
110**/
111
112typedef struct tr_session_stats
113{
114    uint64_t uploadedBytes;   /* total up */
115    uint64_t downloadedBytes; /* total down */
116    double ratio;             /* TR_RATIO_INF, TR_RATIO_NA, or total up/down */
117    uint64_t filesAdded;      /* number of files added */
118    uint64_t sessionCount;    /* program started N times */
119    uint64_t secondsActive;   /* how long Transmisson's been running */
120}
121tr_session_stats;
122
123/* stats from the current session. */
124void tr_getSessionStats( const tr_handle   * handle,
125                         tr_session_stats  * setme );
126
127/* stats from the current and past sessions. */
128void tr_getCumulativeSessionStats( const tr_handle   * handle,
129                                   tr_session_stats  * setme );
130
131
132/**
133***
134**/
135
136typedef enum
137{
138    TR_PLAINTEXT_PREFERRED,
139    TR_ENCRYPTION_PREFERRED,
140    TR_ENCRYPTION_REQUIRED
141}
142tr_encryption_mode;
143
144tr_encryption_mode tr_getEncryptionMode( tr_handle * handle );
145
146void tr_setEncryptionMode( tr_handle * handle, tr_encryption_mode mode );
147
148/***********************************************************************
149 * tr_getPrefsDirectory
150 ***********************************************************************
151 * Returns the full path to a directory which can be used to store
152 * preferences. The string belongs to libtransmission, do not free it.
153 **********************************************************************/
154const char * tr_getConfigDir( const tr_handle * );
155
156
157
158
159/***********************************************************************
160** Message Logging
161*/
162
163enum
164{
165    TR_MSG_ERR = 1,
166    TR_MSG_INF = 2,
167    TR_MSG_DBG = 3
168};
169void tr_setMessageLevel( int );
170int tr_getMessageLevel( void );
171
172typedef struct tr_msg_list
173{
174    /* TR_MSG_ERR, TR_MSG_INF, or TR_MSG_DBG */
175    uint8_t level;
176
177    /* Time the message was generated */
178    time_t when;
179
180    /* The torrent associated with this message,
181     * or a module name such as "Port Forwarding" for non-torrent messages,
182     * or NULL. */
183    char * name;
184
185    /* The message */
186    char * message;
187
188    /* The source file where this message originated */
189    const char * file;
190
191    /* The line number in the source file where this message originated */
192    int line;
193
194    /* linked list of messages */
195    struct tr_msg_list * next;
196}
197tr_msg_list;
198
199void tr_setMessageQueuing( int enable );
200
201tr_msg_list * tr_getQueuedMessages( void );
202void tr_freeMessageList( tr_msg_list * freeme );
203
204/***********************************************************************
205** Incoming Peer Connections Port
206*/
207
208void tr_setBindPort( tr_handle *, int );
209
210void tr_natTraversalEnable( tr_handle *, int enable );
211
212int tr_getPublicPort( const tr_handle * );
213
214typedef enum
215{
216    TR_NAT_TRAVERSAL_MAPPING,
217    TR_NAT_TRAVERSAL_MAPPED,
218    TR_NAT_TRAVERSAL_UNMAPPING,
219    TR_NAT_TRAVERSAL_UNMAPPED,
220    TR_NAT_TRAVERSAL_ERROR,
221}
222tr_nat_traversal_status;
223
224typedef struct tr_handle_status
225{
226    tr_nat_traversal_status natTraversalStatus;
227    int publicPort;
228}
229tr_handle_status;
230
231const tr_handle_status * tr_handleStatus( tr_handle * );
232
233
234/***********************************************************************
235***
236***  TORRENTS
237**/
238
239typedef struct tr_torrent tr_torrent;
240
241int tr_torrentCount( const tr_handle * h );
242
243/***********************************************************************
244*** Speed Limits
245**/
246
247enum { TR_UP, TR_DOWN };
248
249typedef enum
250{
251    TR_SPEEDLIMIT_GLOBAL,    /* only follow the overall speed limit */
252    TR_SPEEDLIMIT_SINGLE,    /* only follow the per-torrent limit */
253    TR_SPEEDLIMIT_UNLIMITED  /* no limits at all */
254}
255tr_speedlimit;
256
257void tr_torrentSetSpeedMode( tr_torrent   * tor,
258                             int            up_or_down,
259                             tr_speedlimit  mode );
260
261tr_speedlimit tr_torrentGetSpeedMode( const tr_torrent  * tor,
262                                      int                 up_or_down);
263
264void tr_torrentSetSpeedLimit( tr_torrent   * tor,
265                              int            up_or_down,
266                              int            single_KiB_sec );
267
268int tr_torrentGetSpeedLimit( const tr_torrent  * tor,
269                             int                 up_or_down );
270
271void tr_setUseGlobalSpeedLimit( tr_handle * handle,
272                                int           up_or_down,
273                                int           use_flag );
274
275void tr_setGlobalSpeedLimit( tr_handle * handle,
276                             int           up_or_down,
277                             int           global_KiB_sec );
278
279void tr_getGlobalSpeedLimit( tr_handle * handle,
280                             int           up_or_down,
281                             int         * setme_is_enabled,
282                             int         * setme_KiBsec );
283
284
285/***********************************************************************
286***  Peer Limits
287**/
288
289void tr_torrentSetMaxConnectedPeers( tr_torrent  * tor,
290                                     uint16_t      maxConnectedPeers);
291
292uint16_t tr_torrentGetMaxConnectedPeers( const tr_torrent  * tor );
293
294void tr_setGlobalPeerLimit( tr_handle * handle,
295                            uint16_t    maxGlobalPeers );
296
297uint16_t tr_getGlobalPeerLimit( const tr_handle * handle );
298
299
300/**
301 * Specify a range of IPs for Transmission to block.
302 *
303 * filename must be an uncompressed ascii file,
304 * using the same format as the bluetack level1 file.
305 *
306 * libtransmission does not keep a handle to `filename'
307 * after this call returns, so the caller is free to
308 * keep or delete `filename' as it wishes.
309 * libtransmission makes its own copy of the file
310 * massaged into a format easier to search.
311 *
312 * The caller only needs to invoke this when the blocklist
313 * has changed.
314 *
315 * Passing NULL for a filename will clear the blocklist.
316 */
317int tr_blocklistSetContent( tr_handle  * handle,
318                            const char * filename );
319
320int tr_blocklistGetRuleCount( tr_handle * handle );
321
322int tr_blocklistExists( const tr_handle * handle );
323
324int tr_blocklistIsEnabled( const tr_handle * handle );
325
326void tr_blocklistSetEnabled( tr_handle * handle,
327                             int         isEnabled );
328
329struct in_addr;
330
331int tr_blocklistHasAddress( tr_handle             * handle,
332                            const struct in_addr  * addr);
333
334
335/***********************************************************************
336 * Torrent Priorities
337 **********************************************************************/
338
339enum
340{
341    TR_PRI_LOW    = -1,
342    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
343    TR_PRI_HIGH   =  1
344};
345
346typedef int8_t tr_priority_t;
347
348/* set a batch of files to a particular priority.
349 * priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW */
350void tr_torrentSetFilePriorities( tr_torrent        * tor,
351                                  tr_file_index_t   * files,
352                                  tr_file_index_t     fileCount,
353                                  tr_priority_t       priority );
354
355/* returns a malloc()ed array of tor->info.fileCount items,
356 * each holding a value of TR_PRI_NORMAL, _HIGH, or _LOW.
357   free the array when done. */
358tr_priority_t* tr_torrentGetFilePriorities( const tr_torrent * );
359
360/* single-file form of tr_torrentGetFilePriorities.
361 * returns one of TR_PRI_NORMAL, _HIGH, or _LOW. */
362tr_priority_t tr_torrentGetFilePriority( const tr_torrent *, tr_file_index_t file );
363
364/* returns true if the file's `download' flag is set */
365int tr_torrentGetFileDL( const tr_torrent *, tr_file_index_t file );
366
367/* set a batch of files to be downloaded or not. */
368void tr_torrentSetFileDLs ( tr_torrent      * tor,
369                            tr_file_index_t * files,
370                            tr_file_index_t   fileCount,
371                            int               do_download );
372
373/***********************************************************************
374 * tr_torrentRates
375 ***********************************************************************
376 * Gets the total download and upload rates
377 **********************************************************************/
378void tr_torrentRates( tr_handle *, float *, float * );
379
380
381
382/**
383 *  Torrent Instantiation
384 *
385 *  Instantiating a tr_torrent had gotten more complicated as features were
386 *  added.  At one point there were four functions to check metainfo and five
387 *  to create tr_torrent.
388 *
389 *  To remedy this, a Torrent Constructor (struct tr_ctor) has been introduced:
390 *  + Simplifies the API down to two (non-deprecated) functions.
391 *  + You can set the fields you want; the system sets defaults for the rest.
392 *  + You can specify whether or not your fields should supercede fastresume's.
393 *  + We can add new features to tr_ctor without breaking tr_torrentNew()'s API.
394 *
395 *  All the tr_ctor{Get,Set}*() functions with a return value return
396 *  an error number, or zero if no error occurred.
397 *
398 *  You must call one of the SetMetainfo() functions before creating
399 *  a torrent with a tr_ctor.  The other functions are optional.
400 *
401 *  You can reuse a single tr_ctor to create a batch of torrents --
402 *  just call one of the SetMetainfo() functions between each
403 *  tr_torrentNew() call.
404 *
405 *  Every call to tr_ctorSetMetainfo*() frees the previous metainfo.
406 */
407
408typedef enum
409{
410    TR_FALLBACK, /* indicates the ctor value should be used only
411                    in case of missing fastresume settings */
412
413    TR_FORCE, /* indicates the ctor value should be used
414                 regardless of what's in the fastresume settings */
415}
416tr_ctorMode;
417
418typedef struct tr_ctor tr_ctor;
419struct tr_benc;
420
421tr_ctor* tr_ctorNew                    ( const tr_handle  * handle);
422
423void     tr_ctorFree                   ( tr_ctor        * ctor );
424
425void     tr_ctorSetSave                ( tr_ctor        * ctor,
426                                         int     saveMetadataInOurTorrentsDir );
427
428void     tr_ctorSetDeleteSource       ( tr_ctor        * ctor,
429                                         uint8_t          doDelete );
430
431int      tr_ctorSetMetainfo            ( tr_ctor        * ctor,
432                                         const uint8_t  * metainfo,
433                                         size_t           len );
434
435int      tr_ctorSetMetainfoFromFile    ( tr_ctor        * ctor,
436                                         const char     * filename );
437
438int      tr_ctorSetMetainfoFromHash    ( tr_ctor        * ctor,
439                                         const char     * hashString );
440
441void     tr_ctorSetMaxConnectedPeers   ( tr_ctor        * ctor,
442                                         tr_ctorMode      mode,
443                                         uint16_t         maxConnectedPeers );
444
445void     tr_ctorSetDestination         ( tr_ctor        * ctor,
446                                         tr_ctorMode      mode,
447                                         const char     * directory );
448
449void     tr_ctorSetPaused              ( tr_ctor        * ctor,
450                                         tr_ctorMode      mode,
451                                         uint8_t          isPaused );
452
453int      tr_ctorGetMaxConnectedPeers   ( const tr_ctor  * ctor,
454                                         tr_ctorMode      mode,
455                                         uint16_t       * setmeCount );
456
457int      tr_ctorGetPaused              ( const tr_ctor  * ctor,
458                                         tr_ctorMode      mode,
459                                         uint8_t        * setmeIsPaused );
460
461int      tr_ctorGetDestination         ( const tr_ctor  * ctor,
462                                         tr_ctorMode      mode,
463                                         const char    ** setmeDestination );
464
465int      tr_ctorGetMetainfo            ( const tr_ctor  * ctor,
466                                         const struct tr_benc ** setme );
467
468int      tr_ctorGetSave                ( const tr_ctor  * ctor );
469 
470int      tr_ctorGetDeleteSource        ( const tr_ctor  * ctor,
471                                         uint8_t        * setmeDoDelete );
472
473/* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
474const char* tr_ctorGetSourceFile       ( const tr_ctor  * ctor );
475
476
477typedef struct tr_info tr_info;
478
479/**
480 * Parses the specified metainfo.
481 * Returns TR_OK if it parsed and can be added to Transmission.
482 * Returns TR_EINVALID if it couldn't be parsed.
483 * Returns TR_EDUPLICATE if it parsed but can't be added.
484 *     "destination" must be set to test for TR_EDUPLICATE.
485 *
486 * If setme_info is non-NULL and parsing is successful
487 * (that is, if TR_EINVALID is not returned), then the parsed
488 * metainfo is stored in setme_info and should be freed by the
489 * caller via tr_metainfoFree().
490 */
491int tr_torrentParse( const tr_handle  * handle,
492                     const tr_ctor    * ctor,
493                     tr_info          * setme_info_or_NULL );
494
495/**
496 * Instantiate a single torrent.
497 */
498#define TR_EINVALID     1
499#define TR_EUNSUPPORTED 2
500#define TR_EDUPLICATE   3
501#define TR_EOTHER       666
502tr_torrent * tr_torrentNew( tr_handle      * handle,
503                            const tr_ctor  * ctor,
504                            int            * setmeError );
505
506
507/**
508 *  Load all the torrents in tr_getTorrentDir().
509 *  This can be used at startup to kickstart all the torrents
510 *  from the previous session.
511 */
512tr_torrent ** tr_loadTorrents ( tr_handle  * h,
513                                tr_ctor    * ctor,
514                                int        * setmeCount );
515
516
517
518/**
519 * Set whether or not torrents are allowed to do peer exchanges.
520 * PEX is always disabled in private torrents regardless of this.
521 * In public torrents, PEX is enabled by default.
522 */
523void tr_setPexEnabled( tr_handle *, int isEnabled );
524
525int tr_isPexEnabled( const tr_handle * );
526
527const tr_info * tr_torrentInfo( const tr_torrent * );
528
529void tr_torrentSetFolder( tr_torrent *, const char * );
530
531const char * tr_torrentGetFolder( const tr_torrent * );
532
533void tr_torrentStart( tr_torrent * );
534
535void tr_torrentStop( tr_torrent * );
536
537
538/**
539***
540**/
541
542typedef enum
543{
544    TR_CP_INCOMPLETE,   /* doesn't have all the desired pieces */
545    TR_CP_DONE,         /* has all the pieces but the DND ones */
546    TR_CP_COMPLETE      /* has every piece */
547}
548cp_status_t;
549
550typedef void (tr_torrent_status_func)(tr_torrent   * torrent,
551                                      cp_status_t    status,
552                                      void         * user_data );
553
554/**
555 * Register to be notified whenever a torrent's state changes.
556 *
557 * func is invoked FROM LIBTRANSMISSION'S THREAD!
558 * This means func must be fast (to avoid blocking peers),
559 * shouldn't call libtransmission functions (to avoid deadlock),
560 * and shouldn't modify client-level memory without using a mutex!
561 */
562void tr_torrentSetStatusCallback( tr_torrent             * torrent,
563                                  tr_torrent_status_func   func,
564                                  void                   * user_data );
565
566void tr_torrentClearStatusCallback( tr_torrent * torrent );
567
568
569
570/**
571***
572**/
573
574typedef void (tr_torrent_active_func)(tr_torrent   * torrent,
575                                      int            isRunning,
576                                      void         * user_data );
577
578/**
579 * Register to be notified whenever a torrent starts or stops.
580 *
581 * func is invoked FROM LIBTRANSMISSION'S THREAD!
582 * This means func must be fast (to avoid blocking peers),
583 * shouldn't call libtransmission functions (to avoid deadlock),
584 * and shouldn't modify client-level memory without using a mutex!
585 */
586void tr_torrentSetActiveCallback( tr_torrent             * torrent,
587                                  tr_torrent_active_func   func,
588                                  void                   * user_data );
589
590void tr_torrentClearActiveCallback( tr_torrent * torrent );
591
592
593/**
594 * MANUAL ANNOUNCE
595 *
596 * Trackers usually set an announce interval of 15 or 30 minutes.
597 * Users can send one-time announce requests that override this
598 * interval by calling tr_manualUpdate().
599 *
600 * The wait interval for tr_manualUpdate() is much smaller.
601 * You can test whether or not a manual update is possible
602 * (for example, to desensitize the button) by calling
603 * tr_torrentCanManualUpdate().
604 */
605
606void tr_manualUpdate( tr_torrent * );
607
608int tr_torrentCanManualUpdate( const tr_torrent * );
609
610/***********************************************************************
611 * tr_torrentStat
612 ***********************************************************************
613 * Returns a pointer to an tr_stat structure with updated information
614 * on the torrent. The structure belongs to libtransmission (do not
615 * free it) and is guaranteed to be unchanged until the next call to
616 * tr_torrentStat.
617 * The interface should call this function every second or so in order
618 * to update itself.
619 **********************************************************************/
620typedef struct tr_stat tr_stat;
621const tr_stat * tr_torrentStat( tr_torrent * );
622const tr_stat * tr_torrentStatCached( tr_torrent * );
623
624/***********************************************************************
625 * tr_torrentPeers
626 ***********************************************************************/
627typedef struct tr_peer_stat tr_peer_stat;
628tr_peer_stat * tr_torrentPeers( const tr_torrent *, int * peerCount );
629void tr_torrentPeersFree( tr_peer_stat *, int peerCount );
630
631typedef struct tr_file_stat tr_file_stat;
632tr_file_stat * tr_torrentFiles( const tr_torrent *, tr_file_index_t * fileCount );
633void tr_torrentFilesFree( tr_file_stat *, tr_file_index_t fileCount );
634
635
636/***********************************************************************
637 * tr_torrentAvailability
638 ***********************************************************************
639 * Use this to draw an advanced progress bar which is 'size' pixels
640 * wide. Fills 'tab' which you must have allocated: each byte is set
641 * to either -1 if we have the piece, otherwise it is set to the number
642 * of connected peers who have the piece.
643 **********************************************************************/
644void tr_torrentAvailability( const tr_torrent *, int8_t * tab, int size );
645
646void tr_torrentAmountFinished( const tr_torrent * tor, float * tab, int size );
647
648/***********************************************************************
649 * tr_torrentRemoveSaved
650 ***********************************************************************
651 * delete's Transmission's copy of the torrent's metadata from
652 * tr_getTorrentDir().
653 **********************************************************************/
654void tr_torrentRemoveSaved( tr_torrent * );
655
656void tr_torrentVerify( tr_torrent * );
657
658/**
659 * Frees memory allocated by tr_torrentNew().
660 * Running torrents are stopped first.
661 */
662void tr_torrentClose( tr_torrent * );
663
664/**
665 * Like tr_torrentClose() but also deletes
666 * the fastresume file and our copy of the
667 * torrent file
668 */
669void tr_torrentDelete( tr_torrent * );
670
671/***********************************************************************
672 * tr_info
673 **********************************************************************/
674
675typedef struct tr_file
676{
677    uint64_t          length;      /* Length of the file, in bytes */
678    char            * name;        /* Path to the file */
679    int8_t            priority;    /* TR_PRI_HIGH, _NORMAL, or _LOW */
680    int8_t            dnd;         /* nonzero if the file shouldn't be downloaded */
681    tr_piece_index_t  firstPiece;  /* We need pieces [firstPiece... */
682    tr_piece_index_t  lastPiece;   /* ...lastPiece] to dl this file */
683    uint64_t          offset;      /* file begins at the torrent's nth byte */
684}
685tr_file;
686
687typedef struct tr_piece
688{
689    uint8_t  hash[SHA_DIGEST_LENGTH];  /* pieces hash */
690    int8_t   priority;                 /* TR_PRI_HIGH, _NORMAL, or _LOW */
691    int8_t   dnd;                      /* nonzero if the piece shouldn't be downloaded */
692}
693tr_piece;
694   
695typedef struct tr_tracker_info
696{
697    char * address;
698    int    port;
699    char * announce;
700    char * scrape;
701}
702tr_tracker_info;
703
704struct tr_info
705{
706    /* Path to torrent */
707    char               * torrent;
708
709    /* General info */
710    uint8_t              hash[SHA_DIGEST_LENGTH];
711    char                 hashString[2*SHA_DIGEST_LENGTH+1];
712    char               * name;
713
714    /* Flags */
715    unsigned int isPrivate : 1;
716    unsigned int isMultifile : 1;
717
718    /* Tracker info */
719    struct
720    {
721        tr_tracker_info  * list;
722        int                 count;
723    }                  * trackerList;
724    int                  trackerTiers;
725    char               * primaryAddress;
726
727    /* Torrent info */
728    char               * comment;
729    char               * creator;
730    time_t               dateCreated;
731
732    /* Pieces info */
733    uint32_t             pieceSize;
734    tr_piece_index_t     pieceCount;
735    uint64_t             totalSize;
736    tr_piece           * pieces;
737
738    /* Files info */
739    tr_file_index_t      fileCount;
740    tr_file            * files;
741};
742
743typedef enum
744{
745    TR_STATUS_CHECK_WAIT   = (1<<0), /* Waiting in queue to check files */
746    TR_STATUS_CHECK        = (1<<1), /* Checking files */
747    TR_STATUS_DOWNLOAD     = (1<<2), /* Downloading */
748    TR_STATUS_SEED         = (1<<3), /* Seeding */
749    TR_STATUS_STOPPED      = (1<<4)  /* Torrent is stopped */
750}
751tr_torrent_status;
752
753#define TR_STATUS_IS_ACTIVE(s) ((s) != TR_STATUS_STOPPED)
754
755/**
756 * Transmission error codes
757 * errors are always negative, and 0 refers to no error.
758 */
759typedef enum tr_errno
760{
761    TR_OK = 0,
762
763    /* general errors */
764    TR_ERROR = -100,
765    TR_ERROR_ASSERT,
766
767    /* io errors */
768    TR_ERROR_IO_PARENT = -200,
769    TR_ERROR_IO_PERMISSIONS,
770    TR_ERROR_IO_SPACE,
771    TR_ERROR_IO_FILE_TOO_BIG,
772    TR_ERROR_IO_OPEN_FILES,
773    TR_ERROR_IO_DUP_DOWNLOAD,
774    TR_ERROR_IO_CHECKSUM,
775    TR_ERROR_IO_OTHER,
776
777    /* tracker errors */
778    TR_ERROR_TC_ERROR = -300,
779    TR_ERROR_TC_WARNING,
780
781    /* peer errors */
782    TR_ERROR_PEER_MESSAGE = -400
783}
784tr_errno;
785
786#define TR_ERROR_IS_IO(e) (TR_ERROR_IO_PARENT<=(e) && (e)<=TR_ERROR_IO_OTHER)
787#define TR_ERROR_IS_TC(e) (TR_ERROR_TC_ERROR<=(e) && (e)<=TR_ERROR_TC_WARNING)
788
789struct tr_tracker_stat
790{
791    /* This is the unmodified string returned by the tracker in response
792     * to the torrent's most recent scrape request.  If no request was
793     * sent or there was no response, this string is empty. */
794    char scrapeResponse[256];
795
796    /* The unmodified string returned by the tracker in response
797     * to the torrent's most recent scrape request.  If no request was
798     * sent or there was no response, this string is empty. */
799    char announceResponse[256];
800
801    /* Time the most recent scrape request was sent,
802     * or zero if one hasn't been sent yet. */
803    time_t lastScrapeTime;
804
805    /* Time when the next scrape request will be sent.
806     * This value is always a valid time. */
807    time_t nextScrapeTime;
808
809    /* Time the most recent announce request was sent,
810     * or zero if one hasn't been sent yet. */
811    time_t lastAnnounceTime;
812
813    /* Time when the next reannounce request will be sent,
814     * or zero if the torrent is stopped. */
815    time_t nextAnnounceTime;
816
817    /* When the tracker will allow a human-driven "manual" announce to be sent,
818     * derived from the "min interval" field given by the tracker.
819     * This value is 0 when the torrent is stopped.
820     * This value is ~(time_t)0 if the tracker returned a serious error.
821     * Otherwise, the value is a valid time.
822     * @see tr_manualUpdate( tr_torrent * );
823     * @see tr_torrentCanManualUpdate( const tr_torrent * ); */
824    time_t nextManualAnnounceTime;
825};
826
827tr_torrent_status tr_torrentGetStatus( tr_torrent * );
828
829struct tr_stat
830{
831    tr_torrent_status status;
832
833    struct tr_tracker_stat tracker_stat;
834    const tr_tracker_info * tracker;
835
836    tr_errno error;
837    char errorString[128];
838
839    /* [0..1] */
840    float recheckProgress;
841
842    /* [0..1] */
843    float percentComplete;
844
845    /* [0..1] */
846    float percentDone;
847
848    /* KiB/s */
849    float rateDownload;
850
851    /* KiB/s */
852    float rateUpload;
853
854 #define TR_ETA_NOT_AVAIL -1
855 #define TR_ETA_UNKNOWN -2
856    /* seconds */
857    int eta;
858
859    int peersKnown;
860    int peersConnected;
861    int peersFrom[TR_PEER_FROM__MAX];
862    int peersSendingToUs;
863    int peersGettingFromUs;
864    int seeders;
865    int leechers;
866    int completedFromTracker;
867
868    /* if the torrent is running, this is the time at which
869     * the client can manually ask the torrent's tracker
870     * for more peers.  otherwise, the value is zero. */
871    time_t manualAnnounceTime;
872
873    /* Byte count of how much data is left to be downloaded until
874     * we're done -- that is, until we've got all the pieces we wanted. */
875    uint64_t leftUntilDone;
876
877    /* Byte count of all the corrupt data you've ever downloaded for
878     * this torrent.  If you're on a poisoned torrent, this number can
879     * grow very large. */
880    uint64_t corruptEver;
881
882    /* Byte count of all data you've ever uploaded for this torrent. */
883    uint64_t uploadedEver;
884
885    /* Byte count of all the non-corrupt data you've ever downloaded
886     * for this torrent.  If you deleted the files and downloaded a second time,
887     * this will be 2*totalSize.. */
888    uint64_t downloadedEver;
889
890    /* Byte count of all the checksum-verified data we have for this torrent. */
891    uint64_t haveValid;
892
893    /* Byte count of all the partial piece data we have for this torrent.
894     * As pieces become complete, this value may decrease as portions of it are
895     * moved to `corrupt' or `haveValid'. */
896    uint64_t haveUnchecked;
897
898    /* Byte count of all the non-DND piece data that either we already have,
899     * or that a peer we're connected to has. [0...desiredSize] */
900    uint64_t desiredAvailable;
901
902    /* Byte count of all the piece data we want, whether we currently
903     * have it nor not. [0...tr_info.totalSize] */
904    uint64_t desiredSize;
905
906    float swarmspeed;
907
908#define TR_RATIO_NA  -1
909#define TR_RATIO_INF -2
910    /* TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
911    float ratio;
912   
913    uint64_t startDate;
914    uint64_t activityDate;
915};
916
917struct tr_file_stat
918{
919    uint64_t bytesCompleted;
920    float progress;
921};
922
923struct tr_peer_stat
924{
925    char addr[16];
926    char client[80];
927   
928    unsigned int isEncrypted : 1;
929    unsigned int isDownloadingFrom : 1;
930    unsigned int isUploadingTo : 1;
931
932    unsigned int peerIsChoked : 1;
933    unsigned int peerIsInterested : 1;
934    unsigned int clientIsChoked : 1;
935    unsigned int clientIsInterested : 1;
936    unsigned int isIncoming : 1;
937
938    char flagStr[32];
939
940    uint8_t  from;
941    uint16_t port;
942   
943    float progress;
944    float downloadFromRate;
945    float uploadToRate;
946};
947
948
949#ifdef __TRANSMISSION__
950#  include "session.h"
951#endif
952
953#ifdef __cplusplus
954}
955#endif
956
957#endif
Note: See TracBrowser for help on using the repository browser.