MusicBrainz4::CQuery Class Reference

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

List of all members.

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 mb4_c.h


Member Typedef Documentation

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

Member Enumeration Documentation

Enumerated type for query status

Enumerator:
eQuery_Success 
eQuery_ConnectionError 
eQuery_Timeout 
eQuery_AuthenticationError 
eQuery_FetchError 
eQuery_RequestError 
eQuery_ResourceNotFound 

Constructor & Destructor Documentation

MusicBrainz4::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)
MusicBrainz4::CQuery::~CQuery (  ) 

Member Function Documentation

bool MusicBrainz4::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 MusicBrainz4::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 MusicBrainz4::CQuery::LastErrorMessage (  )  const

Return the error message from the last query

Returns:
Error message from last query
int MusicBrainz4::CQuery::LastHTTPCode (  )  const

Return the HTTP code of the last query

Returns:
HTTP code of last query
CQuery::tQueryResult MusicBrainz4::CQuery::LastResult (  )  const

Return the result of the last query

Returns:
Result of last query
CReleaseList MusicBrainz4::CQuery::LookupDiscID ( const std::string &  DiscID  ) 

Request a list of releases matching the specified disc ID.

Parameters:
DiscID Disc id to match
Returns:
MusicBrainz4::CReleaseList
CRelease MusicBrainz4::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 MusicBrainz4::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:
MusicBrainz4::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 MusicBrainz4::CQuery::SetPassword ( const std::string &  Password  ) 

Set the password to use when authenticating to the MusicBrainz service

Parameters:
Password Password to use
void MusicBrainz4::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 MusicBrainz4::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 MusicBrainz4::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 MusicBrainz4::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 MusicBrainz4::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 MusicBrainz4::CQuery::Version (  )  const

Return the library version

Returns:
Library version
Generated on Tue May 15 18:06:21 2012 for libmusicbrainz4 by  doxygen 1.6.3