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
31namespace 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