source: trunk/libtransmission/transmission.h @ 5868

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

(#954) rpc: add "torrent-remove" method. rename tr_torrentDelete() as tr_torrentRemove() for consistency with various parts of the code.

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