diff options
Diffstat (limited to 'include/cddb/cddb_cmd.h')
| -rw-r--r-- | include/cddb/cddb_cmd.h | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/include/cddb/cddb_cmd.h b/include/cddb/cddb_cmd.h new file mode 100644 index 00000000..c5a01fef --- /dev/null +++ b/include/cddb/cddb_cmd.h @@ -0,0 +1,185 @@ +/* + $Id: cddb_cmd.h,v 1.17 2006/10/15 08:58:51 airborne Exp $ + + Copyright (C) 2003, 2004, 2005 Kris Verbeeck <airborne@advalvas.be> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library 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 + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public + License along with this library; if not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. +*/ + +#ifndef CDDB_CMD_H +#define CDDB_CMD_H 1 + +#ifdef __cplusplus + extern "C" { +#endif + + +/* --- accessing data on the CDDB server --- */ + + +/** + * Retrieve a disc record from the CDDB server. This function + * requires that the category and disc ID of the provided disc + * structure are valid. + * + * If nothing goes wrong, the function will return 1 and the error + * code will be reset to: + * - #CDDB_ERR_OK: + * If everything went as planned. + * + * If there is a problem with reading data from the CDDB server one of + * the following error codes will be set: + * - #CDDB_ERR_DATA_MISSING: + * If some required data is missing from the given disc + * structure to execute this command. + * - #CDDB_ERR_DISC_NOT_FOUND: + * If the requested disc is not known by the CDDB server. + * - #CDDB_ERR_SERVER_ERROR: + * If the server encountered an error while trying to process your + * request. + * - #CDDB_ERR_UNKNOWN: + * If the server specified an unknown response code. Please + * report this as a libcddb bug. + * + * When there are problems with the connection to the CDDB server one + * of the following error codes will be set: + * - #CDDB_ERR_UNKNOWN_HOST_NAME: + * If there was an error when resolving the host name of the CDDB + * server. + * - #CDDB_ERR_CONNECT: + * If a connection to the CDDB server could not be established. + * This can be due to incorrect data about the location of the + * server (host name, port). + * - #CDDB_ERR_NOT_CONNECTED: + * If something when wrong in the process and you got + * disconnected. Retrying might succeed (but no guarantees). + * - #CDDB_ERR_PERMISSION_DENIED: + * If the server is up and running but denied the connection. + * This can occur when the server is too highly loaded or the + * handshake information (user name, ...) is considered to be + * invalid. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + * @return 1 on succes, 0 on failure + */ +int cddb_read(cddb_conn_t *c, cddb_disc_t *disc); + +/** + * Query the CDDB database for a list of possible disc matches. This + * function requires that the disc ID and disc length of the provided + * disc structure are valid. The disc should also contain a number of + * tracks and for each track its frame offset on the CD should be + * valid. + * + * If there are multiple matches then only the first one will be + * returned by this function. For other matches you will have to use + * the #cddb_query_next function. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + * + * @return The number of matches found or -1 on error. + */ +int cddb_query(cddb_conn_t *c, cddb_disc_t *disc); + +/** + * Returns the next match in a CDDB query result set. This function + * should be used in conjunction with #cddb_query. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + */ +int cddb_query_next(cddb_conn_t *c, cddb_disc_t *disc); + +/** + * Perform a text search in the CDDB database. Instead of actually + * needing information about a real disc like in #cddb_query this + * function accept a string that is used for searching the database. + * + * If there are multiple matches then only the first one will be + * returned by this function. For other matches you will have to use + * the #cddb_search_next function. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + * @param str The search string + * + * @return The number of matches found or -1 on error. + */ +int cddb_search(cddb_conn_t *c, cddb_disc_t *disc, const char *str); + +/** + * Returns the next match in a CDDB search result set. This function + * should be used in conjunction with #cddb_search. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + */ +int cddb_search_next(cddb_conn_t *c, cddb_disc_t *disc); + +/** + * Perform a text search in the CDDB database. It uses the album + * command implemented on the freedb2.org servers. Either the album + * title or artist's name should be filled in, in the disc structure. + * + * If there are multiple matches then only the first one will be + * returned by this function. For other matches you will have to use + * the #cddb_album_next function. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + * + * @return The number of matches found or -1 on error. + */ +int cddb_album(cddb_conn_t *c, cddb_disc_t *disc); + +/** + * Returns the next match in a CDDB album result set. This function + * should be used in conjunction with #cddb_album. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + */ +int cddb_album_next(cddb_conn_t *c, cddb_disc_t *disc); + +/** + * Submit a new or updated disc to the CDDB database. This function + * requires that the disc ID, length, category, artist and title of + * the provided disc structure are valid. The disc should also + * contain a number of tracks and for each track its frame offset on + * the CD and title should be valid. + * + * @param c The CDDB connection structure. + * @param disc A non-null CDDB disc structure. + */ +int cddb_write(cddb_conn_t *c, cddb_disc_t *disc); + +/** + * Query the currently configured server for a list of mirrors. + * Accessing the list of mirror sites is done with the iterator + * functions #cddb_first_site and #cddb_next_site. + * + * @param c The CDDB connection structure. + */ +int cddb_sites(cddb_conn_t *c); + + +#ifdef __cplusplus + } +#endif + +#endif /* CDDB_CMD_H */ |