1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
/*
$Id: cddb_site.h,v 1.3 2005/06/15 16:08:28 airborne Exp $
Copyright (C) 2005 Kris Verbeeck <airborne@advalvas.be>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
#ifndef CDDB_SITE_H
#define CDDB_SITE_H 1
#ifdef __cplusplus
extern "C" {
#endif
#include "cddb/cddb_error.h"
/* --- type and structure definitions */
/**
* Enumeration defining the CDDB protocol supported by a specific
* site.
*/
typedef enum {
PROTO_UNKNOWN = 0, /**< Unknown protocol */
PROTO_CDDBP, /**< FreeDB custom protocol */
PROTO_HTTP /**< Command tunneling over HTTP */
} cddb_protocol_t;
/**
* The CDDB site structure. Contains all information about one
* particular CDDB server.
*/
typedef struct cddb_site_s cddb_site_t;
/* --- construction / destruction */
/**
* Creates a new CDDB site structure.
*
* @return The CDDB site structure or NULL if memory allocation failed.
*/
cddb_site_t *cddb_site_new(void);
/**
* Free all resources associated with the given CDDB site structure.
*
* @param site The CDDB site structure.
*/
cddb_error_t cddb_site_destroy(cddb_site_t *site);
/**
* Creates a clone of the given site.
*
* @param site The CDDB site structure.
*/
cddb_site_t *cddb_site_clone(cddb_site_t *site);
/* --- setters / getters --- */
/**
* Get the site's address.
*
* @param site The CDDB site structure.
* @param address The address of the server upon returning.
* @param port The port of the server upon returning.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_get_address(const cddb_site_t *site,
const char **address, unsigned int *port);
/**
* Set the site's address. A copy of the address string is made. So the caller
* should free any memory associated with the input parameter.
*
* @param site The CDDB site structure.
* @param address The address of the server.
* @param port The port of the server.
* @return Error code: CDDB_ERR_OK, CDDB_ERR_INVALID or CDDB_ERR_OUT_OF_MEMORY.
*/
cddb_error_t cddb_site_set_address(cddb_site_t *site,
const char *address, unsigned int port);
/**
* Get the protocol used by the site.
*
* @see cddb_protocol_t
*
* @param site The CDDB site structure.
* @return The protocol.
*/
cddb_protocol_t cddb_site_get_protocol(const cddb_site_t *site);
/**
* Set the protocol used by the site.
*
* @see cddb_protocol_t
*
* @param site The CDDB site structure.
* @param proto The protocol.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_set_protocol(cddb_site_t *site, cddb_protocol_t proto);
/**
* Get the query path in case the HTTP protocol is used.
*
* @param site The CDDB site structure.
* @param path The query path upon returning.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_get_query_path(const cddb_site_t *site,
const char **path);
/**
* Set the query path in case the HTTP protocol is used. A copy of the path
* string is made. So the caller should free any memory associated with the
* input parameter.
*
* @param site The CDDB site structure.
* @param path The query path. A value of NULL deletes the current path.
* @return Error code: CDDB_ERR_OK, CDDB_ERR_INVALID or CDDB_ERR_OUT_OF_MEMORY.
*/
cddb_error_t cddb_site_set_query_path(cddb_site_t *site, const char *path);
/**
* Get the submit path in case the HTTP protocol is used.
*
* @param site The CDDB site structure.
* @param path The submit path upon returning.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_get_submit_path(const cddb_site_t *site,
const char **path);
/**
* Set the submit path in case the HTTP protocol is used. A copy of the path
* string is made. So the caller should free any memory associated with the
* input parameter.
*
* @param site The CDDB site structure.
* @param path The query path. A value of NULL deletes the current path.
* @return Error code: CDDB_ERR_OK, CDDB_ERR_INVALID or CDDB_ERR_OUT_OF_MEMORY.
*/
cddb_error_t cddb_site_set_submit_path(cddb_site_t *site, const char *path);
/**
* Get the site's location.
*
* @param site The CDDB site structure.
* @param latitude Will contain the server's latitude upon returning.
* A positive number is used for the northern
* hemisphere, a negative one for the southern
* hemisphere.
* @param longitude Will contain the server's longitude upon returning.
* A positive number is used for the eastern
* hemisphere, a negative one for the western
* hemisphere.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_get_location(const cddb_site_t *site,
float *latitude, float *longitude);
/**
* Set the site's location.
*
* @param site The CDDB site structure.
* @param latitude The server's latitude. Use a positive number for the
* northern hemisphere, a negative one for the southern
* hemisphere.
* @param longitude The server's longitude. Use a positive number for the
* eastern hemisphere, a negative one for the western
* hemisphere.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_set_location(cddb_site_t *site,
float latitude, float longitude);
/**
* Get a description of the site.
*
* @param site The CDDB site structure.
* @param desc The description upon returning.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_get_description(const cddb_site_t *site,
const char **desc);
/**
* Set a description for the site. A copy of the description string is made.
* So the caller should free any memory associated with the input parameter.
*
* @param site The CDDB site structure.
* @param desc The description. A value of NULL deletes the current
* description.
* @return Error code: CDDB_ERR_OK, CDDB_ERR_INVALID or CDDB_ERR_OUT_OF_MEMORY.
*/
cddb_error_t cddb_site_set_description(cddb_site_t *site, const char *desc);
/* --- miscellaneous */
/**
* Parses one line of data as returned by the sites command and
* populates the given structure.
*
* @param site The CDDB site structure.
* @param line The result line.
* @return True in case of success or false on failure.
*/
int cddb_site_parse(cddb_site_t *site, const char *line);
/**
* Prints information about the site on stdout. This is just a
* debugging routine to display the structure's content.
*
* @param site The CDDB site structure.
* @return Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.
*/
cddb_error_t cddb_site_print(const cddb_site_t *site);
#ifdef __cplusplus
}
#endif
#endif /* CDDB_SITE_H */
|
