// Connection.h: interface for the CConnection class.
//
//////////////////////////////////////////////////////////////////////

#if !defined(AFX_CONNECTION_H__035ED1A8_ECAE_4A7F_8CFE_44F22F9A2FDA__INCLUDED_)
#define AFX_CONNECTION_H__035ED1A8_ECAE_4A7F_8CFE_44F22F9A2FDA__INCLUDED_

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

namespace scdriver
{
	/// <summary>
	///	Supported ScimoreDB transaction isolation levels
	/// </summary>
	enum TRAN_ISOLATION_LEVEL
	{
		READ_COMMITTED	= 0, 	/// <summary>Read only committed data. This level is the default. </summary>
		READ_REPEATABLE = 1,	/// <summary>Read repeatable isolation level. The data view will not change, and the current transaction will always see the database in the state after the transaction has been started. </summary>
		SERIALIZE		= 3		/// <summary>Serialize all transactions and execute on at the time</summary>
	};

	/// <summary>
	///	Query language type
	/// </summary>
	enum CONNECTION_LANG
	{
		LANG_DQL = 0,	/// <summary>Interpet the command text as DQL statements</summary>
		LANG_SQL = 1,	/// <summary>Interpet the command text as SQL statements</summary>
	};

	/// <summary>
	///	Connection callback events
	/// </summary>
	enum CONNECTION_EVENT
	{
		CONN_BROKEN	= 1,	/// <summary>Fire when connections has been terminated.</summary>
		CONN_ALTER	= 2,	/// <summary>Fire when DB cluster configuration has been altered.</summary>
		QUERY_DONE	= 3,	/// <summary>Fire when the query has been completed, usually used when query is executed asychronuosously.</summary>
		READ_SCHEMA = 4,	/// <summary>Reserved for internal use. Do not set this event it will lead to crash!</summary>
		READ_PARAMETERS = 5 /// <summary>Read output parameter value.</summary>
	};

// forward declaration
class CConnection; 
class CRecordset;
class CFieldStream;
class CCommand;
class c_connector;

/// <summary>
///	Callback routine that will be fired when specified connection state event occurs.
/// </summary>
/// <param name="conn">Connection instance pointer that fires the event</param>
/// <param name="context">User key, specified in SetConnectionCallback function</param>
typedef void (__stdcall CONNECTION_STATE_CALLBACK) (CConnection *conn, void *context);

/// <summary>
///	Manage connection, transaction,
///	query execution and state callbacks
/// <summary>
#ifdef DELPHI
class CConnection : public CAbstractConnection
#else
class __declspec( dllexport ) CConnection  
#endif
{
public:
	CConnection();
	virtual ~CConnection();

	/// <summary>
	/// Connects with TCP to the database server. The client uses internal connection pool. It will re-use
	/// released connection or establish new one. Connection becomes release after Close() call & can be reused.
	/// </summary>
	/// <param name="host">Host name or IP address</param>
	/// <param name="port">The port, the databse is listening</param>
	/// <param name="inst_id">The parameter is used when connecting to distributed database. 
	/// All Servers in the cluster has an unique instance id that can be acquired from system metadata: 
	/// SELECT * from system.sysinstances.
	/// Default value -1, i.e. client will connect to the random server.</param>
	/// <returns>If method fails, the node_exception exception, containing the error message, will be thrown</returns>
	void Connect(const char *host,const int port, const long inst_id = -1);

	/// <summary>
	/// Connects, using named pipes protocol (shared memory), to the embedded database engine.
	/// The embedded database can be loaded into client's process as dll or started in a separate
	/// process (rundll32).
	/// </summary>
	/// <param name="embdb_id">Host name or IP address</param>
	/// <param name="in_process">True if database is loaded in host process</param>
	/// <returns>If method fails, the ServerException, containing the error message, will be thrown</returns>
	void Connect(const char *embdb_id,const bool &in_process);

	/// <summary>
	///	If connection executes asynchronuos query, you can cancel it
	/// by calling Cancel method.
	/// </summary>
	/// <returns>If method fails, the node_exception exception, containing the error message, will be thrown</returns>
	void Cancel();

	/// <summary>
	///	Close connection and release it to the poll of
	/// the available connections. If you need to query
	/// the database, call Connect() again.
	/// </summary>
	/// <returns>If method fails, the node_exception exception, containing the error message, will be thrown</returns>
	void Close();

	/// <summary>
	/// The function call will block until database
	/// responded executed query status. If database returns an error
	/// the [node_exception] exception with an error message
	/// will be thrown. Otherwise, if defined, query events/callbacks will be
	/// fired. The callback event is set with SetConnectionStateCallback
	/// function.
	/// The GetCompletionStatus(), must always be called right after
	/// CConnection: Execute, CCommand::Execute/Open  or CRecordset::Open,
	/// unless, the query is asynchronuos - in this case, call the function
	/// after completion event has been fired.
	/// </summary>
	/// <returns>If server sends back to the client the error, node_exception exception, containing the error message, will be thrown</returns>
	void GetCompletionStatus();

	/// <summary>
	/// Return number of deleted, inserted or updated rows in the current transaction scope
	/// </summary>
	__int64 GetAffectedRows();

	/// <summary>
	/// Start new transaction scope and sets AutoCommit to false. Followed data changes will be visible
	/// only by the current connection, until, Commit() is executed. Executing Rollback() will undo
	/// all changes that was made after begin current transaction. The behaviour is similiar to BEGIN TRANSACTION
	/// SQL statememnt.
	/// </summary>
	/// <param name="iso_level">Set transaction supported isolation level. The default - read committed.</param>
	/// <returns>If server sends back to the client the error, node_exception exception, containing the error message, will be thrown</returns>
	void BeginTransaction(const TRAN_ISOLATION_LEVEL iso_level = READ_COMMITTED);

	/// <summary>
	/// Abort/Rollback current transaction. The transaction must be started
	/// using BeginTransaction() function.
	/// </summary>
	/// <returns>If server sends back to the client the error, node_exception exception, containing the error message, will be thrown</returns>
	void AbortTransaction();

	/// <summary>
	/// Commit current transaction's changes. The transaction must be started
	/// using BeginTransaction() function.
	/// </summary>
	/// <returns>If server sends back to the client the error, node_exception exception, containing the error message, will be thrown</returns>
	void CommitTransaction();

	/// <summary>
	///	Execute SQL or DQL command.
	/// The command will set affected rows and receive the new values
	/// for the output parameter(s).
	/// </summary>
	/// <param name="cmd">SQL or DQL statement. By default, database interpret text as SQL, unless, SetLanguage function had set it to DQL.</param>
	/// <param name="_recv">Reserved for internal use.</param>
	/// <param name="_irecv">Reserved for internal use.</param>
	/// <returns>If server sends back to the client the error, node_exception exception with the error message, will be thrown</returns>
	void Execute(const char *cmd, byte *_recv = 0, const int _irecv = 8192);

	/// <summary>
	///	Return generated DQL statement from SQL.
	/// </summary>
	/// <param name="sql">SQL statement.</param>
	/// <param name="dql">Pointer to the buffer that receives DQL</param>
	/// <param name="idql">Size of the DQL buffer. The DQL can be maximum 8KB</param>
	/// <returns>If server sends back to the client the error, node_exception exception with the error message, will be thrown</returns>
	void ShowDQL(const char *sql,char *dql, int idql);

	/// <summary>
	/// Set query timeout value in seconds. If query being executed longer than 
	/// timeout seconds, it will be cancelled. The timeout is only used for synchronuos
	/// queries. Asynchrounuos queries can be executed with ScimoreCommand::ExecuteAsynchronous
	/// method and cancelled using ScimoreCommand::Cancel. Default value is - 0xffffffff, i.e. the query
	/// never timeouts.
	/// </summary>
	void SetTimeout(const long Seconds);

	/// <summary>
	/// Set which language to execute. ScimoreDB supports SQL and DQL. DQL is text-based execution plan and used in rare cases,
	/// for example, if SQL optimizer generates incorrect or slow DQL plan. By default, Language is SQL.
	/// </summary>
	/// <param name="tlang">CONNECTION_LANG enum value specifying the language</param>
	void SetLanguage(const CONNECTION_LANG tlang);

	/// <summary>
	///	Set callback function to be fired for the specified connection state.
	///	The callback routine must not use any DB functions, e.g. execute, read rows, etc..,
	/// it should do a quick operation like SetEvent()...
	/// NOTE: do not call GetCompletionStatus() inside any callback functions.
	/// </summary>
	/// <param name="etype">Set QUERY_DONE event, which will be fired, when
	/// asynchronuos query completed</param>
	/// <param name="pcallback">Events callback routine address</param>
	/// <param name="usercontext">User defined key/value that will be passed to callback routine.</param>
	void SetConnectionStateCallback(const CONNECTION_EVENT etype, CONNECTION_STATE_CALLBACK *pcallback, void *usercontext = 0);

	/// <summary>
	///	If you set callback routines, you need to reset them as well. 
	/// Reset it in the inside callback routines or when you done with the query.
	/// </summary>
	/// <param name="etype">Callback events type.</param>
	void ResetConnectionStateCallback(const CONNECTION_EVENT etype);

	/**************************************
	 *
	 *    function: get_class_size
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 *	return the size of the class
	 **************************************/
	static int get_class_size();

	friend class CRecordset;
	friend class CFieldStream;
	friend class CCommand;
	friend class CBulkExport;
	friend class CBulkImport;
	friend class c_connector;

protected:

	/**************************************
	 *
	 *    function: F i r e E v e n t
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 *	call users callback functions
	 **************************************/
	void FireEvent(const CONNECTION_EVENT &etype);	

	/**************************************
	 *
	 *    function: g e t _ r e t u r n 
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 **************************************/
	byte *get_return();

	/**************************************
	 *
	 *    function: g e t _ d r i v e r
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 **************************************/
	c_connector *get_driver();	

private:

	/**************************************
	 *
	 *    function: E x e c u t e S Q L
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 *	execute SQL
	 **************************************/
	void ExecuteSQL(const char *sql, const int &isql, byte *recv);

	/**************************************
	 *
	 *    function: E x e c u t e D Q L
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 *	execute DQL
	 **************************************/
	void ExecuteDQL(const char *dql, byte *recv);

	/**************************************
	 *
	 *    function: b a t c h _ s q l
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 *	split SQL into max 8kb chunk.
	 *	Batching is allowed when SQL statement
	 *	ends with ';'
	 *	Return: true - if there is more than one batch
	 *	isql - size of sql block
	 *	sql updated pointer to the next sql batch begining
	 **************************************/
	bool batch_sql(const char *cmd, char *sql,  int &isql);

	/**************************************
	 *
	 *    function: r e s e t _ t r a n _ s c o p e
	 *
	 **************************************
	 *
	 * Functional description
	 *
	 *	when auto_commit == false and transaction fails
	 *	the server will rollback all changes made
	 *	by transaction's scope. And the client does not need to call
	 *	AbortTransaction anymore.The auto_commit flag will be reset
	 *	to TRUE as well
	 **************************************/
	void reset_tran_scope();

private:
	c_connector					*m_driver;		// connection enpoint instance used to communicate with the DB servers
	__int64						m_affected_rows;// number of affected rows by current executed command
	bool						m_auto_commit;	// auto commit flag: true - each succesfully executed command will commit data, false - modified data will not be committed until implicitly call conn->CommitTransactio() 
	long						m_timeout;		// in seconds to wait for the qurty to complete
	CONNECTION_LANG				m_language;		// 1 - SQL or 0 - DQL command statement
	byte						m_recv[8192];

protected:
	int							m_irecv;

private:
	// registered callback functions for each connection
	// state change event [CONNECTION_EVENT]
	CONNECTION_STATE_CALLBACK	*m_pconn_broken;
	CONNECTION_STATE_CALLBACK	*m_pconn_alter;
	CONNECTION_STATE_CALLBACK	*m_pquery_done;
	CONNECTION_STATE_CALLBACK	*m_pread_schema;
	CONNECTION_STATE_CALLBACK	*m_pread_params;

	// user data ptr, which will be passed in callback function
	void						*m_pconn_broken_context;
	void						*m_pconn_alter_context;
	void						*m_pquery_done_context;
	void						*m_pread_schema_context;
	void						*m_pread_params_context;
};
}

#endif // !defined(AFX_CONNECTION_H__035ED1A8_ECAE_4A7F_8CFE_44F22F9A2FDA__INCLUDED_)