// Copyright (c) 1999-2000  David Muse
// See the file COPYING for more information.

#ifndef SQLRCLIENT_H
#define SQLRCLIENT_H

#include <client.h>

#include <private/row.h>
#include <private/column.h>
#include <private/field.h>

class sqlrclient : public client {
	public:
			sqlrclient(char *server, int port, char *socket,
						char *user, char *password,
						int retrytime, int tries);
				// Initiates a connection to "server" on "port"
				// or to the unix "socket" on the local machine
				// and authenticates with "user" and "password".
				// Failed connections will be retried for 
				// "tries" times on interval "retrytime"
				// or on for a default number of times on
				// a default interval if left unspecified.

				// If the "socket" parameter is neither 
				// NULL nor "" then an attempt will be made to 
				// connect through it before attempting to 
				// connect to "server" on "port".  If it is 
				// NULL or "" then no attempt will be made to 
				// connect through the socket.
			~sqlrclient();
				// Disconnects and terminates the session if
				// it hasn't been terminated already.

		int	sendQuery(char *query);
				// sends "query" and gets a return set
		int	sendFinalQuery(char *query);
				// sends "query", gets a return set and ends 
				// the session
		int	sendFileQuery(char *path, char *filename, ...);
				// Sends the query in file "path"/"filename" 
				// with substitutions and gets a return set.
				// 
				// Variables in the query of syntax $(variable) 
				// are substituted with the specified values.
				// Enclose ='$(variable)' statements in the
				// where clause with []'s as in:
				//    column[='$(variable)]
				// to substitute "is NULL" in place of empty
				// values.
				//
				// To specify replacement values for variables,
				// use the method as follows:
				//
				// sendFileQuery(path,filename,
				//	variable_name_array1,
				//		replacement_value_array1,
				//	variable_name_array2,
				//		replacement_value_array2,
				//	NULL,
				//	variable_name1,
				//		replacement_value1,
				//	variable_name2,
				//		replacement_value2,
				//	NULL);
				// 
				// Any number of array and individual value
				// replacements may be specified.
		int	sendFinalFileQuery(char *path, char *filename, ...);
				// sends the query in file "path"/"filename" 
				// with substitutions, gets a return set and 
				// ends the session
		int	sendCachedQuery(char **cachefilename, int ttl, 
					char *query);
				// Sends "query" and gets a return set.  The 
				// return set is cached and "cachefilename" 
				// is allocated and set to the cache filename.
		int	sendCachedFinalQuery(char **cachefilename, int ttl, 
					char *query);
				// Sends "query", gets a return set and ends 
				// the session.  The return set is cached and 
				// "cachefilename" is allocated and set to the 
				// cache filename.
		int	sendCachedFileQuery(char **cachefilename, int ttl, 
					char *path, char *filename, ...);
				// Sends the query in file "path"/"filename" and
				// gets a return set.  The return set is 
				// cached and "cachefilename" is allocated and 
				// set to the cache filename.
		int	sendCachedFinalFileQuery(char **cachefilename, int ttl, 
					char *path, char *filename, ...);
				// Sends the query in file "path"/"filename" 
				// with substitutions, gets a return set and 
				// ends the session.  The return set is cached 
				// and "cachefilename" is allocated and set to 
				// the cache filename.
		int	openCachedResultSet(char *filename);
				// Opens a cached result set as if a query that
				// would have generated it had been executed.
				// Returns 1 on success and 0 on failure.


		int	endSession();
				// terminates the session
		int	suspendSession();
				// disconnects this client from the current
				// session but leaves the session open so 
				// that another client can connect to it 
				// using resumeSession()
		int	resumeSession(int port, char *socket);
				// Resumes a session previously left open 
				// using suspendSession().
				// Returns 1 on success and 0 on failure.
		int	getConnectionPort();
				// Returns the inet port that the client is 
				// communicating over. This parameter may be 
				// passed to another client for use in
				// the resumeSession() command.
		char	*getConnectionSocket();
				// Returns the unix socket that the client is 
				// communicating over. This parameter may be 
				// passed to another client for use in
				// the resumeSession() command.

		int	colCount();
				// returns the number of columns in the current
				// return set
		int	rowCount();
				// returns the number of rows in the current 
				// return set
		char	*errorMessage();
				// If a query failed and generated an error, the
				// error message is available here.  If the 
				// query succeeded then this method returns a 
				// NULL.

		char	*getField(int row, int col);
		char	*getField(int row, char *col);
				// returns a pointer to the value of the 
				// specified row and column

		char	**getRow(int row);
				// returns a null terminated array of the 
				// values of the specified row
		char	**getColumnNames();
				// returns a null terminated array of the 
				// column names of the current return set

		char	*getColumnName(int col);
				// returns the name of the specified column
		char	*getColumnType(int col);
		char	*getColumnType(char *col);
				// returns the type of the specified column
		int	getColumnLength(int col);
		int	getColumnLength(char *col);
				// returns the length of the specified column.
		int	getLongest(int col);
		int	getLongest(char *col);
				// returns the length of the longest field
				// in the specified column.

		void	debugOn();
				// Causes verbose debugging information to be 
				// sent to standard output.  Another way to do 
				// this is to start a query with "-- debug\n".
		void	debugOff();
				// turns debugging off
		int	getDebug();
				// returns 0 if debugging is off and 1 if 
				// debugging is on

	private:

		#include <private/sqlrclient.h>
};

#endif