source: trunk/libtransmission/transmission.h @ 5796

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

new utility for iterating through torrents: tr_torrentNext()

  • Property svn:keywords set to Date Rev Author Id
File size: 30.3 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 5796 2008-05-10 00:19:00Z 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 * Iterate through the torrents.
253 * Pass in in a NULL pointer to get the first torrent.
254 */
255tr_torrent* tr_torrentNext( tr_handle *, tr_torrent * );
256
257/***********************************************************************
258*** Speed Limits
259**/
260
261enum { TR_UP, TR_DOWN };
262
263typedef enum
264{
265    TR_SPEEDLIMIT_GLOBAL,    /* only follow the overall speed limit */
266    TR_SPEEDLIMIT_SINGLE,    /* only follow the per-torrent limit */
267    TR_SPEEDLIMIT_UNLIMITED  /* no limits at all */
268}
269tr_speedlimit;
270
271void tr_torrentSetSpeedMode( tr_torrent   * tor,
272                             int            up_or_down,
273                             tr_speedlimit  mode );
274
275tr_speedlimit tr_torrentGetSpeedMode( const tr_torrent  * tor,
276                                      int                 up_or_down);
277
278void tr_torrentSetSpeedLimit( tr_torrent   * tor,
279                              int            up_or_down,
280                              int            single_KiB_sec );
281
282int tr_torrentGetSpeedLimit( const tr_torrent  * tor,
283                             int                 up_or_down );
284
285void tr_setUseGlobalSpeedLimit( tr_handle * handle,
286                                int           up_or_down,
287                                int           use_flag );
288
289void tr_setGlobalSpeedLimit( tr_handle * handle,
290                             int           up_or_down,
291                             int           global_KiB_sec );
292
293void tr_getGlobalSpeedLimit( tr_handle * handle,
294                             int           up_or_down,
295                             int         * setme_is_enabled,
296                             int         * setme_KiBsec );
297
298
299/***********************************************************************
300***  Peer Limits
301**/
302
303void tr_torrentSetMaxConnectedPeers( tr_torrent  * tor,
304                                     uint16_t      maxConnectedPeers);
305
306uint16_t tr_torrentGetMaxConnectedPeers( const tr_torrent  * tor );
307
308void tr_setGlobalPeerLimit( tr_handle * handle,
309                            uint16_t    maxGlobalPeers );
310
311uint16_t tr_getGlobalPeerLimit( const tr_handle * handle );
312
313
314/**
315 * Specify a range of IPs for Transmission to block.
316 *
317 * filename must be an uncompressed ascii file,
318 * using the same format as the bluetack level1 file.
319 *
320 * libtransmission does not keep a handle to `filename'
321 * after this call returns, so the caller is free to
322 * keep or delete `filename' as it wishes.
323 * libtransmission makes its own copy of the file
324 * massaged into a format easier to search.
325 *
326 * The caller only needs to invoke this when the blocklist
327 * has changed.
328 *
329 * Passing NULL for a filename will clear the blocklist.
330 */
331int tr_blocklistSetContent( tr_handle  * handle,
332                            const char * filename );
333
334int tr_blocklistGetRuleCount( tr_handle * handle );
335
336int tr_blocklistExists( const tr_handle * handle );
337
338int tr_blocklistIsEnabled( const tr_handle * handle );
339
340void tr_blocklistSetEnabled( tr_handle * handle,
341                             int         isEnabled );
342
343struct in_addr;
344
345int tr_blocklistHasAddress( tr_handle             * handle,
346                            const struct in_addr  * addr);
347
348
349/***********************************************************************
350 * Torrent Priorities
351 **********************************************************************/
352
353enum
354{
355    TR_PRI_LOW    = -1,
356    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
357    TR_PRI_HIGH   =  1
358};
359
360typedef int8_t tr_priority_t;
361
362/* set a batch of files to a particular priority.
363 * priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW */
364void tr_torrentSetFilePriorities( tr_torrent        * tor,
365                                  tr_file_index_t   * files,
366                                  tr_file_index_t     fileCount,
367                                  tr_priority_t       priority );
368
369/* returns a malloc()ed array of tor->info.fileCount items,
370 * each holding a value of TR_PRI_NORMAL, _HIGH, or _LOW.
371   free the array when done. */
372tr_priority_t* tr_torrentGetFilePriorities( const tr_torrent * );
373
374/* single-file form of tr_torrentGetFilePriorities.
375 * returns one of TR_PRI_NORMAL, _HIGH, or _LOW. */
376tr_priority_t tr_torrentGetFilePriority( const tr_torrent *, tr_file_index_t file );
377
378/* returns true if the file's `download' flag is set */
379int tr_torrentGetFileDL( const tr_torrent *, tr_file_index_t file );
380
381/* set a batch of files to be downloaded or not. */
382void tr_torrentSetFileDLs ( tr_torrent      * tor,
383                            tr_file_index_t * files,
384                            tr_file_index_t   fileCount,
385                            int               do_download );
386
387/***********************************************************************
388 * tr_torrentRates
389 ***********************************************************************
390 * Gets the total download and upload rates
391 **********************************************************************/
392void tr_torrentRates( tr_handle *, float *, float * );
393
394
395
396/**
397 *  Torrent Instantiation
398 *
399 *  Instantiating a tr_torrent had gotten more complicated as features were
400 *  added.  At one point there were four functions to check metainfo and five
401 *  to create tr_torrent.
402 *
403 *  To remedy this, a Torrent Constructor (struct tr_ctor) has been introduced:
404 *  + Simplifies the API down to two (non-deprecated) functions.
405 *  + You can set the fields you want; the system sets defaults for the rest.
406 *  + You can specify whether or not your fields should supercede fastresume's.
407 *  + We can add new features to tr_ctor without breaking tr_torrentNew()'s API.
408 *
409 *  All the tr_ctor{Get,Set}*() functions with a return value return
410 *  an error number, or zero if no error occurred.
411 *
412 *  You must call one of the SetMetainfo() functions before creating
413 *  a torrent with a tr_ctor.  The other functions are optional.
414 *
415 *  You can reuse a single tr_ctor to create a batch of torrents --
416 *  just call one of the SetMetainfo() functions between each
417 *  tr_torrentNew() call.
418 *
419 *  Every call to tr_ctorSetMetainfo*() frees the previous metainfo.
420 */
421
422typedef enum
423{
424    TR_FALLBACK, /* indicates the ctor value should be used only
425                    in case of missing fastresume settings */
426
427    TR_FORCE, /* indicates the ctor value should be used
428                 regardless of what's in the fastresume settings */
429}
430tr_ctorMode;
431
432typedef struct tr_ctor tr_ctor;
433struct tr_benc;
434
435tr_ctor* tr_ctorNew                    ( const tr_handle  * handle);
436
437void     tr_ctorFree                   ( tr_ctor        * ctor );
438
439void     tr_ctorSetSave                ( tr_ctor        * ctor,
440                                         int     saveMetadataInOurTorrentsDir );
441
442void     tr_ctorSetDeleteSource       ( tr_ctor        * ctor,
443                                         uint8_t          doDelete );
444
445int      tr_ctorSetMetainfo            ( tr_ctor        * ctor,
446                                         const uint8_t  * metainfo,
447                                         size_t           len );
448
449int      tr_ctorSetMetainfoFromFile    ( tr_ctor        * ctor,
450                                         const char     * filename );
451
452int      tr_ctorSetMetainfoFromHash    ( tr_ctor        * ctor,
453                                         const char     * hashString );
454
455void     tr_ctorSetMaxConnectedPeers   ( tr_ctor        * ctor,
456                                         tr_ctorMode      mode,
457                                         uint16_t         maxConnectedPeers );
458
459void     tr_ctorSetDestination         ( tr_ctor        * ctor,
460                                         tr_ctorMode      mode,
461                                         const char     * directory );
462
463void     tr_ctorSetPaused              ( tr_ctor        * ctor,
464                                         tr_ctorMode      mode,
465                                         uint8_t          isPaused );
466
467int      tr_ctorGetMaxConnectedPeers   ( const tr_ctor  * ctor,
468                                         tr_ctorMode      mode,
469                                         uint16_t       * setmeCount );
470
471int      tr_ctorGetPaused              ( const tr_ctor  * ctor,
472                                         tr_ctorMode      mode,
473                                         uint8_t        * setmeIsPaused );
474
475int      tr_ctorGetDestination         ( const tr_ctor  * ctor,
476                                         tr_ctorMode      mode,
477                                         const char    ** setmeDestination );
478
479int      tr_ctorGetMetainfo            ( const tr_ctor  * ctor,
480                                         const struct tr_benc ** setme );
481
482int      tr_ctorGetSave                ( const tr_ctor  * ctor );
483 
484int      tr_ctorGetDeleteSource        ( const tr_ctor  * ctor,
485                                         uint8_t        * setmeDoDelete );
486
487/* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
488const char* tr_ctorGetSourceFile       ( const tr_ctor  * ctor );
489
490
491typedef struct tr_info tr_info;
492
493/**
494 * Parses the specified metainfo.
495 * Returns TR_OK if it parsed and can be added to Transmission.
496 * Returns TR_EINVALID if it couldn't be parsed.
497 * Returns TR_EDUPLICATE if it parsed but can't be added.
498 *     "destination" must be set to test for TR_EDUPLICATE.
499 *
500 * If setme_info is non-NULL and parsing is successful
501 * (that is, if TR_EINVALID is not returned), then the parsed
502 * metainfo is stored in setme_info and should be freed by the
503 * caller via tr_metainfoFree().
504 */
505int tr_torrentParse( const tr_handle  * handle,
506                     const tr_ctor    * ctor,
507                     tr_info          * setme_info_or_NULL );
508
509/**
510 * Instantiate a single torrent.
511 */
512#define TR_EINVALID     1
513#define TR_EUNSUPPORTED 2
514#define TR_EDUPLICATE   3
515#define TR_EOTHER       666
516tr_torrent * tr_torrentNew( tr_handle      * handle,
517                            const tr_ctor  * ctor,
518                            int            * setmeError );
519
520
521/**
522 *  Load all the torrents in tr_getTorrentDir().
523 *  This can be used at startup to kickstart all the torrents
524 *  from the previous session.
525 */
526tr_torrent ** tr_loadTorrents ( tr_handle  * h,
527                                tr_ctor    * ctor,
528                                int        * setmeCount );
529
530
531
532/**
533 * Set whether or not torrents are allowed to do peer exchanges.
534 * PEX is always disabled in private torrents regardless of this.
535 * In public torrents, PEX is enabled by default.
536 */
537void tr_setPexEnabled( tr_handle *, int isEnabled );
538
539int tr_isPexEnabled( const tr_handle * );
540
541const tr_info * tr_torrentInfo( const tr_torrent * );
542
543void tr_torrentSetFolder( tr_torrent *, const char * );
544
545const char * tr_torrentGetFolder( const tr_torrent * );
546
547void tr_torrentStart( tr_torrent * );
548
549void tr_torrentStop( tr_torrent * );
550
551
552/**
553***
554**/
555
556typedef enum
557{
558    TR_CP_INCOMPLETE,   /* doesn't have all the desired pieces */
559    TR_CP_DONE,         /* has all the pieces but the DND ones */
560    TR_CP_COMPLETE      /* has every piece */
561}
562cp_status_t;
563
564typedef void (tr_torrent_status_func)(tr_torrent   * torrent,
565                                      cp_status_t    status,
566                                      void         * user_data );
567
568/**
569 * Register to be notified whenever a torrent's state changes.
570 *
571 * func is invoked FROM LIBTRANSMISSION'S THREAD!
572 * This means func must be fast (to avoid blocking peers),
573 * shouldn't call libtransmission functions (to avoid deadlock),
574 * and shouldn't modify client-level memory without using a mutex!
575 */
576void tr_torrentSetStatusCallback( tr_torrent             * torrent,
577                                  tr_torrent_status_func   func,
578                                  void                   * user_data );
579
580void tr_torrentClearStatusCallback( tr_torrent * torrent );
581
582
583
584/**
585***
586**/
587
588typedef void (tr_torrent_active_func)(tr_torrent   * torrent,
589                                      int            isRunning,
590                                      void         * user_data );
591
592/**
593 * Register to be notified whenever a torrent starts or stops.
594 *
595 * func is invoked FROM LIBTRANSMISSION'S THREAD!
596 * This means func must be fast (to avoid blocking peers),
597 * shouldn't call libtransmission functions (to avoid deadlock),
598 * and shouldn't modify client-level memory without using a mutex!
599 */
600void tr_torrentSetActiveCallback( tr_torrent             * torrent,
601                                  tr_torrent_active_func   func,
602                                  void                   * user_data );
603
604void tr_torrentClearActiveCallback( tr_torrent * torrent );
605
606
607/**
608 * MANUAL ANNOUNCE
609 *
610 * Trackers usually set an announce interval of 15 or 30 minutes.
611 * Users can send one-time announce requests that override this
612 * interval by calling tr_manualUpdate().
613 *
614 * The wait interval for tr_manualUpdate() is much smaller.
615 * You can test whether or not a manual update is possible
616 * (for example, to desensitize the button) by calling
617 * tr_torrentCanManualUpdate().
618 */
619
620void tr_manualUpdate( tr_torrent * );
621
622int tr_torrentCanManualUpdate( const tr_torrent * );
623
624/***********************************************************************
625 * tr_torrentStat
626 ***********************************************************************
627 * Returns a pointer to an tr_stat structure with updated information
628 * on the torrent. The structure belongs to libtransmission (do not
629 * free it) and is guaranteed to be unchanged until the next call to
630 * tr_torrentStat.
631 * The interface should call this function every second or so in order
632 * to update itself.
633 **********************************************************************/
634typedef struct tr_stat tr_stat;
635const tr_stat * tr_torrentStat( tr_torrent * );
636const tr_stat * tr_torrentStatCached( tr_torrent * );
637
638/***********************************************************************
639 * tr_torrentPeers
640 ***********************************************************************/
641typedef struct tr_peer_stat tr_peer_stat;
642tr_peer_stat * tr_torrentPeers( const tr_torrent *, int * peerCount );
643void tr_torrentPeersFree( tr_peer_stat *, int peerCount );
644
645typedef struct tr_file_stat tr_file_stat;
646tr_file_stat * tr_torrentFiles( const tr_torrent *, tr_file_index_t * fileCount );
647void tr_torrentFilesFree( tr_file_stat *, tr_file_index_t fileCount );
648
649
650/***********************************************************************
651 * tr_torrentAvailability
652 ***********************************************************************
653 * Use this to draw an advanced progress bar which is 'size' pixels
654 * wide. Fills 'tab' which you must have allocated: each byte is set
655 * to either -1 if we have the piece, otherwise it is set to the number
656 * of connected peers who have the piece.
657 **********************************************************************/
658void tr_torrentAvailability( const tr_torrent *, int8_t * tab, int size );
659
660void tr_torrentAmountFinished( const tr_torrent * tor, float * tab, int size );
661
662/***********************************************************************
663 * tr_torrentRemoveSaved
664 ***********************************************************************
665 * delete's Transmission's copy of the torrent's metadata from
666 * tr_getTorrentDir().
667 **********************************************************************/
668void tr_torrentRemoveSaved( tr_torrent * );
669
670void tr_torrentVerify( tr_torrent * );
671
672/**
673 * Frees memory allocated by tr_torrentNew().
674 * Running torrents are stopped first.
675 */
676void tr_torrentClose( tr_torrent * );
677
678/**
679 * Like tr_torrentClose() but also deletes
680 * the fastresume file and our copy of the
681 * torrent file
682 */
683void tr_torrentDelete( tr_torrent * );
684
685/***********************************************************************
686 * tr_info
687 **********************************************************************/
688
689typedef struct tr_file
690{
691    uint64_t          length;      /* Length of the file, in bytes */
692    char            * name;        /* Path to the file */
693    int8_t            priority;    /* TR_PRI_HIGH, _NORMAL, or _LOW */
694    int8_t            dnd;         /* nonzero if the file shouldn't be downloaded */
695    tr_piece_index_t  firstPiece;  /* We need pieces [firstPiece... */
696    tr_piece_index_t  lastPiece;   /* ...lastPiece] to dl this file */
697    uint64_t          offset;      /* file begins at the torrent's nth byte */
698}
699tr_file;
700
701typedef struct tr_piece
702{
703    uint8_t  hash[SHA_DIGEST_LENGTH];  /* pieces hash */
704    int8_t   priority;                 /* TR_PRI_HIGH, _NORMAL, or _LOW */
705    int8_t   dnd;                      /* nonzero if the piece shouldn't be downloaded */
706}
707tr_piece;
708   
709typedef struct tr_tracker_info
710{
711    int    tier;
712    char * announce;
713    char * scrape;
714}
715tr_tracker_info;
716
717struct tr_info
718{
719    /* Path to torrent */
720    char               * torrent;
721
722    /* General info */
723    uint8_t              hash[SHA_DIGEST_LENGTH];
724    char                 hashString[2*SHA_DIGEST_LENGTH+1];
725    char               * name;
726
727    /* Flags */
728    unsigned int isPrivate : 1;
729    unsigned int isMultifile : 1;
730
731    /* these trackers are sorted by tier */
732    tr_tracker_info    * trackers;
733    int                  trackerCount;
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.