<?php
/*
     DatabaseHandler.php, provides an abstract interface to implement database
                          specific functions in a universal way.
     Copyright (C) 2004 Arend van Beelen, Auton Rijnsburg

     This program is free software; you can redistribute it and/or modify it
     under the terms of the GNU General Public License as published by the Free
     Software Foundation; either version 2 of the License, or (at your option)
     any later version.

     This program 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 General Public License for
     more details.

     You should have received a copy of the GNU General Public License along
     with this program; if not, write to the Free Software Foundation, Inc.,
     59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

     For any questions, comments or whatever, you may mail me at: hide@address.com
*/

/**
 * @brief Provides an abstract interface to implement database specific functions in a universal way.
 *
 * This class is used by the Database class to give access to multiple types of
 * databases.
 *
 * When implementing your own database handler, you should call your class like
 * <code>{$type}_DatabaseHandler</code> and save it in a file with the same
 * name (with <code>.php</code> extension) in the
 * <code>plugins/DatabaseHandlers</code> directory. The database type then
 * becomes available to the Database class.
 */
interface DatabaseHandler
{
	/**
	 * Connects to a database.
	 *
	 * @param server   The server on which the database is running. This can be an
	 *                 IP address or a hostname.
	 * @param database The name of the actual database to select on the server
	 *                 when connected.
	 * @param username Username used to authenticate to the database server.
	 * @param password The user's password to authenticate to the database server.
	 * @return @p true if the connection is successful, @p false otherwise.
	 */
	public function connect($server, $database, $username, $password);

	/**
	 * Disconnects from the database.
	 */
	public function disconnect();

	/**
	 * Returns the type of database interface implemented by the database handler.
	 *
	 * @return The type of database, for example 'MySQL'.
	 */
	public function type();

	/**
	 * Returns the server to which we are connected.
	 *
	 * @return The server on which the database is running. This can be an
	 *         IP address or a hostname.
	 */
	public function server();

	/**
	 * Returns the selected database on the server.
	 *
	 * @return The name of the actual database selected on the server.
	 */
	public function database();

	/**
	 * Returns the username that was used for authentication.
	 *
	 * @return Username used to authenticate to the database server.
	 */
	public function username();

	/**
	 * Executes the specified SQL query on the database.
	 *
	 * @param sqlQuery The query to execute.
	 * @return @p true if the query was successfully executed, @p false otherwise.
	 */
	public function query($sqlQuery);

	/**
	 * Returns the number of rows of the last executed query.
	 *
	 * @return The number of rows of the last query.
	 */
	public function numberOfRows();

	/**
	 * Returns the number of affected rows of the last executed query.
	 *
	 * @return The number of affected rows of the last query.
	 */
	public function numberOfAffectedRows();

	/**
	 * Results whether the last query generated any results.
	 *
	 * @return @p true if the last query generated results, @p false otherwise.
	 */
	public function hasResults();

	/**
	 * Results whether the last query had any affected rows.
	 *
	 * @return @p true if the last query had affected rows, @p false otherwise.
	 */
	public function hasAffectedRows();

	/**
	 * Returns a result from the last query.
	 *
	 * @param row   The selected row to get the result from.
	 * @param field The field in this row to return.
	 * @return The value of the selected field in the selected row.
	 */
	public function result($row, $field);

	/**
	 * Returns results as an array.
	 *
	 * @return An array containing results from the last query.
	 */
	public function resultArray();

	/**
	 * Returns results as an object.
	 *
	 * @return An object containing results from the last query.
	 */
	public function resultObject();

	/**
	 * Resets the results from the last query to the beginning.
	 */
	public function resetResults();

	/**
	 * Returns the ID generated from the last INSERT operation.
	 */
	public function insertId();

	/**
	 * Returns the last generated error. Errors can be generated because a query()
	 * call fails.
	 *
	 * @return A string containing the last generated error.
	 */
	public function error();
}

?>