source: trunk/libtransmission/transmission.h @ 5666

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

add statistics "reset" button

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