source: trunk/libtransmission/transmission.h @ 5843

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

RPC/IPC redesign

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