libmusicbrainz3
3.0.2
|
A simple interface to the MusicBrainz web service. More...
Public Member Functions | |
Query (IWebService *ws=NULL, const std::string &clientId=std::string()) | |
Constructor. More... | |
virtual | ~Query () |
Destructor. More... | |
Artist * | getArtistById (const std::string &id, const ArtistIncludes *include=NULL) |
Returns an artist. More... | |
Release * | getReleaseById (const std::string &id, const ReleaseIncludes *include=NULL) |
Returns a release. More... | |
Track * | getTrackById (const std::string &id, const TrackIncludes *include=NULL) |
Returns a track. More... | |
User * | getUserByName (const std::string &name) |
Returns information about a MusicBrainz user. More... | |
ArtistResultList | getArtists (const ArtistFilter *filter) |
Returns artists matching given criteria. More... | |
ReleaseResultList | getReleases (const ReleaseFilter *filter) |
Returns releases matching given criteria. More... | |
TrackResultList | getTracks (const TrackFilter *filter) |
Returns tracks matching given criteria. More... | |
void | submitPuids (const std::map< std::string, std::string > &tracks2puids) |
Submit track to PUID mappings. More... | |
Protected Member Functions | |
Metadata * | getFromWebService (const std::string &entity, const std::string &id, const IIncludes *include=NULL, const IFilter *filter=NULL) |
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.
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.
ws | a pointer to subclass instance of IWebService, or NULL |
clientId | a string containing the application's ID |
|
virtual |
Destructor.
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.
id | a string containing the artist's ID |
include | an ArtistIncludes instance |
NULL
NULL
, the caller takes responsibility for deleting it when it is no longer needed.ConnectionError | couldn't connect to server |
RequestError | invalid ID or include tags |
ResourceNotFoundError | artist doesn't exist |
ResponseError | server returned invalid data |
ArtistResultList MusicBrainz::Query::getArtists | ( | const ArtistFilter * | filter | ) |
Returns artists matching given criteria.
filter | a pointer to ArtistFilter object |
ConnectionError | couldn't connect to server |
RequestError | invalid ID or include tags |
ResponseError | server returned invalid data |
|
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.
id | a string containing the release's ID |
include | an ReleaseIncludes instance |
NULL
NULL
, the caller takes responsibility for deleting it when it is no longer needed.ConnectionError | couldn't connect to server |
RequestError | invalid ID or include tags |
ResourceNotFoundError | artist doesn't exist |
ResponseError | server returned invalid data |
ReleaseResultList MusicBrainz::Query::getReleases | ( | const ReleaseFilter * | filter | ) |
Returns releases matching given criteria.
filter | a pointer to ReleaseFilter object |
ConnectionError | couldn't connect to server |
RequestError | invalid ID or include tags |
ResponseError | server returned invalid data |
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.
id | a string containing the track's ID |
include | an TrackIncludes instance |
NULL
NULL
, the caller takes responsibility for deleting it when it is no longer needed.ConnectionError | couldn't connect to server |
RequestError | invalid ID or include tags |
ResourceNotFoundError | artist doesn't exist |
ResponseError | server returned invalid data |
TrackResultList MusicBrainz::Query::getTracks | ( | const TrackFilter * | filter | ) |
Returns tracks matching given criteria.
filter | a pointer to TrackFilter object |
ConnectionError | couldn't connect to server |
RequestError | invalid ID or include tags |
ResponseError | server returned invalid data |
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.
name | a string containing the user's name |
NULL
NULL
, the caller takes responsibility for deleting it when it is no longer needed.ConnectionError | couldn't connect to server |
RequestError | invalid ID or include tags |
ResourceNotFoundError | artist doesn't exist |
ResponseError | server returned invalid data |
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.
tracks2puids | a map mapping track IDs to PUIDs |
ConnectionError | couldn't connect to server |
RequestError | invalid track- or PUIDs |
AuthenticationError | invalid user name and/or password |