source: trunk/libtransmission/transmission.h @ 5994

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

#981: add tr_stat.dateAdded to libT; add "sort by age" to gtk+ client

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