A simple interface to the MusicBrainz web service.
More...
List of all members.
Detailed Description
A simple interface to the MusicBrainz web service.
This is a facade which provides a simple interface to the MusicBrainz web service. It hides all the details like fetching data from a server, parsing the XML and creating an object tree. Using this class, you can request data by ID or search the collection of all resources (artists, releases, or tracks) to retrieve those matching given criteria.
- Todo:
- Add examples here.
Constructor & Destructor Documentation
MusicBrainz::Query::Query |
( |
IWebService * |
ws = NULL , |
|
|
const std::string & |
clientId = std::string() | |
|
) |
| | |
Constructor.
The ws parameter has to be a subclass of IWebService. If it isn't given, the default WebService class is used to create an IWebService instance.
If the constructor is called without arguments, an instance of WebService is used, preconfigured to use the MusicBrainz server. This should be enough for most users.
If you want to use queries which require authentication you have to pass a WebService instance where user name and password have been set.
The clientId parameter is required for data submission. The format is "application-version"
, where application
is your application's name and version
is a version number which may not contain a '-' character.
- Parameters:
-
| ws | a pointer to subclass instance of IWebService, or NULL |
| clientId | a string containing the application's ID |
virtual MusicBrainz::Query::~Query |
( |
|
) |
[virtual] |
Member Function Documentation
Artist* MusicBrainz::Query::getArtistById |
( |
const std::string & |
id, |
|
|
const ArtistIncludes * |
include = NULL | |
|
) |
| | |
Returns an artist.
If no artist with that ID can be found, include contains invalid tags or there's a server problem, an exception is raised.
- Parameters:
-
| id | a string containing the artist's ID |
| include | an ArtistIncludes instance |
- Returns:
- a pointer to Artist instance, or
NULL
- Note:
- If the returned pointer is not
NULL
, the caller takes responsibility for deleting it when it is no longer needed.
- Exceptions:
-
Returns artists matching given criteria.
- Parameters:
-
- Returns:
- a vector of pointers to ArtistResult objects
- Note:
- The caller is responsible for deleting all returned ArtistResult objects.
- Exceptions:
-
Metadata* MusicBrainz::Query::getFromWebService |
( |
const std::string & |
entity, |
|
|
const std::string & |
id, |
|
|
const IIncludes * |
include = NULL , |
|
|
const IFilter * |
filter = NULL | |
|
) |
| | [protected] |
Release* MusicBrainz::Query::getReleaseById |
( |
const std::string & |
id, |
|
|
const ReleaseIncludes * |
include = NULL | |
|
) |
| | |
Returns a release.
If no release with that ID can be found, include contains invalid tags or there's a server problem, and exception is raised.
- Parameters:
-
| id | a string containing the release's ID |
| include | an ReleaseIncludes instance |
- Returns:
- a pointer to Release instance, or
NULL
- Note:
- If the returned pointer is not
NULL
, the caller takes responsibility for deleting it when it is no longer needed.
- Exceptions:
-
Returns releases matching given criteria.
- Parameters:
-
- Returns:
- a vector of pointers to ReleaseResult objects
- Note:
- The caller is responsible for deleting all returned ReleaseResult objects.
- Exceptions:
-
Track* MusicBrainz::Query::getTrackById |
( |
const std::string & |
id, |
|
|
const TrackIncludes * |
include = NULL | |
|
) |
| | |
Returns a track.
If no track with that ID can be found, include contains invalid tags or there's a server problem, and exception is raised.
- Parameters:
-
| id | a string containing the track's ID |
| include | an TrackIncludes instance |
- Returns:
- a pointer to Track instance, or
NULL
- Note:
- If the returned pointer is not
NULL
, the caller takes responsibility for deleting it when it is no longer needed.
- Exceptions:
-
Returns tracks matching given criteria.
- Parameters:
-
- Returns:
- a vector of pointers to TrackResult objects
- Note:
- The caller is responsible for deleting all returned TrackResult objects.
- Exceptions:
-
User* MusicBrainz::Query::getUserByName |
( |
const std::string & |
name |
) |
|
Returns information about a MusicBrainz user.
You can only request user data if you know the user name and password for that account. If username and/or password are incorrect, an AuthenticationError is raised.
See the example in Query on how to supply user name and password.
- Parameters:
-
| name | a string containing the user's name |
- Returns:
- a pointer to User instance, or
NULL
- Note:
- If the returned pointer is not
NULL
, the caller takes responsibility for deleting it when it is no longer needed.
- Exceptions:
-
void MusicBrainz::Query::submitPuids |
( |
const std::map< std::string, std::string > & |
tracks2puids |
) |
|
Submit track to PUID mappings.
The tracks2puids parameter has to be a map, with the keys being MusicBrainz track IDs (either as absolute URIs or in their 36 character ASCII representation) and the values being PUIDs (ASCII, 36 characters).
Note that this method only works if a valid user name and password have been set. See the example in Query on how to supply authentication data.
- Parameters:
-
| tracks2puids | a map mapping track IDs to PUIDs |
- Exceptions:
-