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_ARTIST_H__ |
24 | #define __MUSICBRAINZ3_ARTIST_H__ |
25 | |
26 | #include <string> |
27 | #include <vector> |
28 | #include <musicbrainz3/musicbrainz.h> |
29 | #include <musicbrainz3/entity.h> |
30 | #include <musicbrainz3/lists.h> |
31 | |
32 | namespace MusicBrainz |
33 | { |
34 | |
35 | /** |
36 | * Represents an artist. |
37 | * |
38 | * Artists in MusicBrainz can have a type. Currently, this type can |
39 | * be either Person or Group for which the following URIs are assigned: |
40 | * |
41 | * - \a "http://musicbrainz.org/ns/mmd-1.0#Person" |
42 | * - \a "http://musicbrainz.org/ns/mmd-1.0#Group" |
43 | * |
44 | * Use the \a Artist::TYPE_PERSON and \a Artist::TYPE_GROUP constants for comparison. |
45 | */ |
46 | class MB_API Artist : public Entity |
47 | { |
48 | public: |
49 | |
50 | static const std::string TYPE_PERSON; |
51 | static const std::string TYPE_GROUP; |
52 | |
53 | /** |
54 | * Constructor. |
55 | * |
56 | * @param id a string containing an absolute URI |
57 | * @param type a string containing an absolute URI |
58 | * @param name a string containing the artist's name |
59 | * @param sortName a string containing the artist's sort name |
60 | */ |
61 | Artist(const std::string &id = "" , const std::string &type = "" , |
62 | const std::string &name = "" , const std::string &sortName = "" ); |
63 | |
64 | /** |
65 | * Destructor. |
66 | */ |
67 | virtual ~Artist(); |
68 | |
69 | /** |
70 | * Returns the artist's type. |
71 | * |
72 | * @return a string containing an absolute URI |
73 | */ |
74 | std::string getType() const; |
75 | |
76 | /** |
77 | * Sets the artist's type. |
78 | * |
79 | * @param type a string containing an absolute URI |
80 | */ |
81 | void setType(const std::string &type); |
82 | |
83 | /** |
84 | * Returns the artist's name. |
85 | * |
86 | * @return a string containing the artist's name, or empty string |
87 | */ |
88 | std::string getName() const; |
89 | |
90 | /** |
91 | * Sets the artist's name. |
92 | * |
93 | * @param name a string containing the artist's name |
94 | */ |
95 | void setName(const std::string &name); |
96 | |
97 | /** |
98 | * Returns the artist's sort name. |
99 | * |
100 | * <p>The sort name is the artist's name in a special format which |
101 | * is better suited for lexicographic sorting. The MusicBrainz |
102 | * style guide specifies this format.</p> |
103 | * |
104 | * @see <a href="http://musicbrainz.org/style.html">The MusicBrainz Style Guidelines</a> |
105 | */ |
106 | std::string getSortName() const; |
107 | |
108 | /** |
109 | * Sets the artist's sort name. |
110 | * |
111 | * @param sortName: a string containing the artist's sort name |
112 | * |
113 | * @see #getSortName |
114 | */ |
115 | void setSortName(const std::string &sortName); |
116 | |
117 | /** |
118 | * Returns the disambiguation attribute. |
119 | * |
120 | * This attribute may be used if there is more than one artist |
121 | * with the same name. In this case, disambiguation attributes |
122 | * are added to the artists' names to keep them apart. |
123 | * |
124 | * For example, there are at least three bands named 'Vixen'. |
125 | * Each band has a different disambiguation in the MusicBrainz |
126 | * database, like 'Hip-hop' or 'all-female rock/glam band'. |
127 | * |
128 | * @return a disambiguation string |
129 | * |
130 | * @see getUniqueName |
131 | */ |
132 | std::string getDisambiguation() const; |
133 | |
134 | /** |
135 | * Sets the disambiguation attribute. |
136 | * |
137 | * @param disambiguation a disambiguation string |
138 | * |
139 | * @see getDisambiguation, getUniqueName |
140 | */ |
141 | void setDisambiguation(const std::string &disambiguation); |
142 | |
143 | /** |
144 | * Returns a unique artist name (using disambiguation). |
145 | * |
146 | * This method returns the artist name together with the |
147 | * disambiguation attribute in parenthesis if it exists. |
148 | * Example: 'Vixen (Hip-hop)'. |
149 | * |
150 | * @return a string containing the unique name |
151 | * |
152 | * @see getDisambiguation |
153 | */ |
154 | std::string getUniqueName() const; |
155 | |
156 | /** |
157 | * Returns the birth/foundation date. |
158 | * |
159 | * The definition of the \e begin \e date depends on the artist's |
160 | * type. For persons, this is the day of birth, for groups it |
161 | * is the day the group was founded. |
162 | * |
163 | * The returned date has the format "YYYY", "YYYY-MM", or |
164 | * "YYYY-MM-DD", depending on how much detail is known. |
165 | * |
166 | * @return a string containing the date |
167 | * |
168 | * @see getType |
169 | */ |
170 | std::string getBeginDate() const; |
171 | |
172 | /** |
173 | * Sets the begin/foundation date. |
174 | * |
175 | * @param dateStr a date string |
176 | * |
177 | * @see getBeginDate |
178 | */ |
179 | void setBeginDate(const std::string &dateStr); |
180 | |
181 | /** |
182 | * Get the death/dissolving date. |
183 | * |
184 | * The definition of the \e end \e date depends on the artist's |
185 | * type. For persons, this is the day of death, for groups it |
186 | * is the day the group was dissolved. |
187 | * |
188 | * @return a string containing a date |
189 | * |
190 | * @see getBeginDate |
191 | */ |
192 | std::string getEndDate() const; |
193 | |
194 | /** |
195 | * Sets the death/dissolving date. |
196 | * |
197 | * @param dateStr a string containing a date |
198 | * |
199 | * @see: setEndDate, getBeginDate |
200 | */ |
201 | void setEndDate(const std::string &dateStr); |
202 | |
203 | /** |
204 | * Returns a list of releases from this artist. |
205 | * |
206 | * This may also include releases where this artist isn't the |
207 | * \e main artist but has just contributed one or more tracks |
208 | * (aka VA-Releases). |
209 | * |
210 | * @return: a list of pointers to Release objects |
211 | */ |
212 | ReleaseList &getReleases(); |
213 | |
214 | /** |
215 | * Returns number of releases. |
216 | * |
217 | * This is equivalent to \c getReleases().size() |
218 | * |
219 | * @return an int containing number of releases |
220 | * |
221 | * @see getReleases |
222 | */ |
223 | int getNumReleases() const; |
224 | |
225 | /** |
226 | * Returns an release specified by index. |
227 | * |
228 | * This is equivalent to \c getReleases()[index] |
229 | * |
230 | * @return a pointer to Release instance |
231 | * |
232 | * @see getReleases |
233 | */ |
234 | Release *getRelease(int index); |
235 | |
236 | /** |
237 | * Adds a release to this artist's list of releases. |
238 | * |
239 | * @param release a pointer to Release object |
240 | */ |
241 | void addRelease(Release *release); |
242 | |
243 | /** |
244 | * Returns the offset of the release list. |
245 | * |
246 | * This is used if the track list is incomplete (ie. the web |
247 | * service only returned part of the tracks on this release). |
248 | * Note that the offset value is zero-based, which means track |
249 | * \a 0 is the first track. |
250 | * |
251 | * @return an integer containing the offset |
252 | * |
253 | * @see getReleases |
254 | */ |
255 | int getReleasesOffset() const; |
256 | |
257 | /** |
258 | * Sets the offset of the release list. |
259 | * |
260 | * @param offset an integer containing the offset |
261 | * |
262 | * @see getReleasesOffset |
263 | */ |
264 | void setReleasesOffset(const int offset); |
265 | |
266 | /** |
267 | * Returns the number of existing releases. |
268 | * |
269 | * This may or may not match with the number of elements that |
270 | * getReleases and getNumReleases returns. If the count is higher than |
271 | * the list, it indicates that the list is incomplete. |
272 | * |
273 | * @return an integer containing the count |
274 | * |
275 | * @see getReleases |
276 | */ |
277 | int getReleasesCount() const; |
278 | |
279 | /** |
280 | * Sets the count of the release list. |
281 | * |
282 | * @param count an integer containing the count |
283 | * |
284 | * @see getReleasesCount |
285 | */ |
286 | void setReleasesCount(const int count); |
287 | |
288 | /** |
289 | * Returns the list of aliases for this artist. |
290 | * |
291 | * @return a list of pointers to ArtistAlias objects |
292 | */ |
293 | ArtistAliasList &getAliases(); |
294 | |
295 | /** |
296 | * Returns number of aliases. |
297 | * |
298 | * This is equivalent to \c getAliases().size() |
299 | * |
300 | * @return an int containing number of aliases |
301 | * |
302 | * @see getAliases |
303 | */ |
304 | int getNumAliases() const; |
305 | |
306 | /** |
307 | * Returns alias specified by index. |
308 | * |
309 | * This is equivalent to \c getAliases()[index] |
310 | * |
311 | * @return a pointer to ArtistAlias instance |
312 | * |
313 | * @see getAliases |
314 | */ |
315 | ArtistAlias *getAlias(int index); |
316 | |
317 | /** |
318 | * Adds an alias for this artist. |
319 | * |
320 | * @param alias a pointer to ArtistAlias object |
321 | */ |
322 | void addAlias(ArtistAlias *alias); |
323 | |
324 | private: |
325 | |
326 | class ArtistPrivate; |
327 | ArtistPrivate *d; |
328 | }; |
329 | |
330 | } |
331 | |
332 | #endif |
333 | |