/* $Id: cddb_cmd.h,v 1.17 2006/10/15 08:58:51 airborne Exp $ Copyright (C) 2003, 2004, 2005 Kris Verbeeck 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 */