source: trunk/libtransmission/transmission.h @ 346

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

Add support to libtransmission and the MacOS X GUI for saving private copies of

torrent files.

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