source: trunk/libtransmission/transmission.h @ 5906

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

(rpc) remove TR_RPC_TORRENT_CLOSING. formalize "torrent-list"'s response in the rpc spec.

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