source: trunk/libtransmission/transmission.h @ 5908

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

(libt) more janitorial work on cleaning up tr_session*() and tr_torrent*() functions: session stats, torrent count, and manual update.

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