source: trunk/libtransmission/transmission.h @ 1119

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

add support in libT and the mac interface for displaying comment, creator, and date created

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