source: trunk/libtransmission/transmission.h @ 2316

Last change on this file since 2316 was 2316, checked in by charles, 15 years ago

splitting dnd and priorities apart, and moving the file storage for those fields into fastresume

  • Property svn:keywords set to Date Rev Author Id
File size: 25.3 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 2316 2007-07-10 03:12:46Z charles $
3 *
4 * Copyright (c) 2005-2007 Transmission authors and contributors
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a
7 * copy of this software and associated documentation files (the "Software"),
8 * to deal in the Software without restriction, including without limitation
9 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 * and/or sell copies of the Software, and to permit persons to whom the
11 * Software is furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 * DEALINGS IN THE SOFTWARE.
23 *****************************************************************************/
24
25#ifndef TR_TRANSMISSION_H
26#define TR_TRANSMISSION_H 1
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32#include "version.h"
33
34#include <inttypes.h>
35#ifndef PRId64
36# define PRId64 "lld"
37#endif
38#ifndef PRIu64
39# define PRIu64 "llu"
40#endif
41#include <time.h>
42
43#define SHA_DIGEST_LENGTH 20
44#ifdef __BEOS__
45# include <StorageDefs.h>
46# define MAX_PATH_LENGTH  B_FILE_NAME_LENGTH
47#else
48# define MAX_PATH_LENGTH  1024
49#endif
50
51#ifndef INET_ADDRSTRLEN
52#define INET_ADDRSTRLEN 16
53#endif
54
55#if defined(__MINGW__)
56#define TR_PATH_DELIMITER '\\'
57#define TR_PATH_DELIMITER_STR "\\"
58#else
59#define TR_PATH_DELIMITER '/'
60#define TR_PATH_DELIMITER_STR "/"
61#endif
62
63#define TR_DEFAULT_PORT   9090
64
65#define TR_PEER_FROM__MAX       4
66#define TR_PEER_FROM_INCOMING   0 /* connections made to the listening port */
67#define TR_PEER_FROM_TRACKER    1 /* peers received from a tracker */
68#define TR_PEER_FROM_CACHE      2 /* peers read from the peer cache */
69#define TR_PEER_FROM_PEX        3 /* peers discovered via PEX */
70
71/***********************************************************************
72 * Error codes
73 **********************************************************************/
74/* General errors */
75#define TR_OK                       0x00000000
76#define TR_ERROR                    0x81000000
77#define TR_ERROR_ASSERT             0x82000000
78/* I/O errors */
79#define TR_ERROR_IO_MASK            0x000000FF
80#define TR_ERROR_IO_PARENT          ((1<<31) | (1<<0))
81#define TR_ERROR_IO_PERMISSIONS     ((1<<31) | (1<<1))
82#define TR_ERROR_IO_SPACE           ((1<<31) | (1<<2))
83#define TR_ERROR_IO_FILE_TOO_BIG    ((1<<31) | (1<<3))
84#define TR_ERROR_IO_OPEN_FILES      ((1<<31) | (1<<4))
85#define TR_ERROR_IO_DUP_DOWNLOAD    ((1<<31) | (1<<5))
86#define TR_ERROR_IO_OTHER           ((1<<31) | (1<<6))
87/* Misc */
88#define TR_ERROR_TC_MASK            0x00000F00
89#define TR_ERROR_TC_ERROR           0x80000100
90#define TR_ERROR_TC_WARNING         0x80000200
91
92#define TR_ERROR_ISSET( num, code ) ( (code) == ( (code) & (num) ) )
93
94/***********************************************************************
95 * tr_init
96 ***********************************************************************
97 * Initializes a libtransmission instance. Returns a obscure handle to
98 * be passed to all functions below. The tag argument is a short string
99 * unique to the program invoking tr_init(), it is currently used as
100 * part of saved torrent files' names to prevent one frontend from
101 * deleting a torrent used by another. The following tags are used:
102 *   beos cli daemon gtk macosx
103 **********************************************************************/
104typedef struct tr_handle_s tr_handle_t;
105tr_handle_t * tr_init( const char * tag );
106
107typedef struct tr_tracker_info_s tr_tracker_info_t;
108
109/***********************************************************************
110 * tr_setMessageLevel
111 ***********************************************************************
112 * Set the level of messages to be output or queued
113 **********************************************************************/
114#define TR_MSG_ERR 1
115#define TR_MSG_INF 2
116#define TR_MSG_DBG 3
117void tr_setMessageLevel( int );
118int tr_getMessageLevel( void );
119
120/***********************************************************************
121 * tr_setMessageQueuing
122 ***********************************************************************
123 * Enable or disable message queuing
124 **********************************************************************/
125typedef struct tr_msg_list_s tr_msg_list_t;
126void tr_setMessageQueuing( int );
127
128/***********************************************************************
129 * tr_getQueuedMessages
130 ***********************************************************************
131 * Return a list of queued messages
132 **********************************************************************/
133tr_msg_list_t * tr_getQueuedMessages( void );
134void tr_freeMessageList( tr_msg_list_t * list );
135
136/***********************************************************************
137 * tr_getPrefsDirectory
138 ***********************************************************************
139 * Returns the full path to a directory which can be used to store
140 * preferences. The string belongs to libtransmission, do not free it.
141 **********************************************************************/
142const char * tr_getPrefsDirectory( void );
143
144/***********************************************************************
145 * tr_setBindPort
146 ***********************************************************************
147 * Sets the port to listen for incoming peer connections.
148 * This can be safely called even with active torrents.
149 **********************************************************************/
150void tr_setBindPort( tr_handle_t *, int );
151
152/***********************************************************************
153 * tr_natTraversalEnable
154 * tr_natTraversalDisable
155 ***********************************************************************
156 * Enable or disable NAT traversal using NAT-PMP or UPnP IGD.
157 **********************************************************************/
158void tr_natTraversalEnable( tr_handle_t *, int enable );
159
160/***********************************************************************
161 * tr_handleStatus
162 ***********************************************************************
163 * Returns some status info for the given handle.
164 **********************************************************************/
165typedef struct tr_handle_status_s tr_handle_status_t;
166tr_handle_status_t * tr_handleStatus( tr_handle_t * );
167
168/***********************************************************************
169 * tr_setGlobalUploadLimit
170 ***********************************************************************
171 * Sets the total upload rate limit in KB/s
172 **********************************************************************/
173void tr_setGlobalUploadLimit( tr_handle_t *, int );
174
175/***********************************************************************
176 * tr_setGlobalDownloadLimit
177 ***********************************************************************
178 * Sets the total download rate limit in KB/s
179 **********************************************************************/
180void tr_setGlobalDownloadLimit( tr_handle_t *, int );
181
182/***********************************************************************
183 * tr_torrentCount
184 ***********************************************************************
185 * Returns the count of open torrents
186 **********************************************************************/
187int tr_torrentCount( tr_handle_t * h );
188
189
190/***********************************************************************
191 * tr_torrentIterate
192 ***********************************************************************
193 * Iterates on open torrents
194 **********************************************************************/
195typedef struct tr_torrent_s tr_torrent_t;
196typedef void (*tr_callback_t) ( tr_torrent_t *, void * );
197void tr_torrentIterate( tr_handle_t *, tr_callback_t, void * );
198
199void tr_setUseCustomLimit( tr_torrent_t * tor, int limit );
200void tr_setUploadLimit( tr_torrent_t * tor, int limit );
201void tr_setDownloadLimit( tr_torrent_t * tor, int limit );
202
203/***********************************************************************
204 * Torrent Priorities
205 **********************************************************************/
206
207enum
208{
209    TR_PRI_LOW    = -1,
210    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
211    TR_PRI_HIGH   =  1
212};
213
214typedef int8_t tr_priority_t;
215
216/* priorities should be an array of tor->info.fileCount bytes,
217 * each holding a value of TR_PRI_NORMAL, _HIGH, or _LOW */
218void tr_torrentSetFilePriorities ( tr_torrent_t *, const tr_priority_t * priorities );
219
220/* single-file form of tr_torrentPrioritizeFiles.
221 * priority must be one of TR_PRI_NORMAL, _HIGH, or _LOW */
222void tr_torrentSetFilePriority( tr_torrent_t *, int file, tr_priority_t priority );
223
224/* returns a malloc()ed array of tor->info.fileCount items,
225 * each holding a value of TR_PRI_NORMAL, _HIGH, or _LOW.
226   free the array when done. */
227tr_priority_t* tr_torrentGetFilePriorities( const tr_torrent_t * );
228
229/* single-file form of tr_torrentGetFilePriorities.
230 * returns one of TR_PRI_NORMAL, _HIGH, or _LOW. */
231tr_priority_t tr_torrentGetFilePriority( const tr_torrent_t *, int file );
232
233/* returns true if the file's `download' flag is set */
234int tr_torrentGetFileDL( const tr_torrent_t *, int file );
235
236/* set the specified file's `download' flag */
237void tr_torrentSetFileDL( tr_torrent_t *, int file, int do_download );
238
239
240/***********************************************************************
241 * tr_torrentRates
242 ***********************************************************************
243 * Gets the total download and upload rates
244 **********************************************************************/
245void tr_torrentRates( tr_handle_t *, float *, float * );
246
247/***********************************************************************
248 * tr_close
249 ***********************************************************************
250 * Frees memory allocated by tr_init.
251 **********************************************************************/
252void tr_close( tr_handle_t * );
253
254/***********************************************************************
255 * tr_torrentInit
256 ***********************************************************************
257 * Opens and parses torrent file at 'path'. If the file exists and is
258 * a valid torrent file, returns an handle and adds it to the list of
259 * torrents (but doesn't start it). Returns NULL and sets *error
260 * otherwise. If hash is not NULL and the torrent is already loaded
261 * then it's 20-byte hash will be copied in. If the TR_FLAG_SAVE flag
262 * is passed then a copy of the torrent file will be saved.
263 **********************************************************************/
264#define TR_EINVALID     1
265#define TR_EUNSUPPORTED 2
266#define TR_EDUPLICATE   3
267#define TR_EOTHER       666
268tr_torrent_t * tr_torrentInit( tr_handle_t  * handle,
269                               const char   * metainfo_filename,
270                               const char   * destination,
271                               int            flags,
272                               int          * setme_error );
273
274typedef struct tr_info_s tr_info_t;
275
276/**
277 * Parses the specified metainfo file.
278 *
279 * Returns TR_OK if it parsed and can be added to Transmission.
280 * Returns TR_INVALID if it couldn't be parsed.
281 * Returns TR_EDUPLICATE if it parsed but can't be added.
282 *
283 * "destination" can be NULL if you don't need to know whether
284 * or not the torrent can be added.
285 *
286 " "setme_info" can be NULL if you don't need the information.
287 * If the metainfo can be parsed and setme_info is non-NULL,
288 * it will be filled with the metadata's info.  You'll need to
289 * call tr_metainfoFree( setme_info ) when done with it.
290 */
291int tr_torrentParse( const tr_handle_t  * handle,
292                     const char         * metainfo_filename,
293                     const char         * destination,
294                     tr_info_t          * setme_info );
295
296/**
297 * Parses the cached metainfo file that matches the given hash string.
298 * See tr_torrentParse() for a description of the arguments
299 */
300int
301tr_torrentParseHash( const tr_handle_t  * h,
302                     const char         * hashStr,
303                     const char         * destination,
304                     tr_info_t          * setme_info );
305
306
307/***********************************************************************
308 * tr_torrentInitData
309 ***********************************************************************
310 * Like tr_torrentInit, except the actual torrent data is passed in
311 * instead of the filename.
312 **********************************************************************/
313tr_torrent_t * tr_torrentInitData( tr_handle_t *,
314                                   const uint8_t * data, size_t size,
315                                   const char * destination,
316                                   int flags, int * error );
317
318/***********************************************************************
319 * tr_torrentInitSaved
320 ***********************************************************************
321 * Opens and parses a torrent file as with tr_torrentInit, only taking
322 * the hash string of a saved torrent file instead of a filename. There
323 * are currently no valid flags for this function.
324 **********************************************************************/
325tr_torrent_t * tr_torrentInitSaved( tr_handle_t *,
326                                    const char * hashStr,
327                                    const char * destination,
328                                    int flags, int * error );
329
330/***********************************************************************
331 * tr_torrentDisablePex
332 ***********************************************************************
333 * Disable or enable peer exchange for this torrent. Peer exchange is
334 * enabled by default, except for private torrents where pex is
335 * disabled and cannot be enabled.
336 **********************************************************************/
337void tr_torrentDisablePex( tr_torrent_t *, int disable );
338
339/***********************************************************************
340 * tr_torrentScrape
341 ***********************************************************************
342 * Return torrent metainfo.
343 **********************************************************************/
344const tr_info_t * tr_torrentInfo( const tr_torrent_t * );
345
346/***********************************************************************
347 * tr_torrentScrape
348 ***********************************************************************
349 * Asks the tracker for the count of seeders and leechers. Returns 0
350 * and fills 's' and 'l' if successful. Otherwise returns 1 if the
351 * tracker doesn't support the scrape protocol, is unreachable or
352 * replied with some error. tr_torrentScrape may block up to 20 seconds
353 * before returning.
354 **********************************************************************/
355int tr_torrentScrape( tr_torrent_t *, int * s, int * l, int * d );
356
357void   tr_torrentSetFolder( tr_torrent_t *, const char * );
358const char * tr_torrentGetFolder( const tr_torrent_t * );
359
360/***********************************************************************
361 * tr_torrentStart
362 ***********************************************************************
363 * Starts downloading. The download is launched in a seperate thread,
364 * therefore tr_torrentStart returns immediately.
365 **********************************************************************/
366void   tr_torrentStart( tr_torrent_t * );
367
368/***********************************************************************
369 * tr_torrentStop
370 ***********************************************************************
371 * Stops downloading and notices the tracker that we are leaving. The
372 * thread keeps running while doing so.
373 * The thread will eventually be joined, either:
374 * - by tr_torrentStat when the tracker has been successfully noticed,
375 * - by tr_torrentStat if the tracker could not be noticed within 60s,
376 * - by tr_torrentClose if you choose to remove the torrent without
377 *   waiting any further.
378 **********************************************************************/
379void tr_torrentStop( tr_torrent_t * );
380
381/***********************************************************************
382 * tr_getComplete, tr_getIncomplete and tr_getPartial
383 ***********************************************************************
384 * The first call after a torrent changed state returns 1. Returns 0
385 * in other cases.
386 **********************************************************************/
387int tr_getIncomplete( tr_torrent_t * tor );
388int tr_getDone( tr_torrent_t * tor );
389int tr_getComplete( tr_torrent_t * tor );
390
391
392/***********************************************************************
393 * tr_manualUpdate
394 ***********************************************************************
395 * Reannounce to tracker regardless of wait interval
396 **********************************************************************/
397void tr_manualUpdate( tr_torrent_t * );
398
399/***********************************************************************
400 * tr_torrentStat
401 ***********************************************************************
402 * Returns a pointer to an tr_stat_t structure with updated information
403 * on the torrent. The structure belongs to libtransmission (do not
404 * free it) and is guaranteed to be unchanged until the next call to
405 * tr_torrentStat.
406 * The interface should call this function every second or so in order
407 * to update itself.
408 **********************************************************************/
409typedef struct tr_stat_s tr_stat_t;
410tr_stat_t * tr_torrentStat( tr_torrent_t * );
411
412/***********************************************************************
413 * tr_torrentPeers
414 ***********************************************************************/
415typedef struct tr_peer_stat_s tr_peer_stat_t;
416tr_peer_stat_t * tr_torrentPeers( const tr_torrent_t *, int * peerCount );
417void tr_torrentPeersFree( tr_peer_stat_t *, int peerCount );
418
419/***********************************************************************
420 * tr_torrentAvailability
421 ***********************************************************************
422 * Use this to draw an advanced progress bar which is 'size' pixels
423 * wide. Fills 'tab' which you must have allocated: each byte is set
424 * to either -1 if we have the piece, otherwise it is set to the number
425 * of connected peers who have the piece.
426 **********************************************************************/
427void tr_torrentAvailability( const tr_torrent_t *, int8_t * tab, int size );
428
429void tr_torrentAmountFinished( const tr_torrent_t * tor, float * tab, int size );
430
431/***********************************************************************
432 * tr_torrentCompletion
433 ***********************************************************************
434 * Returns the completion progress for each file in the torrent as an
435 * array of floats the same size and order as in tr_info_t. Free the
436 * array when done.
437 **********************************************************************/
438float * tr_torrentCompletion( const tr_torrent_t * );
439
440float tr_torrentFileCompletion( const tr_torrent_t *, int fileIndex );
441
442uint64_t tr_torrentFileBytesCompleted( const tr_torrent_t *, int fileIndex ); 
443
444
445/***********************************************************************
446 * tr_torrentRemoveSaved
447 ***********************************************************************
448 * Removes the saved copy of a torrent file for torrents which the
449 * TR_FLAG_SAVE flag is set.
450 **********************************************************************/
451void tr_torrentRemoveSaved( tr_torrent_t * );
452
453void tr_torrentRecheck( tr_torrent_t * );
454
455/***********************************************************************
456 * tr_torrentClose
457 ***********************************************************************
458 * Frees memory allocated by tr_torrentInit. If the torrent was running,
459 * it is stopped first.
460 **********************************************************************/
461void tr_torrentClose( tr_torrent_t * );
462
463/***********************************************************************
464 * tr_info_s
465 **********************************************************************/
466
467typedef struct tr_file_s
468{
469    uint64_t length;                /* Length of the file, in bytes */
470    char     name[MAX_PATH_LENGTH]; /* Path to the file */
471    int8_t   priority;              /* TR_PRI_HIGH, _NORMAL, or _LOW */
472    int8_t   dnd;                   /* nonzero if the file shouldn't be downloaded */
473    int      firstPiece;            /* We need pieces [firstPiece... */
474    int      lastPiece;             /* ...lastPiece] to dl this file */
475    uint64_t offset;                /* file begins at the torrent's nth byte */
476}
477tr_file_t;
478
479typedef struct tr_piece_s
480{
481    uint8_t  hash[SHA_DIGEST_LENGTH];  /* pieces hash */
482    int8_t   priority;                 /* TR_PRI_HIGH, _NORMAL, or _LOW */
483    int8_t   dnd;                      /*  nonzero if the piece shouldn't be downloaded */
484}
485tr_piece_t;
486   
487struct tr_info_s
488{
489    /* Path to torrent */
490    char                 torrent[MAX_PATH_LENGTH];
491
492    /* General info */
493    uint8_t              hash[SHA_DIGEST_LENGTH];
494    char                 hashString[2*SHA_DIGEST_LENGTH+1];
495    char                 name[MAX_PATH_LENGTH];
496
497    /* Flags */
498#define TR_FLAG_SAVE    0x01 /* save a copy of the torrent file */
499#define TR_FLAG_PRIVATE 0x02 /* do not share information for this torrent */
500#define TR_FLAG_PAUSED  0x04 /* don't start the torrent when adding it */
501    int                  flags;
502
503    /* Tracker info */
504    struct
505    {
506        tr_tracker_info_t * list;
507        int                 count;
508    }                  * trackerList;
509    int                  trackerTiers;
510
511    /* Torrent info */
512    char                 comment[MAX_PATH_LENGTH];
513    char                 creator[MAX_PATH_LENGTH];
514    int                  dateCreated;
515
516    /* Pieces info */
517    int                  pieceSize;
518    int                  pieceCount;
519    uint64_t             totalSize;
520    tr_piece_t         * pieces;
521
522    /* Files info */
523    int                  multifile;
524    int                  fileCount;
525    tr_file_t          * files;
526};
527
528typedef enum
529{
530    TR_CP_INCOMPLETE,   /* doesn't have all the desired pieces */
531    TR_CP_DONE,         /* has all the pieces but the DND ones */
532    TR_CP_COMPLETE      /* has every piece */
533}
534cp_status_t;
535
536typedef enum
537{
538    TR_STATUS_CHECK_WAIT   = (1<<0), /* Waiting in queue to check files */
539    TR_STATUS_CHECK        = (1<<1), /* Checking files */
540    TR_STATUS_DOWNLOAD     = (1<<2), /* Downloading */
541    TR_STATUS_DONE         = (1<<3), /* not at 100% so can't tell the tracker
542                                        we're a seeder, but due to DND files
543                                        there's nothing we want right now */
544    TR_STATUS_SEED         = (1<<4), /* Seeding */
545    TR_STATUS_STOPPING     = (1<<5), /* Stopping -- closing connections, etc. */
546    TR_STATUS_STOPPED      = (1<<6)  /* Torrent is stopped */
547}
548torrent_status_t;
549
550#define TR_STATUS_ACTIVE \
551    (TR_STATUS_CHECK_WAIT|TR_STATUS_CHECK|TR_STATUS_DOWNLOAD|TR_STATUS_DONE|TR_STATUS_SEED)
552#define TR_STATUS_INACTIVE \
553    (TR_STATUS_STOPPING|TR_STATUS_STOPPED)
554
555/***********************************************************************
556 * tr_stat_s
557 **********************************************************************/
558struct tr_stat_s
559{
560    torrent_status_t    status;
561    cp_status_t         cpStatus;
562
563    int                 error;
564    char                errorString[128];
565    int                 cannotConnect;
566
567    tr_tracker_info_t * tracker;
568
569    float               percentComplete;
570    float               percentDone;
571    float               rateDownload;
572    float               rateUpload;
573    int                 eta;
574    int                 peersTotal;
575    int                 peersFrom[TR_PEER_FROM__MAX];
576    int                 peersUploading;
577    int                 peersDownloading;
578    int                 seeders;
579    int                 leechers;
580    int                 completedFromTracker;
581
582    uint64_t            left;
583    uint64_t            downloaded;
584    uint64_t            downloadedValid;
585    uint64_t            uploaded;
586    float               swarmspeed;
587
588#define TR_RATIO_NA  -1
589    float               ratio;
590   
591    uint64_t            startDate;
592    uint64_t            activityDate;
593};
594
595struct tr_peer_stat_s
596{
597    char    addr[INET_ADDRSTRLEN];
598    const char * client;
599   
600    int     isConnected;
601    int     from;
602    float   progress;
603    int     port;
604   
605    int     isDownloading;
606    int     isUploading;
607    float   downloadFromRate;
608    float   uploadToRate;
609};
610
611struct tr_msg_list_s
612{
613    int                    level;
614    time_t                 when;
615    char                 * message;
616    struct tr_msg_list_s * next;
617};
618
619struct tr_tracker_info_s
620{
621    char * address;
622    int    port;
623    char * announce;
624    char * scrape;
625};
626
627struct tr_handle_status_s
628{
629#define TR_NAT_TRAVERSAL_MAPPING        1
630#define TR_NAT_TRAVERSAL_MAPPED         2
631#define TR_NAT_TRAVERSAL_NOTFOUND       3
632#define TR_NAT_TRAVERSAL_ERROR          4
633#define TR_NAT_TRAVERSAL_UNMAPPING      5
634#define TR_NAT_TRAVERSAL_DISABLED       6
635#define TR_NAT_TRAVERSAL_IS_DISABLED( st ) \
636  ( TR_NAT_TRAVERSAL_DISABLED == (st) || TR_NAT_TRAVERSAL_UNMAPPING == (st) )
637    int natTraversalStatus;
638    int publicPort;
639};
640
641#ifdef __TRANSMISSION__
642#  include "internal.h"
643#endif
644
645#ifdef __cplusplus
646}
647#endif
648
649#endif
Note: See TracBrowser for help on using the repository browser.