source: trunk/libtransmission/transmission.h @ 6073

Last change on this file since 6073 was 6073, checked in by charles, 13 years ago

#800 initial support for GetRight?-style fetching of data through http and ftp servers specified in the .torrent's "url-list" tag

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