source: branches/multitracker/libtransmission/transmission.h @ 1234

Last change on this file since 1234 was 1234, checked in by livings124, 16 years ago

libT can now better report if it can connect to a tracker, and as a result the mac's queue system will now start the next for any error (not just those sent by the tracker)
  • Property svn:keywords set to Date Rev Author Id
File size: 16.6 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 1234 2006-12-16 01:58:07Z livings124 $
3 *
4 * Copyright (c) 2005-2006 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 PRIu64
36# define PRIu64 "lld"
37#endif
38#include <time.h>
39
40#define SHA_DIGEST_LENGTH 20
41#ifdef __BEOS__
42# include <StorageDefs.h>
43# define MAX_PATH_LENGTH  B_FILE_NAME_LENGTH
44#else
45# define MAX_PATH_LENGTH  1024
46#endif
47
48#ifndef INET_ADDRSTRLEN
49#define INET_ADDRSTRLEN 16
50#endif
51
52#define TR_DEFAULT_PORT   9090
53#define TR_NOERROR        0
54
55/***********************************************************************
56 * tr_init
57 ***********************************************************************
58 * Initializes a libtransmission instance. Returns a obscure handle to
59 * be passed to all functions below.
60 **********************************************************************/
61typedef struct tr_handle_s tr_handle_t;
62tr_handle_t * tr_init();
63
64typedef struct tr_tracker_info_s tr_tracker_info_t;
65
66/***********************************************************************
67 * tr_setMessageLevel
68 ***********************************************************************
69 * Set the level of messages to be output or queued
70 **********************************************************************/
71#define TR_MSG_ERR 1
72#define TR_MSG_INF 2
73#define TR_MSG_DBG 3
74void tr_setMessageLevel( int );
75int tr_getMessageLevel( void );
76
77/***********************************************************************
78 * tr_setMessageQueuing
79 ***********************************************************************
80 * Enable or disable message queuing
81 **********************************************************************/
82typedef struct tr_msg_list_s tr_msg_list_t;
83void tr_setMessageQueuing( int );
84
85/***********************************************************************
86 * tr_getQueuedMessages
87 ***********************************************************************
88 * Return a list of queued messages
89 **********************************************************************/
90tr_msg_list_t * tr_getQueuedMessages( void );
91void tr_freeMessageList( tr_msg_list_t * list );
92
93/***********************************************************************
94 * tr_getPrefsDirectory
95 ***********************************************************************
96 * Returns the full path to a directory which can be used to store
97 * preferences. The string belongs to libtransmission, do not free it.
98 **********************************************************************/
99char * tr_getPrefsDirectory();
100
101/***********************************************************************
102 * tr_setBindPort
103 ***********************************************************************
104 * Sets the port to listen for incoming peer connections.
105 * This can be safely called even with active torrents.
106 **********************************************************************/
107void tr_setBindPort( tr_handle_t *, int );
108
109/***********************************************************************
110 * tr_natTraversalEnable
111 * tr_natTraversalDisable
112 ***********************************************************************
113 * Enable or disable NAT traversal using NAT-PMP or UPnP IGD.
114 **********************************************************************/
115void tr_natTraversalEnable( tr_handle_t * );
116void tr_natTraversalDisable( tr_handle_t * );
117
118/***********************************************************************
119 * tr_natTraversalStatus
120 ***********************************************************************
121 * Return the status of NAT traversal
122 **********************************************************************/
123#define TR_NAT_TRAVERSAL_MAPPING        1
124#define TR_NAT_TRAVERSAL_MAPPED         2
125#define TR_NAT_TRAVERSAL_NOTFOUND       3
126#define TR_NAT_TRAVERSAL_ERROR          4
127#define TR_NAT_TRAVERSAL_UNMAPPING      5
128#define TR_NAT_TRAVERSAL_DISABLED       6
129#define TR_NAT_TRAVERSAL_IS_DISABLED( st ) \
130  ( TR_NAT_TRAVERSAL_DISABLED == (st) || TR_NAT_TRAVERSAL_UNMAPPING == (st) )
131int tr_natTraversalStatus( tr_handle_t * );
132
133/***********************************************************************
134 * tr_setUploadLimit
135 ***********************************************************************
136 * Sets the total upload rate limit in KB/s
137 **********************************************************************/
138void tr_setUploadLimit( tr_handle_t *, int );
139
140/***********************************************************************
141 * tr_setDownloadLimit
142 ***********************************************************************
143 * Sets the total download rate limit in KB/s
144 **********************************************************************/
145void tr_setDownloadLimit( tr_handle_t *, int );
146
147/***********************************************************************
148 * tr_torrentCount
149 ***********************************************************************
150 * Returns the count of open torrents
151 **********************************************************************/
152int tr_torrentCount( tr_handle_t * h );
153
154/***********************************************************************
155 * tr_torrentIterate
156 ***********************************************************************
157 * Iterates on open torrents
158 **********************************************************************/
159typedef struct tr_torrent_s tr_torrent_t;
160typedef void (*tr_callback_t) ( tr_torrent_t *, void * );
161void tr_torrentIterate( tr_handle_t *, tr_callback_t, void * );
162
163/***********************************************************************
164 * tr_torrentRates
165 ***********************************************************************
166 * Gets the total download and upload rates
167 **********************************************************************/
168void tr_torrentRates( tr_handle_t *, float *, float * );
169
170/***********************************************************************
171 * tr_close
172 ***********************************************************************
173 * Frees memory allocated by tr_init.
174 **********************************************************************/
175void tr_close( tr_handle_t * );
176
177/***********************************************************************
178 * tr_torrentInit
179 ***********************************************************************
180 * Opens and parses torrent file at 'path'. If the file exists and is a
181 * valid torrent file, returns an handle and adds it to the list of
182 * torrents (but doesn't start it). Returns NULL and sets *error
183 * otherwise.  If the TR_FSAVEPRIVATE flag is passed then a private copy
184 * of the torrent file will be saved.
185 **********************************************************************/
186#define TR_EINVALID     1
187#define TR_EUNSUPPORTED 2
188#define TR_EDUPLICATE   3
189#define TR_EOTHER       666
190tr_torrent_t * tr_torrentInit( tr_handle_t *, const char * path,
191                               int flags, int * error );
192
193/***********************************************************************
194 * tr_torrentInitSaved
195 ***********************************************************************
196 * Opens and parses a torrent file as with tr_torrentInit, only taking
197 * the hash string of a saved torrent file instead of a filename.  There
198 * are currently no valid flags for this function.
199 **********************************************************************/
200tr_torrent_t * tr_torrentInitSaved( tr_handle_t *, const char * hashStr,
201                                    int flags, int * error );
202
203typedef struct tr_info_s tr_info_t;
204tr_info_t * tr_torrentInfo( tr_torrent_t * );
205
206/***********************************************************************
207 * tr_torrentScrape
208 ***********************************************************************
209 * Asks the tracker for the count of seeders and leechers. Returns 0
210 * and fills 's' and 'l' if successful. Otherwise returns 1 if the
211 * tracker doesn't support the scrape protocol, is unreachable or
212 * replied with some error. tr_torrentScrape may block up to 20 seconds
213 * before returning.
214 **********************************************************************/
215int tr_torrentScrape( tr_torrent_t *, int * s, int * l, int * d );
216
217/***********************************************************************
218 * tr_torrentStart
219 ***********************************************************************
220 * Starts downloading. The download is launched in a seperate thread,
221 * therefore tr_torrentStart returns immediately.
222 **********************************************************************/
223void   tr_torrentSetFolder( tr_torrent_t *, const char * );
224char * tr_torrentGetFolder( tr_torrent_t * );
225void   tr_torrentStart( tr_torrent_t * );
226
227/***********************************************************************
228 * tr_torrentStop
229 ***********************************************************************
230 * Stops downloading and notices the tracker that we are leaving. The
231 * thread keeps running while doing so.
232 * The thread will eventually be joined, either:
233 * - by tr_torrentStat when the tracker has been successfully noticed,
234 * - by tr_torrentStat if the tracker could not be noticed within 60s,
235 * - by tr_torrentClose if you choose to remove the torrent without
236 *   waiting any further.
237 **********************************************************************/
238void tr_torrentStop( tr_torrent_t * );
239
240/***********************************************************************
241 * tr_getFinished
242 ***********************************************************************
243 * The first call after a torrent is completed returns 1. Returns 0
244 * in other cases.
245 **********************************************************************/
246int tr_getFinished( tr_torrent_t * );
247
248/***********************************************************************
249 * tr_torrentStat
250 ***********************************************************************
251 * Returns a pointer to an tr_stat_t structure with updated information
252 * on the torrent. The structure belongs to libtransmission (do not
253 * free it) and is guaranteed to be unchanged until the next call to
254 * tr_torrentStat.
255 * The interface should call this function every second or so in order
256 * to update itself.
257 **********************************************************************/
258typedef struct tr_stat_s tr_stat_t;
259tr_stat_t * tr_torrentStat( tr_torrent_t * );
260
261/***********************************************************************
262 * tr_torrentPeers
263 ***********************************************************************/
264typedef struct tr_peer_stat_s tr_peer_stat_t;
265tr_peer_stat_t * tr_torrentPeers( tr_torrent_t *, int * peerCount );
266void tr_torrentPeersFree( tr_peer_stat_t *, int peerCount );
267
268/***********************************************************************
269 * tr_torrentAvailability
270 ***********************************************************************
271 * Use this to draw an advanced progress bar which is 'size' pixels
272 * wide. Fills 'tab' which you must have allocated: each byte is set
273 * to either -1 if we have the piece, otherwise it is set to the number
274 * of connected peers who have the piece.
275 **********************************************************************/
276void tr_torrentAvailability( tr_torrent_t *, int8_t * tab, int size );
277
278void tr_torrentAmountFinished( tr_torrent_t * tor, float * tab, int size );
279
280/***********************************************************************
281 * tr_torrentRemoveSaved
282 ***********************************************************************
283 * Removes the private saved copy of a torrent file for torrents which
284 * the TR_FSAVEPRIVATE flag is set.
285 **********************************************************************/
286void tr_torrentRemoveSaved( tr_torrent_t * );
287
288/***********************************************************************
289 * tr_torrentClose
290 ***********************************************************************
291 * Frees memory allocated by tr_torrentInit. If the torrent was running,
292 * you must call tr_torrentStop() before closing it.
293 **********************************************************************/
294void tr_torrentClose( tr_handle_t *, tr_torrent_t * );
295
296/***********************************************************************
297 * tr_info_s
298 **********************************************************************/
299typedef struct tr_file_s
300{
301    uint64_t length;                /* Length of the file, in bytes */
302    char     name[MAX_PATH_LENGTH]; /* Path to the file */
303}
304tr_file_t;
305struct tr_info_s
306{
307    /* Path to torrent */
308    char                 torrent[MAX_PATH_LENGTH];
309
310    /* General info */
311    uint8_t              hash[SHA_DIGEST_LENGTH];
312    char                 hashString[2*SHA_DIGEST_LENGTH+1];
313    char                 name[MAX_PATH_LENGTH];
314
315    /* Flags */
316#define TR_FSAVEPRIVATE 0x01    /* save a private copy of the torrent */
317    int                  flags;
318
319    /* Tracker info */
320    struct
321    {
322        tr_tracker_info_t * list;
323        int                 count;
324    }                  * trackerList;
325    int                  trackerTiers;
326
327    /* Torrent info */
328    char                 comment[MAX_PATH_LENGTH];
329    char                 creator[MAX_PATH_LENGTH];
330    int                  dateCreated;
331    int                  privateTorrent;
332
333    /* Pieces info */
334    int                  pieceSize;
335    int                  pieceCount;
336    uint64_t             totalSize;
337    uint8_t            * pieces;
338
339    /* Files info */
340    int                  multifile;
341    int                  fileCount;
342    tr_file_t          * files;
343};
344
345/***********************************************************************
346 * tr_stat_s
347 **********************************************************************/
348struct tr_stat_s
349{
350#define TR_STATUS_CHECK    0x001 /* Checking files */
351#define TR_STATUS_DOWNLOAD 0x002 /* Downloading */
352#define TR_STATUS_SEED     0x004 /* Seeding */
353#define TR_STATUS_STOPPING 0x008 /* Sending 'stopped' to the tracker */
354#define TR_STATUS_STOPPED  0x010 /* Sent 'stopped' but thread still
355                                    running (for internal use only) */
356#define TR_STATUS_PAUSE    0x020 /* Paused */
357
358#define TR_STATUS_ACTIVE   (TR_STATUS_CHECK|TR_STATUS_DOWNLOAD|TR_STATUS_SEED)
359#define TR_STATUS_INACTIVE (TR_STATUS_STOPPING|TR_STATUS_STOPPED|TR_STATUS_PAUSE)
360    int                 status;
361
362#define TR_ETRACKER 1
363#define TR_EINOUT   2
364    int                 error;
365    char                trackerError[128];
366    int                 cannotConnect;
367   
368    const char        * trackerAddress;
369    int                 trackerPort;
370    const char        * trackerAnnounce;
371
372    float               progress;
373    float               rateDownload;
374    float               rateUpload;
375    int                 eta;
376    int                 peersTotal;
377    int                 peersIncoming;
378    int                 peersUploading;
379    int                 peersDownloading;
380    int                 seeders;
381    int                 leechers;
382    int                 completedFromTracker;
383
384    uint64_t            downloaded;
385    uint64_t            uploaded;
386    float               swarmspeed;
387};
388
389struct tr_peer_stat_s
390{
391    char    addr[INET_ADDRSTRLEN];
392    char *  client;
393   
394    int     isConnected;
395    int     isIncoming;
396    int     isDownloading;
397    int     isUploading;
398    float   progress;
399};
400
401struct tr_msg_list_s
402{
403    int                    level;
404    time_t                 when;
405    char                 * message;
406    struct tr_msg_list_s * next;
407};
408
409struct tr_tracker_info_s
410{
411    char * address;
412    int    port;
413    char * announce;
414};
415
416#ifdef __TRANSMISSION__
417#  include "internal.h"
418#endif
419
420#ifdef __cplusplus
421}
422#endif
423
424#endif
Note: See TracBrowser for help on using the repository browser.