source: trunk/libtransmission/transmission.h @ 817

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

Add time to messages.

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