/* --------------------------------------------------------------------------
libmusicbrainz5 - Client library to access MusicBrainz
Copyright (C) 2012 Andrew Hawkins
This file is part of libmusicbrainz5.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
libmusicbrainz5 is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU General Public License
along with this library. If not, see <http://www.gnu.org/licenses/>.
$Id$
----------------------------------------------------------------------------*/
/**
* Create a new instance of #Mb5Query.
*
* @see MusicBrainz5::CQuery::CQuery
*
* @param UserAgent User agent to be passed to submissions
* @param Server Server to use, pass null to use the default server
* @param Port Port to use, pass 0 to use the default port
*
* @return The newly created #Mb5Query object. This object <b>must</b> be deleted once
* finished with.
*/
Mb5Query mb5_query_new(const char *UserAgent, const char *Server, int Port);
/**
* Set the username for authenticating to MusicBrainz
*
* @see MusicBrainz5::CQuery::SetUserName
*
* @param Query #Mb5Query object
* @param UserName Username to use
*/
void mb5_query_set_username(Mb5Query Query, const char *UserName);
/**
* Set the password for authenticating to MusicBrainz
*
* @see MusicBrainz5::CQuery::SetPassword
*
* @param Query #Mb5Query object
* @param Password Password to use
*/
void mb5_query_set_password(Mb5Query Query, const char *Password);
/**
* Set the proxy server
*
* @see MusicBrainz5::CQuery::SetProxyHost
*
* @param Query #Mb5Query object
* @param ProxyHost Proxy server to use
*/
void mb5_query_set_proxyhost(Mb5Query Query, const char *ProxyHost);
/**
* Set the port to use on the proxy server
*
* @see MusicBrainz5::CQuery::SetProxyPort
*
* @param Query #Mb5Query object
* @param ProxyPort Port to use on proxy server
*/
void mb5_query_set_proxyport(Mb5Query Query, int ProxyPort);
/**
* Set the username to use to authenticate to the proxy server
*
* @see MusicBrainz5::CQuery::SetProxyUserName
*
* @param Query #Mb5Query object
* @param ProxyUserName User name to use
*/
void mb5_query_set_proxyusername(Mb5Query Query, const char *ProxyUserName);
/**
* Set the password to use to authenticate to the proxy server
*
* @see MusicBrainz5::CQuery::SetProxyPassword
*
* @param Query #Mb5Query object
* @param ProxyPassword Password to use
*/
void mb5_query_set_proxypassword(Mb5Query Query, const char *ProxyPassword);
/**
* Return a list of releases that match the specified Disc ID
*
* @see MusicBrainz5::CQuery::LookupDiscID
*
* @param Query #Mb5Query object
* @param DiscID DiscID to lookup
*
* @return A #Mb5ReleaseList object. This object <b>must</b> be deleted once
* finished with.
*/
Mb5ReleaseList mb5_query_lookup_discid(Mb5Query Query, const char *DiscID);
/**
* Return full information about a specific release
*
* @see MusicBrainz5::CQuery::LookupRelease
*
* @param Query #Mb5Query object
* @param Release Release to return information for
*
* @return A #Mb5Release object. This object <b>must</b> be deleted once
* finished with.
*/
Mb5Release mb5_query_lookup_release(Mb5Query Query, const char *Release);
/**
* Perform a generic query
*
* @see MusicBrainz5::CQuery::Query
*
* @param Query #Mb5Query object
* @param Entity The entity to query
* @param ID The ID to query
* @param Resource The resource to query
* @param NumParams The number of parameters in the following arrays
* @param ParamNames Array of strings containing parameter names
* @param ParamValues Array of space seperated parameter values
*
* @return A #Mb5Metadata object. This object <b>must</b> be deleted once
* finished with.
*/
Mb5Metadata mb5_query_query(Mb5Query Query, const char *Entity, const char *ID, const char *Resource, int NumParams, char **ParamNames, char **ParamValues);
/**
* Add a list of releases to a collection
*
* @see MusicBrainz5::CQuery::AddCollectionEntries
*
* @param Query #Mb5Query object
* @param Collection ID of collection to add releases to
* @param NumEntries The number of entries to add
* @param Entries Array of strings of release IDs to add
*
* @return 0 on failure, 1 on success
*/
unsigned char mb5_query_add_collection_entries(Mb5Query Query, const char *Collection, int NumEntries, const char **Entries);
/**
* Delete a list of releases from a collection
*
* @see MusicBrainz5::CQuery::AddCollectionEntries
*
* @param Query #Mb5Query object
* @param Collection ID of collection to delete releases from
* @param NumEntries The number of entries to delete
* @param Entries Array of strings of release IDs to delete
*
* @return 0 on failure, 1 on success
*/
unsigned char mb5_query_delete_collection_entries(Mb5Query Query, const char *Collection, int NumEntries, const char **Entries);
/**
* @see MusicBrainz5::CQuery::tQueryResult
*/
typedef enum
{
eQuery_Success=0,
eQuery_ConnectionError,
eQuery_Timeout,
eQuery_AuthenticationError,
eQuery_FetchError,
eQuery_RequestError,
eQuery_ResourceNotFound
} tQueryResult;
/**
* @see MusicBrainz5::CQuery::LastResult
*
* @param Query #Mb5Query object
*
* @return Last query result code
*/
tQueryResult mb5_query_get_lastresult(Mb5Query Query);