source: branches/new_api/libtransmission/transmission.h @ 137

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

Adds a permanent handle for every torrent.
Removed the limit on the number of open torrents.

File size: 9.7 KB
Line 
1/******************************************************************************
2 * Copyright (c) 2005-2006 Transmission authors and contributors
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
20 * DEALINGS IN THE SOFTWARE.
21 *****************************************************************************/
22
23#ifndef TR_TRANSMISSION_H
24#define TR_TRANSMISSION_H 1
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30#include <inttypes.h>
31
32#define SHA_DIGEST_LENGTH    20
33#ifdef __BEOS__
34# include <StorageDefs.h>
35# define MAX_PATH_LENGTH B_FILE_NAME_LENGTH
36#else
37# define MAX_PATH_LENGTH      1024
38#endif
39
40#define TR_DEFAULT_PORT      9090
41
42/***********************************************************************
43 * tr_init
44 ***********************************************************************
45 * Initializes a libtransmission instance. Returns a obscure handle to
46 * be passed to all functions below.
47 **********************************************************************/
48typedef struct tr_handle_s tr_handle_t;
49
50tr_handle_t * tr_init();
51
52/***********************************************************************
53 * tr_getPrefsDirectory
54 ***********************************************************************
55 * Returns the full path to the directory used by libtransmission to
56 * store the resume files. The string belongs to libtransmission, do
57 * not free it.
58 **********************************************************************/
59char * tr_getPrefsDirectory();
60
61/***********************************************************************
62 * tr_setBindPort
63 ***********************************************************************
64 * Sets a "start" port: everytime we start a torrent, we try to bind
65 * this port, then the next one and so on until we are successful.
66 **********************************************************************/
67void tr_setBindPort( tr_handle_t *, int );
68
69/***********************************************************************
70 * tr_setUploadLimit
71 ***********************************************************************
72 * Sets the total upload rate limit in KB/s
73 **********************************************************************/
74void tr_setUploadLimit( tr_handle_t *, int );
75
76/***********************************************************************
77 * tr_torrentRates
78 ***********************************************************************
79 * Gets the total download and upload rates
80 **********************************************************************/
81void tr_torrentRates( tr_handle_t *, float *, float * );
82
83/***********************************************************************
84 * tr_torrentInit
85 ***********************************************************************
86 * Opens and parses torrent file at 'path'. If the file exists and is a
87 * valid torrent file, returns an handle and adds it to the list of
88 * torrents (but doesn't start it). Returns NULL otherwise.
89 **********************************************************************/
90typedef struct tr_torrent_s tr_torrent_t;
91
92tr_torrent_t * tr_torrentInit( tr_handle_t *, const char * path );
93
94/***********************************************************************
95 * tr_torrentScrape
96 ***********************************************************************
97 * Asks the tracker for the count of seeders and leechers. Returns 0
98 * and fills 's' and 'l' if successful. Otherwise returns 1 if the
99 * tracker doesn't support the scrape protocol, is unreachable or
100 * replied with some error. tr_torrentScrape may block up to 20 seconds
101 * before returning.
102 **********************************************************************/
103int tr_torrentScrape( tr_torrent_t *, int * s, int * l );
104
105/***********************************************************************
106 * tr_torrentStart
107 ***********************************************************************
108 * Starts downloading. The download is launched in a seperate thread,
109 * therefore tr_torrentStart returns immediately.
110 **********************************************************************/
111void   tr_torrentSetFolder( tr_torrent_t *, const char * );
112char * tr_torrentGetFolder( tr_torrent_t * );
113void   tr_torrentStart( tr_torrent_t * );
114
115/***********************************************************************
116 * tr_torrentStop
117 ***********************************************************************
118 * Stops downloading and notices the tracker that we are leaving. The
119 * thread keeps running while doing so.
120 * The thread will eventually be joined, either:
121 * - by tr_torrentStat when the tracker has been successfully noticed,
122 * - by tr_torrentStat if the tracker could not be noticed within 60s,
123 * - by tr_torrentClose if you choose to remove the torrent without
124 *   waiting any further.
125 **********************************************************************/
126void tr_torrentStop( tr_torrent_t * );
127
128/***********************************************************************
129 * tr_getFinished
130 ***********************************************************************
131 * Tests to see if torrent is finished
132 **********************************************************************/
133int tr_getFinished( tr_torrent_t * );
134
135/***********************************************************************
136 * tr_setFinished
137 ***********************************************************************
138 * Sets the boolean value finished in the torrent back to false
139 **********************************************************************/
140void tr_setFinished( tr_torrent_t *, int );
141
142
143
144/***********************************************************************
145 * tr_torrentStat
146 ***********************************************************************
147 * Allocates an array of tr_stat_t structures, containing information
148 * about the current status of all open torrents (see the contents
149 * of tr_stat_s below). Returns the count of open torrents and sets
150 * (*s) to the address of the array, or NULL if no torrent is open.
151 * In the former case, the array belongs to the caller who is
152 * responsible of freeing it.
153 * The interface should call this function every 0.5 second or so in
154 * order to update itself.
155 **********************************************************************/
156typedef struct tr_stat_s tr_stat_t;
157
158int tr_torrentCount( tr_handle_t * h );
159tr_stat_t * tr_torrentStat( tr_torrent_t * );
160
161/***********************************************************************
162 * tr_torrentClose
163 ***********************************************************************
164 * Frees memory allocated by tr_torrentInit. If the torrent was running,
165 * you must call tr_torrentStop() before closing it.
166 **********************************************************************/
167void tr_torrentClose( tr_handle_t *, tr_torrent_t * );
168
169/***********************************************************************
170 * tr_close
171 ***********************************************************************
172 * Frees memory allocated by tr_init.
173 **********************************************************************/
174void tr_close( tr_handle_t * );
175
176
177/***********************************************************************
178 * tr_stat_s
179 **********************************************************************/
180typedef struct tr_file_s
181{
182    uint64_t length;                /* Length of the file, in bytes */
183    char     name[MAX_PATH_LENGTH]; /* Path to the file */
184}
185tr_file_t;
186
187typedef struct tr_info_s
188{
189    /* Path to torrent */
190    char        torrent[MAX_PATH_LENGTH];
191
192    /* General info */
193    uint8_t     hash[SHA_DIGEST_LENGTH];
194    char        name[MAX_PATH_LENGTH];
195
196    /* Tracker info */
197    char        trackerAddress[256];
198    int         trackerPort;
199    char        trackerAnnounce[MAX_PATH_LENGTH];
200
201    /* Pieces info */
202    int         pieceSize;
203    int         pieceCount;
204    uint64_t    totalSize;
205    uint8_t   * pieces;
206
207    /* Files info */
208    int         fileCount;
209    tr_file_t * files;
210}
211tr_info_t;
212
213struct tr_stat_s
214{
215    tr_info_t   info;
216
217#define TR_STATUS_CHECK    0x001 /* Checking files */
218#define TR_STATUS_DOWNLOAD 0x002 /* Downloading */
219#define TR_STATUS_SEED     0x004 /* Seeding */
220#define TR_STATUS_STOPPING 0x008 /* Sending 'stopped' to the tracker */
221#define TR_STATUS_STOPPED  0x010 /* Sent 'stopped' but thread still
222                                    running (for internal use only) */
223#define TR_STATUS_PAUSE    0x020 /* Paused */
224#define TR_TRACKER_ERROR   0x100
225    int         status;
226    char        error[128];
227
228    float       progress;
229    float       rateDownload;
230    float       rateUpload;
231    int         eta;
232    int         peersTotal;
233    int         peersUploading;
234    int         peersDownloading;
235    char        pieces[120];
236    int         seeders;
237    int         leechers;
238
239    uint64_t    downloaded;
240    uint64_t    uploaded;
241
242    char      * folder;
243};
244
245#ifdef __TRANSMISSION__
246#  include "internal.h"
247#endif
248
249#ifdef __cplusplus
250}
251#endif
252
253#endif
Note: See TracBrowser for help on using the repository browser.