libmusicbrainz3  3.0.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
MusicBrainz::Query Class Reference

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...
 
ArtistgetArtistById (const std::string &id, const ArtistIncludes *include=NULL)
 Returns an artist. More...
 
ReleasegetReleaseById (const std::string &id, const ReleaseIncludes *include=NULL)
 Returns a release. More...
 
TrackgetTrackById (const std::string &id, const TrackIncludes *include=NULL)
 Returns a track. More...
 
UsergetUserByName (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

MetadatagetFromWebService (const std::string &entity, const std::string &id, const IIncludes *include=NULL, const IFilter *filter=NULL)
 

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
wsa pointer to subclass instance of IWebService, or NULL
clientIda string containing the application's ID
virtual MusicBrainz::Query::~Query ( )
virtual

Destructor.

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
ida string containing the artist's ID
includean 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
ConnectionErrorcouldn't connect to server
RequestErrorinvalid ID or include tags
ResourceNotFoundErrorartist doesn't exist
ResponseErrorserver returned invalid data
ArtistResultList MusicBrainz::Query::getArtists ( const ArtistFilter filter)

Returns artists matching given criteria.

Parameters
filtera pointer to ArtistFilter object
Returns
a vector of pointers to ArtistResult objects
Note
The caller is responsible for deleting all returned ArtistResult objects.
Exceptions
ConnectionErrorcouldn't connect to server
RequestErrorinvalid ID or include tags
ResponseErrorserver returned invalid data
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
ida string containing the release's ID
includean 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
ConnectionErrorcouldn't connect to server
RequestErrorinvalid ID or include tags
ResourceNotFoundErrorartist doesn't exist
ResponseErrorserver returned invalid data
ReleaseResultList MusicBrainz::Query::getReleases ( const ReleaseFilter filter)

Returns releases matching given criteria.

Parameters
filtera pointer to ReleaseFilter object
Returns
a vector of pointers to ReleaseResult objects
Note
The caller is responsible for deleting all returned ReleaseResult objects.
Exceptions
ConnectionErrorcouldn't connect to server
RequestErrorinvalid ID or include tags
ResponseErrorserver 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.

Parameters
ida string containing the track's ID
includean 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
ConnectionErrorcouldn't connect to server
RequestErrorinvalid ID or include tags
ResourceNotFoundErrorartist doesn't exist
ResponseErrorserver returned invalid data
TrackResultList MusicBrainz::Query::getTracks ( const TrackFilter filter)

Returns tracks matching given criteria.

Parameters
filtera pointer to TrackFilter object
Returns
a vector of pointers to TrackResult objects
Note
The caller is responsible for deleting all returned TrackResult objects.
Exceptions
ConnectionErrorcouldn't connect to server
RequestErrorinvalid ID or include tags
ResponseErrorserver 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.

Parameters
namea 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
ConnectionErrorcouldn't connect to server
RequestErrorinvalid ID or include tags
ResourceNotFoundErrorartist doesn't exist
ResponseErrorserver 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.

Parameters
tracks2puidsa map mapping track IDs to PUIDs
Exceptions
ConnectionErrorcouldn't connect to server
RequestErrorinvalid track- or PUIDs
AuthenticationErrorinvalid user name and/or password