source: trunk/libtransmission/transmission.h @ 6049

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

get RPC password protections working in libT and the gtk+ client. mac, daemon, and cli need to be synced.

  • Property svn:keywords set to Date Rev Author Id
File size: 42.2 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 6049 2008-06-05 16:23:03Z 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    /* Torrent info */
1040    char               * comment;
1041    char               * creator;
1042    time_t               dateCreated;
1043
1044    /* Pieces info */
1045    uint32_t             pieceSize;
1046    tr_piece_index_t     pieceCount;
1047    uint64_t             totalSize;
1048    tr_piece           * pieces;
1049
1050    /* Files info */
1051    tr_file_index_t      fileCount;
1052    tr_file            * files;
1053};
1054
1055typedef enum
1056{
1057    TR_STATUS_CHECK_WAIT   = (1<<0), /* Waiting in queue to check files */
1058    TR_STATUS_CHECK        = (1<<1), /* Checking files */
1059    TR_STATUS_DOWNLOAD     = (1<<2), /* Downloading */
1060    TR_STATUS_SEED         = (1<<3), /* Seeding */
1061    TR_STATUS_STOPPED      = (1<<4)  /* Torrent is stopped */
1062}
1063tr_torrent_status;
1064
1065#define TR_STATUS_IS_ACTIVE(s) ((s) != TR_STATUS_STOPPED)
1066
1067/**
1068 * Transmission error codes
1069 * errors are always negative, and 0 refers to no error.
1070 */
1071typedef enum tr_errno
1072{
1073    TR_OK = 0,
1074
1075    /* general errors */
1076    TR_ERROR = -100,
1077    TR_ERROR_ASSERT,
1078
1079    /* io errors */
1080    TR_ERROR_IO_PARENT = -200,
1081    TR_ERROR_IO_PERMISSIONS,
1082    TR_ERROR_IO_SPACE,
1083    TR_ERROR_IO_FILE_TOO_BIG,
1084    TR_ERROR_IO_OPEN_FILES,
1085    TR_ERROR_IO_DUP_DOWNLOAD,
1086    TR_ERROR_IO_CHECKSUM,
1087    TR_ERROR_IO_OTHER,
1088
1089    /* tracker errors */
1090    TR_ERROR_TC_ERROR = -300,
1091    TR_ERROR_TC_WARNING,
1092
1093    /* peer errors */
1094    TR_ERROR_PEER_MESSAGE = -400
1095}
1096tr_errno;
1097
1098tr_torrent_status tr_torrentGetStatus( tr_torrent * );
1099
1100enum
1101{
1102    TR_PEER_FROM_INCOMING  = 0,  /* connections made to the listening port */
1103    TR_PEER_FROM_TRACKER   = 1,  /* peers received from a tracker */
1104    TR_PEER_FROM_CACHE     = 2,  /* peers read from the peer cache */
1105    TR_PEER_FROM_PEX       = 3,  /* peers discovered via PEX */
1106    TR_PEER_FROM__MAX
1107};
1108
1109/**
1110 * The current status of a torrent.
1111 * @see tr_torrentStat()
1112 */
1113typedef struct tr_stat
1114{
1115    /** The torrent's unique Id.
1116        @see tr_torrentId() */
1117    int id;
1118
1119    /** The torrent's current status */
1120    tr_torrent_status status;
1121
1122    /** Our current announce URL, or NULL if none.
1123        This URL may change during the session if the torrent's
1124        metainfo has multiple trackers and the current one
1125        becomes unreachable. */
1126    char * announceURL;
1127
1128    /** Our current scrape URL, or NULL if none.
1129        This URL may change during the session if the torrent's
1130        metainfo has multiple trackers and the current one
1131        becomes unreachable. */
1132    char * scrapeURL;
1133
1134    /** The error status for this torrent.  0 means everything's fine. */
1135    tr_errno error;
1136
1137    /** Typically an error string returned from the tracker. */
1138    char errorString[128];
1139
1140    /** When tr_stat.status is TR_STATUS_CHECK or TR_STATUS_CHECK_WAIT,
1141        this is the percentage of how much of the files has been
1142        verified.  When it gets to 1, the verify process is done.
1143        Range is [0..1]
1144        @see tr_stat.status */
1145    float recheckProgress;
1146
1147    /** How much has been downloaded of the entire torrent.
1148        Range is [0..1] */
1149    float percentComplete;
1150
1151    /** How much has been downloaded of the files the user wants.  This differs
1152        from percentComplete if the user wants only some of the torrent's files.
1153        Range is [0..1]
1154        @see tr_stat.leftUntilDone */
1155    float percentDone;
1156
1157    /** Download speed in KiB/s */
1158    float rateDownload;
1159
1160    /** Upload speed in KiB/s */
1161    float rateUpload;
1162
1163 #define TR_ETA_NOT_AVAIL -1
1164 #define TR_ETA_UNKNOWN -2
1165    /** Estimated number of seconds left until the torrent is done,
1166        or TR_ETA_NOT_AVAIL or TR_ETA_UNKNOWN */
1167    int eta;
1168
1169    /** Number of peers that the tracker says this torrent has */
1170    int peersKnown;
1171
1172    /** Number of peers that we're connected to */
1173    int peersConnected;
1174
1175    /** How many peers we found out about from the tracker, or from pex,
1176        or from incoming connections, or from our resume file. */
1177    int peersFrom[TR_PEER_FROM__MAX];
1178
1179    /** Number of peers that are sending data to us. */
1180    int peersSendingToUs;
1181
1182    /** Number of peers that we're sending data to */
1183    int peersGettingFromUs;
1184
1185    /** Number of seeders that the tracker says this torrent has */
1186    int seeders;
1187
1188    /** Number of leechers that the tracker says this torrent has */
1189    int leechers;
1190
1191    /** Number of finished downloads that the tracker says torrent has */
1192    int completedFromTracker;
1193
1194    /** Byte count of all the piece data we'll have downloaded when we're done,
1195        whether or not we have it yet. [0...tr_info.totalSize] */
1196    uint64_t sizeWhenDone;
1197
1198    /** Byte count of how much data is left to be downloaded until
1199        we're done -- that is, until we've got all the pieces we wanted.
1200        [0...tr_info.sizeWhenDone] */
1201    uint64_t leftUntilDone;
1202
1203    /** Byte count of all the piece data we want and don't have yet,
1204        but that a connected peer does have. [0...leftUntilDone] */
1205    uint64_t desiredAvailable;
1206
1207    /** Byte count of all the corrupt data you've ever downloaded for
1208        this torrent.  If you're on a poisoned torrent, this number can
1209        grow very large. */
1210    uint64_t corruptEver;
1211
1212    /** Byte count of all data you've ever uploaded for this torrent. */
1213    uint64_t uploadedEver;
1214
1215    /** Byte count of all the non-corrupt data you've ever downloaded
1216        for this torrent.  If you deleted the files and downloaded a second
1217        time, this will be 2*totalSize.. */
1218    uint64_t downloadedEver;
1219
1220    /** Byte count of all the checksum-verified data we have for this torrent. */
1221    uint64_t haveValid;
1222
1223    /** Byte count of all the partial piece data we have for this torrent.
1224        As pieces become complete, this value may decrease as portions of it
1225        are moved to `corrupt' or `haveValid'. */
1226    uint64_t haveUnchecked;
1227
1228    /** This is the unmodified string returned by the tracker in response
1229        to the torrent's most recent scrape request.  If no request was
1230        sent or there was no response, this string is empty. */
1231    char scrapeResponse[64];
1232
1233    /** The unmodified string returned by the tracker in response
1234        to the torrent's most recent scrape request.  If no request was
1235        sent or there was no response, this string is empty. */
1236    char announceResponse[64];
1237
1238    /** Time the most recent scrape request was sent,
1239        or zero if one hasn't been sent yet. */
1240    time_t lastScrapeTime;
1241
1242    /** Time when the next scrape request will be sent.
1243        This value is always a valid time. */
1244    time_t nextScrapeTime;
1245
1246    /** Time the most recent announce request was sent,
1247        or zero if one hasn't been sent yet. */
1248    time_t lastAnnounceTime;
1249
1250    /** Time when the next reannounce request will be sent,
1251        or zero if the torrent is stopped. */
1252    time_t nextAnnounceTime;
1253
1254    /** If the torrent is running, this is the time at which
1255        the client can manually ask the torrent's tracker
1256        for more peers.  otherwise, the value is zero. */
1257    time_t manualAnnounceTime;
1258
1259    /** A very rough estimate in KiB/s of how quickly data is being
1260        passed around between all the peers we're connected to.
1261        Don't put too much weight in this number. */
1262    float swarmSpeed;
1263
1264#define TR_RATIO_NA  -1
1265#define TR_RATIO_INF -2
1266    /** TR_RATIO_INF, TR_RATIO_NA, or a regular ratio */
1267    float ratio;
1268
1269    /** When the torrent was first added. */
1270    time_t addedDate;
1271
1272    /** When the torrent finished downloading. */
1273    time_t doneDate;
1274   
1275    /** When the torrent was last started. */ 
1276    time_t startDate;
1277
1278    /** The last time we uploaded or downloaded piece data on this torrent. */
1279    time_t activityDate;
1280}
1281tr_stat;
1282
1283/** Return a pointer to an tr_stat structure with updated information
1284    on the torrent.  This is typically called by the GUI clients every
1285    second or so to get a new snapshot of the torrent's status. */
1286const tr_stat * tr_torrentStat( tr_torrent * );
1287
1288/** Like tr_torrentStat(), but only recalculates the statistics if it's
1289    been longer than a second since they were last calculated.  This can
1290    reduce the CPU load if you're calling tr_torrentStat() frequently. */
1291const tr_stat * tr_torrentStatCached( tr_torrent * );
1292
1293/** @deprecated this method will be removed in 1.40 */
1294void tr_torrentSetAddedDate( tr_torrent *, time_t );
1295
1296/** @deprecated this method will be removed in 1.40 */
1297void tr_torrentSetActivityDate( tr_torrent *, time_t );
1298
1299/** @deprecated this method will be removed in 1.40 */
1300void tr_torrentSetDoneDate( tr_torrent *, time_t );
1301
1302/** @} */
1303
1304#ifdef __TRANSMISSION__
1305#  include "session.h"
1306#endif
1307
1308#ifdef __cplusplus
1309}
1310#endif
1311
1312#endif
Note: See TracBrowser for help on using the repository browser.