<?

/* Database Interface
 * 
 * Interacts with whatever database the election is using
 */

interface Database
{

	/* __construct($database_server, $username, $password)
	 *
	 * Constructor that takes the database server name, user name and password
	 * Likely that the constructor connects to the database, but that is an
	 * implementational concern
	 *
	 * In: String $database_server - The name of the database server
	 * In: String $username - The user name to use when connecting to the server
	 * In: String $password - The password to use when connecting to the server
	 */
	 
	public function __construct($database_server, $username, $password);
	
	/* createDatabase($new_database_name)
	 *
	 * Creates a new database of the given name on the database server
	 * 
	 * In: String $new_database_name - The name of the database to create
	 * Return: boolean - the result of the query to create the database.  False
	 *   on a failure, and true on success.
	 */
	 
	public function createDatabase($new_database_name);
	
	/* createTable($tablename, $field_names) 
	 *
	 * Creates a new table in the currently selected database
	 *
	 * See Also: selectDatabase($database)
	 *
	 * In: String $tablename - The name of the table to create
	 * In: Array $field_names - The details of the fields to create 
	 *     in the table.  Each entry in the array will be an array with the
	 *     following keys and values:
	 *  		Key: 'field_name' Value: String - the name of the field
	 *  		Key: 'type' Value: String - the type of the field (see mysql
	 *  		      commands for more information about allowed types)
	 *  		Key: 'initial_value' Value: String - the initial value of the
	 *  			  entry in the database (NOT NULL for example)
	 *  		Key: 'special' Value: String - any special things
	 *  			  associated with the entry (AUTO_INCREMENT for example).  If
	 *  			  there are multiple additional things associated with the entry
	 *  			  they will be in one string, seperated by spaces.  This is
	 *  			  optional!
	 * Return: boolean - the result of the query to create the database.  False
	 *   on a failure, and true on success.
	 */
	 
	public function createTable($tablename, $field_names);
	
	/* insertIntoTable($tablename, $field_names_and_values_array)
	 *
	 * This function inserts the given information into a row in the table of
	 * name $tablename, in the currently selected database
	 *
	 * See Also: selectDatabase($database)
	 *
	 * In: String $tablename - The name of the table to insert data into
	 * In: Array $field_names_values_array - An array in which the keys are the
	 *     names of the fields for the given table, and the corresponding value of
	 *     each key is the value to insert into the table for that key.
	 * Return: boolean - the result of the query to create the database.  False
	 *   on a failure, and true on success.
	 */
	 
	public function insertIntoTable($tablename, $field_names_and_values_array);
	
	/* getInformationFromTable($tablename, $what_to_select)
	 *
	 * Selects information based on $what_to_select, from $tablename in the currently
	 * selected database. 
	 *
	 * See Also: selectDatabase($database)
	 *
	 * In: String $tablename - The name of the table to get information from
	 * In: String $what_to_select - The string telling the database what to get
	 *     out of the table ('*', 'username, userinfo')
	 * Return: resource - on success (contains the result from the query)
	 *         boolean - returns false if the query is unsuccessful
	 */
	 
	public function getInformationFromTable($tablename, $what_to_select);

	/* selectDatabase($database)
	 *
	 * This function selects the database passed in as an argument to be the
	 * currently active database
	 *
	 * In: $database - The name of the database to select
	 * Return: boolean - the result of the query to create the database.  False
	 *   on a failure, and true on success.
	 */
	 
	public function selectDatabase($database);

	/* getTableColumnNames($tablename)
	 * 
	 * This function returns an array of the names of the fields/columns in the
	 * given table in the selected database
	 *
	 * See Also: selectDatabase($database)
	 *
	 * In: String $tablename - the name of the table in which to get the column
	 *     list
	 * Return: resource - on succes (contains the result from the query)
	 *         boolean - returns false on failure
	 */

	 public function getTableColumnNames($tablename);
}

?>