source: trunk/libtransmission/transmission.h @ 5817

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

json ipc: implement torrent-add, torrent-set-file, torrent-get-file

  • Property svn:keywords set to Date Rev Author Id
File size: 30.2 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 5817 2008-05-12 13:05:06Z 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_EDUPLICATE   2
514tr_torrent * tr_torrentNew( tr_handle      * handle,
515                            const tr_ctor  * ctor,
516                            int            * setmeError );
517
518
519/**
520 *  Load all the torrents in tr_getTorrentDir().
521 *  This can be used at startup to kickstart all the torrents
522 *  from the previous session.
523 */
524tr_torrent ** tr_loadTorrents ( tr_handle  * h,
525                                tr_ctor    * ctor,
526                                int        * setmeCount );
527
528
529
530/**
531 * Set whether or not torrents are allowed to do peer exchanges.
532 * PEX is always disabled in private torrents regardless of this.
533 * In public torrents, PEX is enabled by default.
534 */
535void tr_setPexEnabled( tr_handle *, int isEnabled );
536
537int tr_isPexEnabled( const tr_handle * );
538
539const tr_info * tr_torrentInfo( const tr_torrent * );
540
541void tr_torrentSetFolder( tr_torrent *, const char * );
542
543const char * tr_torrentGetFolder( const tr_torrent * );
544
545void tr_torrentStart( tr_torrent * );
546
547void tr_torrentStop( tr_torrent * );
548
549
550/**
551***
552**/
553
554typedef enum
555{
556    TR_CP_INCOMPLETE,   /* doesn't have all the desired pieces */
557    TR_CP_DONE,         /* has all the pieces but the DND ones */
558    TR_CP_COMPLETE      /* has every piece */
559}
560cp_status_t;
561
562typedef void (tr_torrent_status_func)(tr_torrent   * torrent,
563                                      cp_status_t    status,
564                                      void         * user_data );
565
566/**
567 * Register to be notified whenever a torrent's state changes.
568 *
569 * func is invoked FROM LIBTRANSMISSION'S THREAD!
570 * This means func must be fast (to avoid blocking peers),
571 * shouldn't call libtransmission functions (to avoid deadlock),
572 * and shouldn't modify client-level memory without using a mutex!
573 */
574void tr_torrentSetStatusCallback( tr_torrent             * torrent,
575                                  tr_torrent_status_func   func,
576                                  void                   * user_data );
577
578void tr_torrentClearStatusCallback( tr_torrent * torrent );
579
580
581
582/**
583***
584**/
585
586typedef void (tr_torrent_active_func)(tr_torrent   * torrent,
587                                      int            isRunning,
588                                      void         * user_data );
589
590/**
591 * Register to be notified whenever a torrent starts or stops.
592 *
593 * func is invoked FROM LIBTRANSMISSION'S THREAD!
594 * This means func must be fast (to avoid blocking peers),
595 * shouldn't call libtransmission functions (to avoid deadlock),
596 * and shouldn't modify client-level memory without using a mutex!
597 */
598void tr_torrentSetActiveCallback( tr_torrent             * torrent,
599                                  tr_torrent_active_func   func,
600                                  void                   * user_data );
601
602void tr_torrentClearActiveCallback( tr_torrent * torrent );
603
604
605/**
606 * MANUAL ANNOUNCE
607 *
608 * Trackers usually set an announce interval of 15 or 30 minutes.
609 * Users can send one-time announce requests that override this
610 * interval by calling tr_manualUpdate().
611 *
612 * The wait interval for tr_manualUpdate() is much smaller.
613 * You can test whether or not a manual update is possible
614 * (for example, to desensitize the button) by calling
615 * tr_torrentCanManualUpdate().
616 */
617
618void tr_manualUpdate( tr_torrent * );
619
620int tr_torrentCanManualUpdate( const tr_torrent * );
621
622/***********************************************************************
623 * tr_torrentStat
624 ***********************************************************************
625 * Returns a pointer to an tr_stat structure with updated information
626 * on the torrent. The structure belongs to libtransmission (do not
627 * free it) and is guaranteed to be unchanged until the next call to
628 * tr_torrentStat.
629 * The interface should call this function every second or so in order
630 * to update itself.
631 **********************************************************************/
632typedef struct tr_stat tr_stat;
633const tr_stat * tr_torrentStat( tr_torrent * );
634const tr_stat * tr_torrentStatCached( tr_torrent * );
635
636/***********************************************************************
637 * tr_torrentPeers
638 ***********************************************************************/
639typedef struct tr_peer_stat tr_peer_stat;
640tr_peer_stat * tr_torrentPeers( const tr_torrent *, int * peerCount );
641void tr_torrentPeersFree( tr_peer_stat *, int peerCount );
642
643typedef struct tr_file_stat tr_file_stat;
644tr_file_stat * tr_torrentFiles( const tr_torrent *, tr_file_index_t * fileCount );
645void tr_torrentFilesFree( tr_file_stat *, tr_file_index_t fileCount );
646
647
648/***********************************************************************
649 * tr_torrentAvailability
650 ***********************************************************************
651 * Use this to draw an advanced progress bar which is 'size' pixels
652 * wide. Fills 'tab' which you must have allocated: each byte is set
653 * to either -1 if we have the piece, otherwise it is set to the number
654 * of connected peers who have the piece.
655 **********************************************************************/
656void tr_torrentAvailability( const tr_torrent *, int8_t * tab, int size );
657
658void tr_torrentAmountFinished( const tr_torrent * tor, float * tab, int size );
659
660/***********************************************************************
661 * tr_torrentRemoveSaved
662 ***********************************************************************
663 * delete's Transmission's copy of the torrent's metadata from
664 * tr_getTorrentDir().
665 **********************************************************************/
666void tr_torrentRemoveSaved( tr_torrent * );
667
668void tr_torrentVerify( tr_torrent * );
669
670/**
671 * Frees memory allocated by tr_torrentNew().
672 * Running torrents are stopped first.
673 */
674void tr_torrentClose( tr_torrent * );
675
676/**
677 * Like tr_torrentClose() but also deletes
678 * the fastresume file and our copy of the
679 * torrent file
680 */
681void tr_torrentDelete( tr_torrent * );
682
683/***********************************************************************
684 * tr_info
685 **********************************************************************/
686
687typedef struct tr_file
688{
689    uint64_t          length;      /* Length of the file, in bytes */
690    char            * name;        /* Path to the file */
691    int8_t            priority;    /* TR_PRI_HIGH, _NORMAL, or _LOW */
692    int8_t            dnd;         /* nonzero if the file shouldn't be downloaded */
693    tr_piece_index_t  firstPiece;  /* We need pieces [firstPiece... */
694    tr_piece_index_t  lastPiece;   /* ...lastPiece] to dl this file */
695    uint64_t          offset;      /* file begins at the torrent's nth byte */
696}
697tr_file;
698
699typedef struct tr_piece
700{
701    uint8_t  hash[SHA_DIGEST_LENGTH];  /* pieces hash */
702    int8_t   priority;                 /* TR_PRI_HIGH, _NORMAL, or _LOW */
703    int8_t   dnd;                      /* nonzero if the piece shouldn't be downloaded */
704}
705tr_piece;
706   
707typedef struct tr_tracker_info
708{
709    int    tier;
710    char * announce;
711    char * scrape;
712}
713tr_tracker_info;
714
715struct tr_info
716{
717    /* Path to torrent */
718    char               * torrent;
719
720    /* General info */
721    uint8_t              hash[SHA_DIGEST_LENGTH];
722    char                 hashString[2*SHA_DIGEST_LENGTH+1];
723    char               * name;
724
725    /* Flags */
726    unsigned int isPrivate : 1;
727    unsigned int isMultifile : 1;
728
729    /* these trackers are sorted by tier */
730    tr_tracker_info    * trackers;
731    int                  trackerCount;
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.