Main object for generating queries to MusicBrainz. More...

Public Types
enum	tQueryResult { eQuery_Success = 0, eQuery_ConnectionError, eQuery_Timeout, eQuery_AuthenticationError, eQuery_FetchError, eQuery_RequestError, eQuery_ResourceNotFound }
	Enumerated type for query status. More...
typedef std::map< std::string, std::string >	tParamMap

Public Member Functions
	CQuery (const std::string &UserAgent, const std::string &Server="musicbrainz.org", int Port=80)
	Constructor for MusicBrainz::CQuery object.
	~CQuery ()
void	SetUserName (const std::string &UserName)
	Set the user name.
void	SetPassword (const std::string &Password)
	Set the password.
void	SetProxyHost (const std::string &ProxyHost)
	Set proxy server.
void	SetProxyPort (int ProxyPort)
	Set proxy server port.
void	SetProxyUserName (const std::string &ProxyUserName)
	Set proxy server user name.
void	SetProxyPassword (const std::string &ProxyPassword)
	Set proxy server password.
CReleaseList	LookupDiscID (const std::string &DiscID)
	Return a list of releases that match a disc ID.
CRelease	LookupRelease (const std::string &ReleaseID)
	Return full information about a release.
CMetadata	Query (const std::string &Entity, const std::string &ID="", const std::string &Resource="", const tParamMap &Params=tParamMap())
	Perform a generic query.
bool	AddCollectionEntries (const std::string &CollectionID, const std::vector< std::string > &Entries)
	Add entries to the specified collection.
bool	DeleteCollectionEntries (const std::string &CollectionID, const std::vector< std::string > &Entries)
	Delete entries from the specified collection.
CQuery::tQueryResult	LastResult () const
	Return result of the last query.
int	LastHTTPCode () const
	Return HTTP code of the last query.
std::string	LastErrorMessage () const
	Return error message from the last query.
std::string	Version () const
	Return the library version.

Detailed Description

This object is the main entry point for the library, generating a query to the MusicBrainz service, and parsing the results. The resultant objects can be used to retrieve information appropriate to the query.

For information on generating queries and the expected responses, see the documentation for the web service.

For information on search syntax, see the documentation for search syntax.

Note It is the responsibility of the caller to validate any pointers returned from the library. It is valid for a pointer to be NULL if the information was not present in the response from the MusicBrainz service.

Note The ownership of any pointers returned from the C++ interfaces remains with the library. The caller should not delete any pointer returned from the library. Users of the C library should take note of the documentation for each individual function in mb5_c.h

Member Typedef Documentation

typedef std::map<std::string,std::string> MusicBrainz5::CQuery::tParamMap

Member Enumeration Documentation

enum MusicBrainz5::CQuery::tQueryResult

Enumerated type for query status

Enumerator:

eQuery_Success
eQuery_ConnectionError
eQuery_Timeout
eQuery_AuthenticationError
eQuery_FetchError
eQuery_RequestError
eQuery_ResourceNotFound

Constructor & Destructor Documentation

MusicBrainz5::CQuery::CQuery	(	const std::string &	UserAgent,
		const std::string &	Server = `"musicbrainz.org"`,
		int	Port = `80`
	)

This is the constructor for the MusicBrainz::CQuery object.

Parameters

UserAgent	User agent to use in any queries and submissions. The format is `"application-version"`, where application is your application's name and version is a version number which may not contain a '-' character.
Server	Server to be used (defaults to musicbrainz.org if not specified)
Port	Port to use (defaults to 80 if not specified)

MusicBrainz5::CQuery::~CQuery ( )

Member Function Documentation

bool MusicBrainz5::CQuery::AddCollectionEntries	(	const std::string &	CollectionID,
		const std::vector< std::string > &	Entries
	)

Add a list of releases to the specified collection.

Parameters

CollectionID	The MusicBrainz ID of the collection to add entries to
Entries	List of MusicBrainz Release IDs to add to the collection

Returns: true if successful, false otherwise

Exceptions

CConnectionError	An error occurred connecting to the web server
CTimeoutError	A timeout occurred when connecting to the web server
CAuthenticationError	An authentication error occurred
CFetchError	An error occurred fetching data
CRequestError	The request was invalid
CResourceNotFoundError	The requested resource was not found

bool MusicBrainz5::CQuery::DeleteCollectionEntries	(	const std::string &	CollectionID,
		const std::vector< std::string > &	Entries
	)

Delete a list of releases from the specified collection.

Parameters

