source: trunk/libtransmission/transmission.h @ 5329

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

fix bug that caused very large torrents to crash Transmission

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