source: trunk/libtransmission/transmission.h @ 766

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

Get peers separately from the rest of the stats. This should also get rid of a memory leak.

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