source: trunk/libtransmission/transmission.h @ 6120

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

wire up the backend proxy support.

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