source: trunk/libtransmission/transmission.h @ 1861

Last change on this file since 1861 was 1861, checked in by joshe, 15 years ago

Check error codes correctly in instead of reporting all errors as 'assert'.
Add TR_ERROR_IO_SPACE and TR_ERROR_IO_RESOURCES.

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