source: trunk/libtransmission/transmission.h @ 6

Last change on this file since 6 was 6, checked in by root, 16 years ago

Update 2005-11-21

File size: 9.5 KB
Line 
1/******************************************************************************
2 * Copyright (c) 2005 Eric Petit
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#include <inttypes.h>
27
28#define SHA_DIGEST_LENGTH    20
29#define MAX_PATH_LENGTH      1024
30#define TR_MAX_TORRENT_COUNT 50
31
32/***********************************************************************
33 * tr_init
34 ***********************************************************************
35 * Initializes a libtransmission instance. Returns a obscure handle to
36 * be passed to all functions below.
37 **********************************************************************/
38typedef struct tr_handle_s tr_handle_t;
39
40tr_handle_t * tr_init();
41
42/***********************************************************************
43 * tr_getPrefsDirectory
44 ***********************************************************************
45 * Returns the full path to the directory used by libtransmission to
46 * store the resume files. The string belongs to libtransmission, do
47 * not free it.
48 **********************************************************************/
49char * tr_getPrefsDirectory( tr_handle_t * );
50
51/***********************************************************************
52 * tr_setBindPort
53 ***********************************************************************
54 * Sets a "start" port: everytime we start a torrent, we try to bind
55 * this port, then the next one and so on until we are successful.
56 **********************************************************************/
57void tr_setBindPort( tr_handle_t *, int );
58
59/***********************************************************************
60 * tr_setUploadLimit
61 ***********************************************************************
62 * Sets the total upload rate limit in KB/s
63 **********************************************************************/
64void tr_setUploadLimit( tr_handle_t *, int );
65
66/***********************************************************************
67 * tr_torrentRates
68 ***********************************************************************
69 * Gets the total download and upload rates
70 **********************************************************************/
71void tr_torrentRates( tr_handle_t *, float *, float * );
72
73/***********************************************************************
74 * tr_getFinished
75 ***********************************************************************
76 * Tests to see if torrent is finished
77 **********************************************************************/
78int tr_getFinished( tr_handle_t *, int );
79
80/***********************************************************************
81 * tr_setFinished
82 ***********************************************************************
83 * Sets the boolean value finished in the torrent back to false
84 **********************************************************************/
85void tr_setFinished( tr_handle_t *, int, int );
86
87/***********************************************************************
88 * tr_torrentInit
89 ***********************************************************************
90 * Opens and parses torrent file at 'path'. If the file exists and is a
91 * valid torrent file, returns 0 and adds it to the list of torrents
92 * (but doesn't start it). Returns a non-zero value otherwise.
93 **********************************************************************/
94int tr_torrentInit( tr_handle_t *, const char * path );
95
96/***********************************************************************
97 * tr_torrentScrape
98 ***********************************************************************
99 * Asks the tracker for the count of seeders and leechers. Returns 0
100 * and fills 's' and 'l' if successful. Otherwise returns 1 if the
101 * tracker doesn't support the scrape protocol, is unreachable or
102 * replied with some error. tr_torrentScrape may block up to 20 seconds
103 * before returning.
104 **********************************************************************/
105int tr_torrentScrape( tr_handle_t *, int, int * s, int * l );
106
107/***********************************************************************
108 * tr_torrentStart
109 ***********************************************************************
110 * Starts downloading. The download is launched in a seperate thread,
111 * therefore tr_torrentStart returns immediately.
112 **********************************************************************/
113void   tr_torrentSetFolder( tr_handle_t *, int, const char * );
114char * tr_torrentGetFolder( tr_handle_t *, int );
115void   tr_torrentStart( tr_handle_t *, int );
116
117/***********************************************************************
118 * tr_torrentStop
119 ***********************************************************************
120 * Stops downloading and notices the tracker that we are leaving. The
121 * thread keeps running while doing so.
122 * The thread will eventually be joined, either:
123 * - by tr_torrentStat when the tracker has been successfully noticed,
124 * - by tr_torrentStat if the tracker could not be noticed within 60s,
125 * - by tr_torrentClose if you choose to remove the torrent without
126 *   waiting any further.
127 **********************************************************************/
128void tr_torrentStop( tr_handle_t *, int );
129
130/***********************************************************************
131 * tr_torrentStat
132 ***********************************************************************
133 * Allocates an array of tr_stat_t structures, containing information
134 * about the current status of all open torrents (see the contents
135 * of tr_stat_s below). Returns the count of open torrents and sets
136 * (*s) to the address of the array, or NULL if no torrent is open.
137 * In the former case, the array belongs to the caller who is
138 * responsible of freeing it.
139 * The interface should call this function every 0.5 second or so in
140 * order to update itself.
141 **********************************************************************/
142typedef struct tr_stat_s tr_stat_t;
143
144int tr_torrentCount( tr_handle_t * h );
145int tr_torrentStat( tr_handle_t *, tr_stat_t ** s );
146
147/***********************************************************************
148 * tr_torrentClose
149 ***********************************************************************
150 * Frees memory allocated by tr_torrentInit. If the torrent was running,
151 * you must call tr_torrentStop() before closing it.
152 **********************************************************************/
153void tr_torrentClose( tr_handle_t *, int );
154
155/***********************************************************************
156 * tr_close
157 ***********************************************************************
158 * Frees memory allocated by tr_init.
159 **********************************************************************/
160void tr_close( tr_handle_t * );
161
162
163/***********************************************************************
164 * tr_stat_s
165 **********************************************************************/
166typedef struct tr_file_s
167{
168    uint64_t length;                /* Length of the file, in bytes */
169    char     name[MAX_PATH_LENGTH]; /* Path to the file */
170}
171tr_file_t;
172
173typedef struct tr_info_s
174{
175    /* Path to torrent */
176    char        torrent[MAX_PATH_LENGTH];
177
178    /* General info */
179    uint8_t     hash[SHA_DIGEST_LENGTH];
180    char        name[MAX_PATH_LENGTH];
181
182    /* Tracker info */
183    char        trackerAddress[256];
184    int         trackerPort;
185    char        trackerAnnounce[MAX_PATH_LENGTH];
186
187    /* Pieces info */
188    int         pieceSize;
189    int         pieceCount;
190    uint64_t    totalSize;
191    uint8_t   * pieces;
192
193    /* Files info */
194    int         fileCount;
195    tr_file_t * files;
196}
197tr_info_t;
198
199struct tr_stat_s
200{
201    tr_info_t   info;
202
203#define TR_STATUS_CHECK    0x001 /* Checking files */
204#define TR_STATUS_DOWNLOAD 0x002 /* Downloading */
205#define TR_STATUS_SEED     0x004 /* Seeding */
206#define TR_STATUS_STOPPING 0x008 /* Sending 'stopped' to the tracker */
207#define TR_STATUS_STOPPED  0x010 /* Sent 'stopped' but thread still
208                                    running (for internal use only) */
209#define TR_STATUS_PAUSE    0x020 /* Paused */
210#define TR_TRACKER_ERROR   0x100
211    int         status;
212    char        error[128];
213
214    float       progress;
215    float       rateDownload;
216    float       rateUpload;
217    int         eta;
218    int         peersTotal;
219    int         peersUploading;
220    int         peersDownloading;
221    char        pieces[120];
222    int                 seeders;
223        int                     leechers;
224
225    uint64_t    downloaded;
226    uint64_t    uploaded;
227
228    char      * folder;
229};
230
231#ifdef __TRANSMISSION__
232#  include "internal.h"
233#endif
234
235#endif
Note: See TracBrowser for help on using the repository browser.