source: trunk/libtransmission/transmission.h @ 2

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

Update 2005-11-01

File size: 8.8 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_torrentInit
75 ***********************************************************************
76 * Opens and parses torrent file at 'path'. If the file exists and is a
77 * valid torrent file, returns 0 and adds it to the list of torrents
78 * (but doesn't start it). Returns a non-zero value otherwise.
79 **********************************************************************/
80int tr_torrentInit( tr_handle_t *, const char * path );
81
82/***********************************************************************
83 * tr_torrentScrape
84 ***********************************************************************
85 * Asks the tracker for the count of seeders and leechers. Returns 0
86 * and fills 's' and 'l' if successful. Otherwise returns 1 if the
87 * tracker doesn't support the scrape protocol, is unreachable or
88 * replied with some error. tr_torrentScrape may block up to 20 seconds
89 * before returning.
90 **********************************************************************/
91int tr_torrentScrape( tr_handle_t *, int, int * s, int * l );
92
93/***********************************************************************
94 * tr_torrentStart
95 ***********************************************************************
96 * Starts downloading. The download is launched in a seperate thread,
97 * therefore tr_torrentStart returns immediately.
98 **********************************************************************/
99void   tr_torrentSetFolder( tr_handle_t *, int, const char * );
100char * tr_torrentGetFolder( tr_handle_t *, int );
101void   tr_torrentStart( tr_handle_t *, int );
102
103/***********************************************************************
104 * tr_torrentStop
105 ***********************************************************************
106 * Stops downloading and notices the tracker that we are leaving. The
107 * thread keeps running while doing so.
108 * The thread will eventually be joined, either:
109 * - by tr_torrentStat when the tracker has been successfully noticed,
110 * - by tr_torrentStat if the tracker could not be noticed within 60s,
111 * - by tr_torrentClose if you choose to remove the torrent without
112 *   waiting any further.
113 **********************************************************************/
114void tr_torrentStop( tr_handle_t *, int );
115
116/***********************************************************************
117 * tr_torrentStat
118 ***********************************************************************
119 * Allocates an array of tr_stat_t structures, containing information
120 * about the current status of all open torrents (see the contents
121 * of tr_stat_s below). Returns the count of open torrents and sets
122 * (*s) to the address of the array, or NULL if no torrent is open.
123 * In the former case, the array belongs to the caller who is
124 * responsible of freeing it.
125 * The interface should call this function every 0.5 second or so in
126 * order to update itself.
127 **********************************************************************/
128typedef struct tr_stat_s tr_stat_t;
129
130int tr_torrentCount( tr_handle_t * h );
131int tr_torrentStat( tr_handle_t *, tr_stat_t ** s );
132
133/***********************************************************************
134 * tr_torrentClose
135 ***********************************************************************
136 * Frees memory allocated by tr_torrentInit. If the torrent was running,
137 * you must call tr_torrentStop() before closing it.
138 **********************************************************************/
139void tr_torrentClose( tr_handle_t *, int );
140
141/***********************************************************************
142 * tr_close
143 ***********************************************************************
144 * Frees memory allocated by tr_init.
145 **********************************************************************/
146void tr_close( tr_handle_t * );
147
148
149/***********************************************************************
150 * tr_stat_s
151 **********************************************************************/
152typedef struct tr_file_s
153{
154    uint64_t length;                /* Length of the file, in bytes */
155    char     name[MAX_PATH_LENGTH]; /* Path to the file */
156}
157tr_file_t;
158
159typedef struct tr_info_s
160{
161    /* Path to torrent */
162    char        torrent[MAX_PATH_LENGTH];
163
164    /* General info */
165    uint8_t     hash[SHA_DIGEST_LENGTH];
166    char        name[MAX_PATH_LENGTH];
167
168    /* Tracker info */
169    char        trackerAddress[256];
170    int         trackerPort;
171    char        trackerAnnounce[MAX_PATH_LENGTH];
172
173    /* Pieces info */
174    int         pieceSize;
175    int         pieceCount;
176    uint64_t    totalSize;
177    uint8_t   * pieces;
178
179    /* Files info */
180    int         fileCount;
181    tr_file_t * files;
182}
183tr_info_t;
184
185struct tr_stat_s
186{
187    tr_info_t   info;
188
189#define TR_STATUS_CHECK    0x001 /* Checking files */
190#define TR_STATUS_DOWNLOAD 0x002 /* Downloading */
191#define TR_STATUS_SEED     0x004 /* Seeding */
192#define TR_STATUS_STOPPING 0x008 /* Sending 'stopped' to the tracker */
193#define TR_STATUS_STOPPED  0x010 /* Sent 'stopped' but thread still
194                                    running (for internal use only) */
195#define TR_STATUS_PAUSE    0x020 /* Paused */
196#define TR_TRACKER_ERROR   0x100
197    int         status;
198    char        error[128];
199
200    float       progress;
201    float       rateDownload;
202    float       rateUpload;
203    int         eta;
204    int         peersTotal;
205    int         peersUploading;
206    int         peersDownloading;
207    char        pieces[120];
208
209    uint64_t    downloaded;
210    uint64_t    uploaded;
211
212    char      * folder;
213};
214
215#ifdef __TRANSMISSION__
216#  include "internal.h"
217#endif
218
219#endif
Note: See TracBrowser for help on using the repository browser.