<?php
/** @package verysimple::DB::DataDriver */

/**
 * IDataDriver is an interface that is used by Phreeze::DataAdapter
 * to communicate with a database storage engine.  Any server
 * that can implement these methods will be usable with 
 * Phreeze.
 *
 * @package    verysimple::DB::DataDriver
 * @author     VerySimple Inc. <noreply@verysimple.com>
 * @copyright  1997-2010 VerySimple Inc.
 * @license    http://www.gnu.org/licenses/lgpl.html  LGPL
 * @version    1.0
 */
interface IDataDriver
{
	/**
	 * returns a string to identify the type of server
	 * supported in the implemenation
	 * 
	 * @return string
	 */
	function GetServerType();
	
	/**
	 * Return true if the given connection is live
	 * @param $connection
	 * @return bool;
	 */
	function Ping($connection);
	
	/**
	 * Open the database with the given parameters.  the implementation
	 * must provide a protocol for the connection string that is relevant
	 * 
	 * @param string $connectionstring
	 * @param string $database
	 * @param string $username
	 * @param string $password
	 * @param string $charset the charset that will be used for the connection (example 'utf8')
	 * @param string $bootstrap SQL that will be executed when the connection is first opened (example 'SET SQL_BIG_SELECTS=1')
	 * @return connection
	 */
	function Open($connectionstring,$database,$username,$password,$charset='',$bootstrap='');
	
	/**
	 * Close the given connection reference
	 * @param connection
	 */
	function Close($connection);
	
	/**
	 * Execute a SQL query that is expected to return a resultset
	 * @param connection
	 * @param string sql query
	 * @return resultset
	 */
	function Query($connection,$sql);

	/**
	 * Executes a SQL query that does not return a resultset, such as an insert or update
	 * 
	 * @param connection
	 * @param string sql statement
	 * @return int number of affected records
	 */
	function Execute($connection,$sql);
	
	/**
	 * Moves the database curser forward and returns the current row as an associative array
	 * When no more data is available, null is returned
	 * 
	 * @param connection
	 * @param resultset
	 * @return array (or null)
	 */
	function Fetch($connection,$rs);

	/**
	 * Returns the last auto-insert id that was inserted for the
	 * given connection reference
	 * 
	 * @param connection
	 */
	function GetLastInsertId($connection);
	
	/**
	 * Returns the last error message that the server encountered
	 * for the given connection reference
	 * 
	 * @param connection
	 */
	function GetLastError($connection);
	
	/**
	 * Releases the resources for the given resultset.
	 * 
	 * @param connection
	 * @param resultset
	 */
	function Release($connection,$rs);
	
	/**
	 * Remove or escape any characters that will cause a SQL statment
	 * to crash or cause an injection exploit
	 * @param string value to escape
	 * @return string value after escaping
	 */
	function Escape($val);
	
	/**
	 * Return a stringified version of $val ready to insert with appropriate quoting and escaping
	 * This method must handle at a minimum: strings, numbers, NULL and ISqlFunction objects
	 * @param variant value to insert/update/query
	 * @return string value ready to use in a SQL statement quoted and escaped if necessary
	 */
	function GetQuotedSql($val);
	
	/**
	 * Returns an array of tablenames for the given database
	 * @param mixed connection reference
	 * @param string name of the database
	 * @param $ommitEmptyTables (default false) set to true and tables with no data will be ommitted
	 */
 	function GetTableNames($connection, $dbname, $ommitEmptyTables = false) ;
	
	/**
	 * Optimize, clean, defrag or whatever action is relevant for the database server
	 * @param mixes connection reference
	 * @param string name of table to optimize
	 */
 	function Optimize($connection,$table);
}

?>