source: trunk/libtransmission/transmission.h @ 5457

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

remove `TR_STATUS_DONE' from libtransmission's public API. It's useful as an internal state but not for code calling libtransmission.

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