source: trunk/libtransmission/transmission.h @ 264

Last change on this file since 264 was 264, checked in by titer, 16 years ago

Splits VERSION_STRING and VERSION_REVISION, removes duplication of flags
in the Xcode project file

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