1 | /* |
2 | * MusicBrainz -- The Internet music metadatabase |
3 | * |
4 | * Copyright (C) 2006 Lukas Lalinsky |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Lesser General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2.1 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Lesser General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Lesser General Public |
17 | * License along with this library; if not, write to the Free Software |
18 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
19 | * |
20 | * |
21 | */ |
22 | |
23 | #ifndef __MUSICBRAINZ3_RELEASE_H__ |
24 | #define __MUSICBRAINZ3_RELEASE_H__ |
25 | |
26 | #include <string> |
27 | #include <musicbrainz3/musicbrainz.h> |
28 | #include <musicbrainz3/entity.h> |
29 | #include <musicbrainz3/lists.h> |
30 | |
31 | namespace MusicBrainz |
32 | { |
33 | |
34 | class Artist; |
35 | |
36 | /** |
37 | * Represents a Release. |
38 | * |
39 | * A release within MusicBrainz is an Entity which contains Track |
40 | * objects. Releases may be of more than one type: There can be albums, |
41 | * singles, compilations, live recordings, official releases, bootlegs |
42 | * etc. |
43 | * |
44 | * @note: The current MusicBrainz server implementation supports only a |
45 | * limited set of types. |
46 | */ |
47 | class MB_API Release : public Entity |
48 | { |
49 | public: |
50 | |
51 | static const std::string TYPE_NONE; |
52 | |
53 | static const std::string TYPE_ALBUM; |
54 | static const std::string TYPE_SINGLE; |
55 | static const std::string TYPE_EP; |
56 | static const std::string TYPE_COMPILATION; |
57 | static const std::string TYPE_SOUNDTRACK; |
58 | static const std::string TYPE_SPOKENWORD; |
59 | static const std::string TYPE_INTERVIEW; |
60 | static const std::string TYPE_AUDIOBOOK; |
61 | static const std::string TYPE_LIVE; |
62 | static const std::string TYPE_REMIX; |
63 | static const std::string TYPE_OTHER; |
64 | |
65 | static const std::string TYPE_OFFICIAL; |
66 | static const std::string TYPE_PROMOTION; |
67 | static const std::string TYPE_BOOTLEG; |
68 | static const std::string TYPE_PSEUDO_RELEASE; |
69 | |
70 | /** |
71 | * Constructor. |
72 | * |
73 | * @param id a string containing an absolute URI |
74 | * @param title a string containing the title |
75 | */ |
76 | Release(const std::string &id = std::string(), |
77 | const std::string &title = std::string()); |
78 | |
79 | /** |
80 | * Destructor. |
81 | */ |
82 | ~Release(); |
83 | |
84 | /** |
85 | * Returns the track's title. |
86 | * |
87 | * The style and format of this attribute is specified by the |
88 | * style guide. |
89 | * |
90 | * @return a string containing an absolute URI |
91 | * |
92 | * @see <a href="http://musicbrainz.org/style.html">The MusicBrainz |
93 | * Style Guidelines</a> |
94 | */ |
95 | std::string getTitle() const; |
96 | |
97 | /** |
98 | * Sets the release's title. |
99 | * |
100 | * @param title: a string containing the release's title |
101 | * |
102 | * @see getTitle |
103 | */ |
104 | void setTitle(const std::string &title); |
105 | |
106 | /** |
107 | * Returns the language used in release and track titles. |
108 | * |
109 | * To represent the language, the ISO-639-2/T standard is used, |
110 | * which provides three-letter terminological language codes like |
111 | * "ENG", "DEU", "JPN", "KOR", "ZHO" or "YID". |
112 | * |
113 | * Note that this refers to release and track \e titles, not |
114 | * lyrics. |
115 | * |
116 | * @return a string containing the language code |
117 | * |
118 | * @see getLanguageName |
119 | */ |
120 | std::string getTextLanguage() const; |
121 | |
122 | /** |
123 | * Sets the language used in releaes and track titles. |
124 | * |
125 | * @param language a string containing a language code |
126 | * |
127 | * @see getTextLanguage |
128 | */ |
129 | void setTextLanguage(const std::string &language); |
130 | |
131 | /** |
132 | * Returns the script used in release and track titles. |
133 | * |
134 | * To represent the script, ISO-15924 script codes are used. |
135 | * Valid codes are, among others: "Latn", "Cyrl", "Hans", "Hebr" |
136 | * |
137 | * Note that this refers to release and track \e titles, not |
138 | * lyrics. |
139 | * |
140 | * @return: a string containing the script code |
141 | * |
142 | * @see: getScriptName |
143 | */ |
144 | std::string getTextScript() const; |
145 | |
146 | /** |
147 | * Sets the script used in releaes and track titles. |
148 | * |
149 | * @param script a string containing a script code |
150 | * |
151 | * @see getTextScript |
152 | */ |
153 | void setTextScript(const std::string &script); |
154 | |
155 | /** |
156 | * Returns the main artist of this release. |
157 | * |
158 | * @return a pointer to Artist object, or NULL |
159 | */ |
160 | Artist *getArtist(); |
161 | |
162 | /** |
163 | * Sets this release's main artist. |
164 | * |
165 | * @param artist a pointer to Artist object |
166 | */ |
167 | void setArtist(Artist *artist); |
168 | |
169 | /** |
170 | * Returns the release group of this release. |
171 | * |
172 | * @return a pointer to ReleaseGroup object, or NULL |
173 | */ |
174 | ReleaseGroup *getReleaseGroup(); |
175 | |
176 | /** |
177 | * Sets this release's group. |
178 | * |
179 | * @param releaseGroup a pointer to ReleaseGroup object |
180 | */ |
181 | void setReleaseGroup(ReleaseGroup *releaseGroup); |
182 | |
183 | /** |
184 | * Returns the Amazon shop identifier (ASIN). |
185 | * |
186 | * The ASIN is a 10-letter code (except for books) assigned |
187 | * by Amazon, which looks like 'B000002IT2' or 'B00006I4YD'. |
188 | * |
189 | * @return a string containing the ASIN |
190 | */ |
191 | std::string getAsin() const; |
192 | |
193 | /** |
194 | * Sets the Amazon shop identifier (ASIN). |
195 | * |
196 | * @param asin a string containing the ASIN |
197 | * |
198 | * @see getAsin |
199 | */ |
200 | void setAsin(const std::string &asin); |
201 | |
202 | /** |
203 | * Returns the tracks this release contains. |
204 | * |
205 | * @return a list containing pointers to Track objects |
206 | * |
207 | * @see getTracksOffset |
208 | */ |
209 | TrackList &getTracks(); |
210 | |
211 | /** |
212 | * Returns number of tracks. |
213 | * |
214 | * This is equivalent to \c getTracks().size() |
215 | * |
216 | * @return an int containing number of tracks |
217 | * |
218 | * @see getTracks |
219 | */ |
220 | int getNumTracks() const; |
221 | |
222 | /** |
223 | * Returns an track specified by index. |
224 | * |
225 | * This is equivalent to \c getTracks()[index] |
226 | * |
227 | * @warning \c index must be always lower than the result of \c getNumTracks() |
228 | * |
229 | * @return a pointer to Track instance |
230 | * |
231 | * @see getTracks |
232 | */ |
233 | Track *getTrack(int index); |
234 | |
235 | /** |
236 | * Returns the offset of the track list. |
237 | * |
238 | * This is used if the track list is incomplete (ie. the web |
239 | * service only returned part of the tracks on this release). |
240 | * Note that the offset value is zero-based, which means track |
241 | * \a 0 is the first track. |
242 | * |
243 | * @return an integer containing the offset |
244 | * |
245 | * @see getTracks |
246 | */ |
247 | int getTracksOffset() const; |
248 | |
249 | /** |
250 | * Sets the offset of the track list. |
251 | * |
252 | * @param offset an integer containing the offset |
253 | * |
254 | * @see getTracksOffset |
255 | */ |
256 | void setTracksOffset(const int offset); |
257 | |
258 | /** |
259 | * Returns the number of tracks on this release. |
260 | * |
261 | * This may or may not match with the number of elements that |
262 | * getTracks and getNumTracks returns. If the count is higher than |
263 | * the list, it indicates that the list is incomplete. |
264 | * |
265 | * @return an integer containing the count |
266 | * |
267 | * @see getTracks |
268 | */ |
269 | int getTracksCount() const; |
270 | |
271 | /** |
272 | * Sets the count of the track list. |
273 | * |
274 | * @param count an integer containing the count |
275 | * |
276 | * @see getTracksCount |
277 | */ |
278 | void setTracksCount(const int count); |
279 | |
280 | /** |
281 | * Returns the discs associated with this release. |
282 | * |
283 | * Discs are currently containers for MusicBrainz DiscIDs. |
284 | * Note that under rare circumstances (identical TOCs), a |
285 | * DiscID could be associated with more than one release. |
286 | * |
287 | * @return a list of pointers to Disc objects |
288 | * |
289 | * @todo make the returned vector \c const |
290 | */ |
291 | DiscList &getDiscs(); |
292 | |
293 | /** |
294 | * Returns number of discs. |
295 | * |
296 | * This is equivalent to \c getDiscs().size() |
297 | * |
298 | * @return an int containing number of discs |
299 | * |
300 | * @see getDiscs |
301 | */ |
302 | int getNumDiscs() const; |
303 | |
304 | /** |
305 | * Returns an disc specified by index. |
306 | * |
307 | * This is equivalent to \c getDiscs()[index] |
308 | * |
309 | * @warning \c index must be always lower than the result of \c getNumDiscs() |
310 | * |
311 | * @return a pointer to Disc instance |
312 | * |
313 | * @see getDiscs |
314 | */ |
315 | Disc *getDisc(int index); |
316 | |
317 | /** |
318 | * Returns the list of release events. |
319 | * |
320 | * A Release may contain a list of so-called release events, |
321 | * each represented using a ReleaseEvent object. Release |
322 | * evens specify where and when this release was, well, released. |
323 | * |
324 | * @return a list of pointers to ReleaseEvent objects |
325 | */ |
326 | ReleaseEventList &getReleaseEvents(); |
327 | |
328 | /** |
329 | * Returns number of release events. |
330 | * |
331 | * This is equivalent to \c getReleaseEvents().size() |
332 | * |
333 | * @return an int containing number of release events |
334 | * |
335 | * @see getReleaseEvents |
336 | */ |
337 | int getNumReleaseEvents() const; |
338 | |
339 | /** |
340 | * Returns an release event specified by index. |
341 | * |
342 | * This is equivalent to \c getReleaseevents()[index] |
343 | * |
344 | * @warning \c index must be always lower than the result of \c getNumReleaseEvents() |
345 | * |
346 | * @return a pointer to ReleaseEvent instance |
347 | * |
348 | * @see getReleaseEvents |
349 | */ |
350 | ReleaseEvent *getReleaseEvent(int index); |
351 | |
352 | /** |
353 | * Sets the list of release types. |
354 | * |
355 | * @param types a vector of strings string |
356 | */ |
357 | void setTypes(const std::vector<std::string> &types); |
358 | |
359 | /** |
360 | * Returns the list of release types. |
361 | * |
362 | * @return a vector of strings string |
363 | * |
364 | * @see getType |
365 | */ |
366 | std::vector<std::string> &getTypes(); |
367 | |
368 | /** |
369 | * Returns the number of release types. |
370 | * |
371 | * @return an int |
372 | */ |
373 | int getNumTypes() const; |
374 | |
375 | /** |
376 | * Returns the type specified by index. |
377 | * |
378 | * This is an equivalent to \c getTypes()[index] |
379 | * |
380 | * @warning \c index must be always lower than the result of \c getNumTypes() |
381 | * |
382 | * @param index index |
383 | * @return a string |
384 | * |
385 | * @see getTypes |
386 | */ |
387 | std::string getType(int index) const; |
388 | |
389 | private: |
390 | |
391 | class ReleasePrivate; |
392 | ReleasePrivate *d; |
393 | }; |
394 | |
395 | } |
396 | |
397 | #endif |
398 | |
399 | |