CollectionID	The MusicBrainz ID of the collection to delete entries from
Entries	List of MusicBrainz Release IDs to delete from the collection

Returns: true if successful, false otherwise

Exceptions

CConnectionError	An error occurred connecting to the web server
CTimeoutError	A timeout occurred when connecting to the web server
CAuthenticationError	An authentication error occurred
CFetchError	An error occurred fetching data
CRequestError	The request was invalid
CResourceNotFoundError	The requested resource was not found

std::string MusicBrainz5::CQuery::LastErrorMessage ( ) const

Return the error message from the last query

Returns: Error message from last query

int MusicBrainz5::CQuery::LastHTTPCode ( ) const

Return the HTTP code of the last query

Returns: HTTP code of last query

CQuery::tQueryResult MusicBrainz5::CQuery::LastResult ( ) const

Return the result of the last query

Returns: Result of last query

CReleaseList MusicBrainz5::CQuery::LookupDiscID ( const std::string & DiscID )

Request a list of releases matching the specified disc ID.

Parameters

DiscID Disc id to match

Returns: MusicBrainz5::CReleaseList

CRelease MusicBrainz5::CQuery::LookupRelease ( const std::string & ReleaseID )

Query for detailed information about a specific release

Parameters

ReleaseID MusicBrainz release ID to lookup

Returns: MusicBrainz::CRelease object

Exceptions

CConnectionError	An error occurred connecting to the web server
CTimeoutError	A timeout occurred when connecting to the web server
CAuthenticationError	An authentication error occurred
CFetchError	An error occurred fetching data
CRequestError	The request was invalid
CResourceNotFoundError	The requested resource was not found

CMetadata MusicBrainz5::CQuery::Query	(	const std::string &	Entity,
		const std::string &	ID = `""`,
		const std::string &	Resource = `""`,
		const tParamMap &	Params = `tParamMap()`
	)

Performs a generic query.

Assuming the following parameters are set:

"param1" = "p1v1 p1v2 p1v3"
"param2" = "p2v1"
"param3" = ""

The following query will be generated:

/ws/2/Entity/ID/Resource?param1=p1v1+p1v2+p1v3&param2=p2v1&param3

If any of ID or Resource are empty, those components will be omitted from the query.

For full details about generating queries, see the web service documentation.

Parameters

Entity	Entity to lookup (e.g. artist, release, discid)
ID	The MusicBrainz ID of the entity
Resource	The resource (currently only used for collections)
Params	Map of parameters to add to the query (e.g. inc)

Returns: MusicBrainz5::CMetadata object

Exceptions

CConnectionError	An error occurred connecting to the web server
CTimeoutError	A timeout occurred when connecting to the web server
CAuthenticationError	An authentication error occurred
CFetchError	An error occurred fetching data
CRequestError	The request was invalid
CResourceNotFoundError	The requested resource was not found

void MusicBrainz5::CQuery::SetPassword ( const std::string & Password )

Set the password to use when authenticating to the MusicBrainz service

Parameters

Password Password to use

void MusicBrainz5::CQuery::SetProxyHost ( const std::string & ProxyHost )

Set the proxy server to use for queries. Note The http_proxy environment variable will be used to set a 'default' proxy server. Calls to this method will override any proxy settings set by the http_proxy environment variable.

Parameters

ProxyHost Proxy server to use

void MusicBrainz5::CQuery::SetProxyPassword ( const std::string & ProxyPassword )

Set the password to use when authenticating to the proxy server. Note The http_proxy environment variable will be used to set a 'default' proxy server. Calls to this method will override any proxy settings set by the http_proxy environment variable.

Parameters

ProxyPassword Proxy password to use

void MusicBrainz5::CQuery::SetProxyPort ( int ProxyPort )

Set the proxy server port to use for queries. Note The http_proxy environment variable will be used to set a 'default' proxy server. Calls to this method will override any proxy settings set by the http_proxy environment variable.

Parameters

ProxyPort Proxy port to use

void MusicBrainz5::CQuery::SetProxyUserName ( const std::string & ProxyUserName )

Set the user name to use when authenticating to the proxy server. Note The http_proxy environment variable will be used to set a 'default' proxy server. Calls to this method will override any proxy settings set by the http_proxy environment variable.

Parameters

ProxyUserName Proxy user name to use

void MusicBrainz5::CQuery::SetUserName ( const std::string & UserName )

Set the user name to use when authenticating to the MusicBrainz service

Parameters

UserName Username to use

std::string MusicBrainz5::CQuery::Version ( ) const

Return the library version

Returns: Library version

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation