source: trunk/libtransmission/transmission.h @ 788

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

Try to keep track of the overall speed of the swarm.
Patch by Denis Ahrens.

  • Property svn:keywords set to Date Rev Author Id
File size: 13.9 KB
Line 
1/******************************************************************************
2 * $Id: transmission.h 788 2006-08-16 19:21:09Z joshe $
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
39#define SHA_DIGEST_LENGTH 20
40#ifdef __BEOS__
41# include <StorageDefs.h>
42# define MAX_PATH_LENGTH  B_FILE_NAME_LENGTH
43#else
44# define MAX_PATH_LENGTH  1024
45#endif
46
47#ifndef INET_ADDRSTRLEN
48#define INET_ADDRSTRLEN 16
49#endif
50
51#define TR_DEFAULT_PORT   9090
52#define TR_NOERROR        0
53
54/***********************************************************************
55 * tr_init
56 ***********************************************************************
57 * Initializes a libtransmission instance. Returns a obscure handle to
58 * be passed to all functions below.
59 **********************************************************************/
60typedef struct tr_handle_s tr_handle_t;
61tr_handle_t * tr_init();
62
63/***********************************************************************
64 * tr_setErrorFunction
65 ***********************************************************************
66 * Sets the function used to display libtransmission errors.  A NULL
67 * function means to use the default, which simple prints the message
68 * to stderr.  The function's prototype should look like this:
69 * void myErrFunc( const char * errstr );
70 **********************************************************************/
71void tr_setErrorFunction( void (*func)( const char * ) );
72
73/***********************************************************************
74 * tr_getPrefsDirectory
75 ***********************************************************************
76 * Returns the full path to a directory which can be used to store
77 * preferences. The string belongs to libtransmission, do not free it.
78 **********************************************************************/
79char * tr_getPrefsDirectory();
80
81/***********************************************************************
82 * tr_setBindPort
83 ***********************************************************************
84 * Sets a "start" port: everytime we start a torrent, we try to bind
85 * this port, then the next one and so on until we are successful.
86 **********************************************************************/
87void tr_setBindPort( tr_handle_t *, int );
88
89/***********************************************************************
90 * tr_setUploadLimit
91 ***********************************************************************
92 * Sets the total upload rate limit in KB/s
93 **********************************************************************/
94void tr_setUploadLimit( tr_handle_t *, int );
95
96/***********************************************************************
97 * tr_setDownloadLimit
98 ***********************************************************************
99 * Sets the total download rate limit in KB/s
100 **********************************************************************/
101void tr_setDownloadLimit( tr_handle_t *, int );
102
103/***********************************************************************
104 * tr_torrentCount
105 ***********************************************************************
106 * Returns the count of open torrents
107 **********************************************************************/
108int tr_torrentCount( tr_handle_t * h );
109
110/***********************************************************************
111 * tr_torrentIterate
112 ***********************************************************************
113 * Iterates on open torrents
114 **********************************************************************/
115typedef struct tr_torrent_s tr_torrent_t;
116typedef void (*tr_callback_t) ( tr_torrent_t *, void * );
117void tr_torrentIterate( tr_handle_t *, tr_callback_t, void * );
118
119/***********************************************************************
120 * tr_torrentRates
121 ***********************************************************************
122 * Gets the total download and upload rates
123 **********************************************************************/
124void tr_torrentRates( tr_handle_t *, float *, float * );
125
126/***********************************************************************
127 * tr_close
128 ***********************************************************************
129 * Frees memory allocated by tr_init.
130 **********************************************************************/
131void tr_close( tr_handle_t * );
132
133/***********************************************************************
134 * tr_torrentInit
135 ***********************************************************************
136 * Opens and parses torrent file at 'path'. If the file exists and is a
137 * valid torrent file, returns an handle and adds it to the list of
138 * torrents (but doesn't start it). Returns NULL and sets *error
139 * otherwise.  If the TR_FSAVEPRIVATE flag is passed then a private copy
140 * of the torrent file will be saved.
141 **********************************************************************/
142#define TR_EINVALID     1
143#define TR_EUNSUPPORTED 2
144#define TR_EDUPLICATE   3
145#define TR_EOTHER       666
146tr_torrent_t * tr_torrentInit( tr_handle_t *, const char * path,
147                               int flags, int * error );
148
149/***********************************************************************
150 * tr_torrentInitSaved
151 ***********************************************************************
152 * Opens and parses a torrent file as with tr_torrentInit, only taking
153 * the hash string of a saved torrent file instead of a filename.  There
154 * are currently no valid flags for this function.
155 **********************************************************************/
156tr_torrent_t * tr_torrentInitSaved( tr_handle_t *, const char * hashStr,
157                                    int flags, int * error );
158
159typedef struct tr_info_s tr_info_t;
160tr_info_t * tr_torrentInfo( tr_torrent_t * );
161
162/***********************************************************************
163 * tr_torrentScrape
164 ***********************************************************************
165 * Asks the tracker for the count of seeders and leechers. Returns 0
166 * and fills 's' and 'l' if successful. Otherwise returns 1 if the
167 * tracker doesn't support the scrape protocol, is unreachable or
168 * replied with some error. tr_torrentScrape may block up to 20 seconds
169 * before returning.
170 **********************************************************************/
171int tr_torrentScrape( tr_torrent_t *, int * s, int * l );
172
173/***********************************************************************
174 * tr_torrentStart
175 ***********************************************************************
176 * Starts downloading. The download is launched in a seperate thread,
177 * therefore tr_torrentStart returns immediately.
178 **********************************************************************/
179void   tr_torrentSetFolder( tr_torrent_t *, const char * );
180char * tr_torrentGetFolder( tr_torrent_t * );
181void   tr_torrentStart( tr_torrent_t * );
182
183/***********************************************************************
184 * tr_torrentStop
185 ***********************************************************************
186 * Stops downloading and notices the tracker that we are leaving. The
187 * thread keeps running while doing so.
188 * The thread will eventually be joined, either:
189 * - by tr_torrentStat when the tracker has been successfully noticed,
190 * - by tr_torrentStat if the tracker could not be noticed within 60s,
191 * - by tr_torrentClose if you choose to remove the torrent without
192 *   waiting any further.
193 **********************************************************************/
194void tr_torrentStop( tr_torrent_t * );
195
196/***********************************************************************
197 * tr_getFinished
198 ***********************************************************************
199 * The first call after a torrent is completed returns 1. Returns 0
200 * in other cases.
201 **********************************************************************/
202int tr_getFinished( tr_torrent_t * );
203
204/***********************************************************************
205 * tr_torrentStat
206 ***********************************************************************
207 * Returns a pointer to an tr_stat_t structure with updated information
208 * on the torrent. The structure belongs to libtransmission (do not
209 * free it) and is guaranteed to be unchanged until the next call to
210 * tr_torrentStat.
211 * The interface should call this function every second or so in order
212 * to update itself.
213 **********************************************************************/
214typedef struct tr_stat_s tr_stat_t;
215tr_stat_t * tr_torrentStat( tr_torrent_t * );
216
217/***********************************************************************
218 * tr_torrentPeers
219 ***********************************************************************/
220typedef struct tr_peer_stat_s tr_peer_stat_t;
221tr_peer_stat_t * tr_torrentPeers( tr_torrent_t *, int * peerCount );
222void tr_torrentPeersFree( tr_peer_stat_t *, int peerCount );
223
224/***********************************************************************
225 * tr_torrentAvailability
226 ***********************************************************************
227 * Use this to draw an advanced progress bar which is 'size' pixels
228 * wide. Fills 'tab' which you must have allocated: each byte is set
229 * to either -1 if we have the piece, otherwise it is set to the number
230 * of connected peers who have the piece.
231 **********************************************************************/
232void tr_torrentAvailability( tr_torrent_t *, int8_t * tab, int size );
233
234/***********************************************************************
235 * tr_torrentRemoveSaved
236 ***********************************************************************
237 * Removes the private saved copy of a torrent file for torrents which
238 * the TR_FSAVEPRIVATE flag is set.
239 **********************************************************************/
240void tr_torrentRemoveSaved( tr_torrent_t * );
241
242/***********************************************************************
243 * tr_torrentClose
244 ***********************************************************************
245 * Frees memory allocated by tr_torrentInit. If the torrent was running,
246 * you must call tr_torrentStop() before closing it.
247 **********************************************************************/
248void tr_torrentClose( tr_handle_t *, tr_torrent_t * );
249
250/***********************************************************************
251 * tr_info_s
252 **********************************************************************/
253typedef struct tr_file_s
254{
255    uint64_t length;                /* Length of the file, in bytes */
256    char     name[MAX_PATH_LENGTH]; /* Path to the file */
257}
258tr_file_t;
259struct tr_info_s
260{
261    /* Path to torrent */
262    char        torrent[MAX_PATH_LENGTH];
263
264    /* General info */
265    uint8_t     hash[SHA_DIGEST_LENGTH];
266    char        hashString[2*SHA_DIGEST_LENGTH+1];
267    char        name[MAX_PATH_LENGTH];
268
269    /* Flags */
270#define TR_FSAVEPRIVATE 0x01    /* save a private copy of the torrent */
271    int         flags;
272
273    /* Tracker info */
274    char        trackerAddress[256];
275    int         trackerPort;
276    char        trackerAnnounce[MAX_PATH_LENGTH];
277
278    /* Pieces info */
279    int         pieceSize;
280    int         pieceCount;
281    uint64_t    totalSize;
282    uint8_t   * pieces;
283
284    /* Files info */
285    int         multifile;
286    int         fileCount;
287    tr_file_t * files;
288};
289
290/***********************************************************************
291 * tr_stat_s
292 **********************************************************************/
293struct tr_stat_s
294{
295#define TR_STATUS_CHECK    0x001 /* Checking files */
296#define TR_STATUS_DOWNLOAD 0x002 /* Downloading */
297#define TR_STATUS_SEED     0x004 /* Seeding */
298#define TR_STATUS_STOPPING 0x008 /* Sending 'stopped' to the tracker */
299#define TR_STATUS_STOPPED  0x010 /* Sent 'stopped' but thread still
300                                    running (for internal use only) */
301#define TR_STATUS_PAUSE    0x020 /* Paused */
302
303#define TR_STATUS_ACTIVE   (TR_STATUS_CHECK|TR_STATUS_DOWNLOAD|TR_STATUS_SEED)
304#define TR_STATUS_INACTIVE (TR_STATUS_STOPPING|TR_STATUS_STOPPED|TR_STATUS_PAUSE)
305    int                 status;
306
307#define TR_ETRACKER 1
308#define TR_EINOUT   2
309    int                 error;
310    char                trackerError[128];
311
312    float               progress;
313    float               rateDownload;
314    float               rateUpload;
315    int                 eta;
316    int                 peersTotal;
317    int                 peersUploading;
318    int                 peersDownloading;
319    int                 seeders;
320    int                 leechers;
321
322    uint64_t            downloaded;
323    uint64_t            uploaded;
324    float               swarmspeed;
325};
326
327struct tr_peer_stat_s
328{
329    char    addr[INET_ADDRSTRLEN];
330    char *  client;
331   
332    int     isConnected;
333    int     isDownloading;
334    int     isUploading;
335};
336
337#ifdef __TRANSMISSION__
338#  include "internal.h"
339#endif
340
341#ifdef __cplusplus
342}
343#endif
344
345#endif
Note: See TracBrowser for help on using the repository browser.