source: trunk/libtransmission/transmission.h @ 2149

Last change on this file since 2149 was 2149, checked in by livings124, 15 years ago

Merge file selection and torrent creation into the main branch.

The new code for these features is under a new license.

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