source: trunk/libtransmission/transmission.h @ 5286

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

add a tr_errno specifically for failed checksums so they can be differentiated from "Generic error"

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