1
/* --------------------------------------------------------------------------
3
libmusicbrainz4 - Client library to access MusicBrainz
5
Copyright (C) 2011 Andrew Hawkins
7
This file is part of libmusicbrainz4.
9
This library is free software; you can redistribute it and/or
10
modify it under the terms of v2 of the GNU Lesser General Public
11
License as published by the Free Software Foundation.
13
libmusicbrainz4 is distributed in the hope that it will be useful,
14
but WITHOUT ANY WARRANTY; without even the implied warranty of
15
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16
Lesser General Public License for more details.
18
You should have received a copy of the GNU General Public License
19
along with this library. If not, see <http://www.gnu.org/licenses/>.
21
$Id: Query.h 13266 2011-08-25 12:56:47Z adhawkins $
23
----------------------------------------------------------------------------*/
25
#ifndef _MUSICBRAINZ4_QUERY_H
26
#define _MUSICBRAINZ4_QUERY_H
28
#include "musicbrainz4/ReleaseList.h"
29
#include "musicbrainz4/Metadata.h"
31
#include "musicbrainz4/xmlParser.h"
38
* @mainpage libmusicbrainz4
40
* This is the documentation for libmusicbrainz4, a library for retrieving data from
41
* the <a target="_blank" href="http://musicbrainz.org">MusicBrainz</a> service.
43
* The main entry point to the library is the MusicBrainz4::CQuery object.
45
* For details of the C interface, see the documentation for the file mb4_c.h.
47
* Please report any issues with this library at
48
* <a target="_blank" href="http://tickets.musicbrainz.org/">http://tickets.musicbrainz.org/</a>.
50
* A brief example showing how to lookup a list of releases matching a disc id
53
MusicBrainz4::CQuery Query("cdlookupexample-1.0");
57
MusicBrainz4::CMetadata Metadata=Query.Query("discid",DiscID);
58
if (Metadata.Disc() && Metadata.Disc()->ReleaseList())
60
MusicBrainz4::CReleaseList *ReleaseList=Metadata.Disc()->ReleaseList();
62
std::cout << "Found " << ReleaseList->NumItems() << " release(s)" << std::endl;
64
for (int count=0;count<ReleaseList->NumItems();count++)
66
MusicBrainz4::CRelease *Release=ReleaseList->Item(count);
68
std::cout << "Basic release: " << std::endl << *Release << std::endl;
70
//The releases returned from LookupDiscID don't contain full information
72
MusicBrainz4::CQuery::tParamMap Params;
73
Params["inc"]="artists labels recordings release-groups url-rels discids artist-credits";
75
Metadata=Query.Query("release",Release.ID(),"",Params);
76
if (Metadata.Release())
78
MusicBrainz4::CRelease *FullRelease=Metadata.Release();
80
std::cout << *FullRelease << std::endl;
86
catch (MusicBrainz4::CConnectionError& Error)
88
std::cout << "Connection Exception: '" << Error.what() << "'" << std::endl;
89
std::cout << "LastResult: " << Query.LastResult() << std::endl;
90
std::cout << "LastHTTPCode: " << Query.LastHTTPCode() << std::endl;
91
std::cout << "LastErrorMessage: " << Query.LastErrorMessage() << std::endl;
94
catch (MusicBrainz4::CTimeoutError& Error)
96
std::cout << "Timeout Exception: '" << Error.what() << "'" << std::endl;
97
std::cout << "LastResult: " << Query.LastResult() << std::endl;
98
std::cout << "LastHTTPCode: " << Query.LastHTTPCode() << std::endl;
99
std::cout << "LastErrorMessage: " << Query.LastErrorMessage() << std::endl;
102
catch (MusicBrainz4::CAuthenticationError& Error)
104
std::cout << "Authentication Exception: '" << Error.what() << "'" << std::endl;
105
std::cout << "LastResult: " << Query.LastResult() << std::endl;
106
std::cout << "LastHTTPCode: " << Query.LastHTTPCode() << std::endl;
107
std::cout << "LastErrorMessage: " << Query.LastErrorMessage() << std::endl;
110
catch (MusicBrainz4::CFetchError& Error)
112
std::cout << "Fetch Exception: '" << Error.what() << "'" << std::endl;
113
std::cout << "LastResult: " << Query.LastResult() << std::endl;
114
std::cout << "LastHTTPCode: " << Query.LastHTTPCode() << std::endl;
115
std::cout << "LastErrorMessage: " << Query.LastErrorMessage() << std::endl;
118
catch (MusicBrainz4::CRequestError& Error)
120
std::cout << "Request Exception: '" << Error.what() << "'" << std::endl;
121
std::cout << "LastResult: " << Query.LastResult() << std::endl;
122
std::cout << "LastHTTPCode: " << Query.LastHTTPCode() << std::endl;
123
std::cout << "LastErrorMessage: " << Query.LastErrorMessage() << std::endl;
126
catch (MusicBrainz4::CResourceNotFoundError& Error)
128
std::cout << "ResourceNotFound Exception: '" << Error.what() << "'" << std::endl;
129
std::cout << "LastResult: " << Query.LastResult() << std::endl;
130
std::cout << "LastHTTPCode: " << Query.LastHTTPCode() << std::endl;
131
std::cout << "LastErrorMessage: " << Query.LastErrorMessage() << std::endl;
136
namespace MusicBrainz4
141
* @brief Main object for generating queries to MusicBrainz
143
* This object is the main entry point for the library, generating a query to the
144
* MusicBrainz service, and parsing the results. The resultant objects can be used
145
* to retrieve information appropriate to the query.
147
* For information on generating queries and the expected responses, see the
148
* documentation for the
149
* <a target="_blank" href="http://musicbrainz.org/doc/XML_Web_Service/Version_2">web service</a>.
151
* For information on search syntax, see the documentation for
152
* <a target="_blank" href="http://wiki.musicbrainz.org/Text_Search_Syntax">search syntax</a>.
154
* @b Note It is the responsibility of the caller to validate any pointers returned
155
* from the library. It is valid for a pointer to be NULL if the information was not
156
* present in the response from the MusicBrainz service.
158
* @b Note The ownership of any pointers returned from the C++ interfaces remains
159
* with the library. The caller should not delete any pointer returned from the
160
* library. Users of the C library should take note of the documentation for each
161
* individual function in mb4_c.h
166
typedef std::map<std::string,std::string> tParamMap;
169
* @brief Enumerated type for query status
171
* Enumerated type for query status
176
eQuery_ConnectionError,
178
eQuery_AuthenticationError,
181
eQuery_ResourceNotFound
185
* @brief Constructor for MusicBrainz::CQuery object
187
* This is the constructor for the MusicBrainz::CQuery object.
189
* @param UserAgent User agent to use in any queries and submissions. The format
190
* is @c "application-version", where application is your application's name
191
* and version is a version number which may not contain a '-' character.
192
* @param Server Server to be used (defaults to musicbrainz.org if not specified)
193
* @param Port Port to use (defaults to 80 if not specified)
197
CQuery(const std::string& UserAgent, const std::string& Server="musicbrainz.org", int Port=80);
202
* @brief Set the user name
204
* Set the user name to use when authenticating to the MusicBrainz service
206
* @param UserName Username to use
209
void SetUserName(const std::string& UserName);
212
* @brief Set the password
214
* Set the password to use when authenticating to the MusicBrainz service
216
* @param Password Password to use
219
void SetPassword(const std::string& Password);
222
* @brief Set proxy server
224
* Set the proxy server to use for queries. @b Note The http_proxy environment variable
225
* will be used to set a 'default' proxy server. Calls to this method will override any
226
* proxy settings set by the http_proxy environment variable.
228
* @param ProxyHost Proxy server to use
231
void SetProxyHost(const std::string& ProxyHost);
234
* @brief Set proxy server port
236
* Set the proxy server port to use for queries. @b Note The http_proxy environment variable
237
* will be used to set a 'default' proxy server. Calls to this method will override any
238
* proxy settings set by the http_proxy environment variable.
240
* @param ProxyPort Proxy port to use
243
void SetProxyPort(int ProxyPort);
246
* @brief Set proxy server user name
248
* Set the user name to use when authenticating to the proxy server. @b Note The http_proxy
249
* environment variable will be used to set a 'default' proxy server. Calls to this method
250
* will override any proxy settings set by the http_proxy environment variable.
252
* @param ProxyUserName Proxy user name to use
255
void SetProxyUserName(const std::string& ProxyUserName);
258
* @brief Set proxy server password
260
* Set the password to use when authenticating to the proxy server. @b Note The http_proxy
261
* environment variable will be used to set a 'default' proxy server. Calls to this method
262
* will override any proxy settings set by the http_proxy environment variable.
264
* @param ProxyPassword Proxy password to use
267
void SetProxyPassword(const std::string& ProxyPassword);
270
* @brief Return a list of releases that match a disc ID
272
* Request a list of releases matching the specified disc ID.
274
* @param DiscID Disc id to match
276
* @return MusicBrainz4::CReleaseList
279
CReleaseList LookupDiscID(const std::string& DiscID);
282
* @brief Return full information about a release
284
* Query for detailed information about a specific release
286
* @param ReleaseID MusicBrainz release ID to lookup
288
* @return MusicBrainz::CRelease object
290
* @throw CConnectionError An error occurred connecting to the web server
291
* @throw CTimeoutError A timeout occurred when connecting to the web server
292
* @throw CAuthenticationError An authentication error occurred
293
* @throw CFetchError An error occurred fetching data
294
* @throw CRequestError The request was invalid
295
* @throw CResourceNotFoundError The requested resource was not found
298
CRelease LookupRelease(const std::string& ReleaseID);
301
* @brief Perform a generic query
303
* Performs a generic query.
305
* Assuming the following parameters are set:
307
* "param1" = "p1v1 p1v2 p1v3"<br>
308
* "param2" = "p2v1"<br>
311
* The following query will be generated:
313
* /ws/2/Entity/ID/Resource?param1=p1v1+p1v2+p1v3¶m2=p2v1¶m3
315
* If any of ID or Resource are empty, those components will be omitted from the query.
317
* For full details about generating queries, see the
318
* <a target="_blank" href="http://musicbrainz.org/doc/XML_Web_Service/Version_2">web service</a>
321
* @param Entity Entity to lookup (e.g. artist, release, discid)
322
* @param ID The MusicBrainz ID of the entity
323
* @param Resource The resource (currently only used for collections)
324
* @param Params Map of parameters to add to the query (e.g. inc)
326
* @return MusicBrainz4::CMetadata object
328
* @throw CConnectionError An error occurred connecting to the web server
329
* @throw CTimeoutError A timeout occurred when connecting to the web server
330
* @throw CAuthenticationError An authentication error occurred
331
* @throw CFetchError An error occurred fetching data
332
* @throw CRequestError The request was invalid
333
* @throw CResourceNotFoundError The requested resource was not found
336
CMetadata Query(const std::string& Entity,const std::string& ID="",const std::string& Resource="",const tParamMap& Params=tParamMap());
339
* @brief Add entries to the specified collection
341
* Add a list of releases to the specified collection.
343
* @param CollectionID The MusicBrainz ID of the collection to add entries to
344
* @param Entries List of MusicBrainz Release IDs to add to the collection
346
* @return true if successful, false otherwise
348
* @throw CConnectionError An error occurred connecting to the web server
349
* @throw CTimeoutError A timeout occurred when connecting to the web server
350
* @throw CAuthenticationError An authentication error occurred
351
* @throw CFetchError An error occurred fetching data
352
* @throw CRequestError The request was invalid
353
* @throw CResourceNotFoundError The requested resource was not found
356
bool AddCollectionEntries(const std::string& CollectionID, const std::vector<std::string>& Entries);
359
* @brief Delete entries from the specified collection
361
* Delete a list of releases from the specified collection.
363
* @param CollectionID The MusicBrainz ID of the collection to delete entries from
364
* @param Entries List of MusicBrainz Release IDs to delete from the collection
366
* @return true if successful, false otherwise
368
* @throw CConnectionError An error occurred connecting to the web server
369
* @throw CTimeoutError A timeout occurred when connecting to the web server
370
* @throw CAuthenticationError An authentication error occurred
371
* @throw CFetchError An error occurred fetching data
372
* @throw CRequestError The request was invalid
373
* @throw CResourceNotFoundError The requested resource was not found
376
bool DeleteCollectionEntries(const std::string& CollectionID, const std::vector<std::string>& Entries);
379
* @brief Return result of the last query
381
* Return the result of the last query
383
* @return Result of last query
386
CQuery::tQueryResult LastResult() const;
389
* @brief Return HTTP code of the last query
391
* Return the HTTP code of the last query
393
* @return HTTP code of last query
395
int LastHTTPCode() const;
398
* @brief Return error message from the last query
400
* Return the error message from the last query
402
* @return Error message from last query
404
std::string LastErrorMessage() const;
407
* @brief Return the library version
409
* Return the library version
411
* @return Library version
413
std::string Version() const;
416
CQueryPrivate * const m_d;
418
CMetadata PerformQuery(const std::string& Query);
419
void WaitRequest() const;
420
std::string UserAgent() const;
421
bool EditCollection(const std::string& CollectionID, const std::vector<std::string>& Entries, const std::string& Action);
422
std::string URIEscape(const std::string& URI);
423
std::string URLEncode(const std::map<std::string,std::string>& Params);
added
removed
include/musicbrainz4/Query.h
