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
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:
-
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:
-
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
Return the result of the last query
- Returns:
- Result of last query
CReleaseList MusicBrainz4::CQuery::LookupDiscID |
( |
const std::string & |
DiscID |
) |
|
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:
-
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¶m2=p2v1¶m3
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:
-
void MusicBrainz4::CQuery::SetPassword |
( |
const std::string & |
Password |
) |
|
Set the password to use when authenticating to the MusicBrainz service
- Parameters:
-
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:
-
std::string MusicBrainz4::CQuery::Version |
( |
|
) |
const |
Return the library version
- Returns:
- Library version