source: trunk/libtransmission/transmission.h @ 5600

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

#848: UPnP users always have to wait for NAT-PMP to fail first

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