#ifndef _SQSQLITE_CONNECTION_HPP_
#define _SQSQLITE_CONNECTION_HPP_
// ------------------------------------------------------------------------------------------------
#include "Handle/Connection.hpp"
// ------------------------------------------------------------------------------------------------
namespace SqMod {
/* ------------------------------------------------------------------------------------------------
* Used to manage and interact with a database connection.
*/
class Connection
{
protected:
/* --------------------------------------------------------------------------------------------
* Create the database connection resource.
*/
void Create(CSStr name, Int32 flags, CSStr vfs);
private:
// --------------------------------------------------------------------------------------------
ConnRef m_Handle; // Reference to the managed connection.
protected:
/* --------------------------------------------------------------------------------------------
* Callback function for ActivateTracing()
*/
static void TraceOutput(void * ptr, CCStr sql);
/* --------------------------------------------------------------------------------------------
* Callback function for ActivateProfiling()
*/
static void ProfileOutput(void * ptr, CCStr sql, sqlite3_uint64 time);
/* --------------------------------------------------------------------------------------------
* Validate the managed connection handle and throw an error if invalid.
*/
#if defined(_DEBUG) || defined(SQMOD_EXCEPTLOC)
void Validate(CCStr file, Int32 line) const;
#else
void Validate() const;
#endif // _DEBUG
/* --------------------------------------------------------------------------------------------
* Validate the managed connection handle and throw an error if invalid.
*/
#if defined(_DEBUG) || defined(SQMOD_EXCEPTLOC)
void ValidateCreated(CCStr file, Int32 line) const;
#else
void ValidateCreated() const;
#endif // _DEBUG
/* --------------------------------------------------------------------------------------------
* Validate the managed connection handle and throw an error if invalid.
*/
#if defined(_DEBUG) || defined(SQMOD_EXCEPTLOC)
const ConnRef & GetValid(CCStr file, Int32 line) const;
#else
const ConnRef & GetValid() const;
#endif // _DEBUG
/* --------------------------------------------------------------------------------------------
* Validate the managed connection handle and throw an error if invalid.
*/
#if defined(_DEBUG) || defined(SQMOD_EXCEPTLOC)
const ConnRef & GetCreated(CCStr file, Int32 line) const;
#else
const ConnRef & GetCreated() const;
#endif // _DEBUG
public:
/* --------------------------------------------------------------------------------------------
* Attempt to open the specified database.
*/
Connection()
: m_Handle()
{
/* ... */
}
/* --------------------------------------------------------------------------------------------
* Explicit constructor.
*/
Connection(CSStr name)
: m_Handle(new ConnHnd())
{
SQMOD_GET_VALID(*this)->Create(name, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, nullptr);
}
/* --------------------------------------------------------------------------------------------
* Explicit constructor.
*/
Connection(CSStr name, Int32 flags)
: m_Handle(new ConnHnd())
{
SQMOD_GET_VALID(*this)->Create(name, flags, nullptr);
}
/* --------------------------------------------------------------------------------------------
* Explicit constructor.
*/
Connection(CSStr name, Int32 flags, CSStr vfs)
: m_Handle(new ConnHnd())
{
SQMOD_GET_VALID(*this)->Create(name, flags, vfs);
}
/* --------------------------------------------------------------------------------------------
* Direct handle constructor.
*/
Connection(const ConnRef & c)
: m_Handle(c)
{
/* ... */
}
/* --------------------------------------------------------------------------------------------
* Copy constructor.
*/
Connection(const Connection & o) = default;
/* --------------------------------------------------------------------------------------------
* Move constructor.
*/
Connection(Connection && o) = default;
/* --------------------------------------------------------------------------------------------
* Copy assignment operator.
*/
Connection & operator = (const Connection & o) = default;
/* --------------------------------------------------------------------------------------------
* Move assignment operator.
*/
Connection & operator = (Connection && o) = default;
/* --------------------------------------------------------------------------------------------
* Perform an equality comparison between two connections.
*/
bool operator == (const Connection & o) const
{
return (m_Handle == o.m_Handle);
}
/* --------------------------------------------------------------------------------------------
* Perform an inequality comparison between two connections.
*/
bool operator != (const Connection & o) const
{
return (m_Handle != o.m_Handle);
}
/* --------------------------------------------------------------------------------------------
* Implicit conversion to the raw connection handle.
*/
operator sqlite3 * ()
{
return m_Handle ? m_Handle->mPtr : nullptr;
}
/* --------------------------------------------------------------------------------------------
* Implicit conversion to the raw connection handle.
*/
operator sqlite3 * () const
{
return m_Handle ? m_Handle->mPtr : nullptr;
}
/* --------------------------------------------------------------------------------------------
* Used by the script engine to compare two instances of this type.
*/
Int32 Cmp(const Connection & o) const
{
if (m_Handle.Get() == o.m_Handle.Get())
{
return 0;
}
else if (m_Handle.Get() > o.m_Handle.Get())
{
return 1;
}
else
{
return -1;
}
}
/* --------------------------------------------------------------------------------------------
* Used by the script engine to convert an instance of this type to a string.
*/
const String & ToString() const
{
return m_Handle ? m_Handle->mName : NullString();
}
/* --------------------------------------------------------------------------------------------
* Used by the script engine to retrieve the name from instances of this type.
*/
static SQInteger Typename(HSQUIRRELVM vm);
/* --------------------------------------------------------------------------------------------
* Retrieve the associated connection handle.
*/
const ConnRef & GetHandle() const
{
return m_Handle;
}
/* --------------------------------------------------------------------------------------------
* See whether the managed connection handle is valid.
*/
bool IsValid() const
{
return m_Handle;
}
/* --------------------------------------------------------------------------------------------
* See whether the managed connection handle was connected.
*/
bool IsConnected() const
{
return m_Handle && (m_Handle->mPtr != nullptr);
}
/* --------------------------------------------------------------------------------------------
* Return the number of active references to this connection handle.
*/
Uint32 GetRefCount() const
{
return m_Handle.Count();
}
/* --------------------------------------------------------------------------------------------
* Release the reference to the associated database connection.
*/
void Release()
{
m_Handle.Reset();
}
/* --------------------------------------------------------------------------------------------
* Retrieve the last received status code.
*/
Int32 GetStatus() const
{
return SQMOD_GET_VALID(*this)->mStatus;
}
/* --------------------------------------------------------------------------------------------
* Retrieve the flags used to create this database connection.
*/
Int32 GetFlags() const
{
return SQMOD_GET_VALID(*this)->mFlags;
}
/* --------------------------------------------------------------------------------------------
* Retrieve the name used to create this database connection.
*/
const String & GetName() const
{
return SQMOD_GET_VALID(*this)->mName;
}
/* --------------------------------------------------------------------------------------------
* Retrieve the virtual file system used to create this database connection.
*/
const String GetVFS() const
{
return SQMOD_GET_VALID(*this)->mVFS;
}
/* --------------------------------------------------------------------------------------------
* Return the numeric result code for the most recent failed API call (if any).
*/
Int32 GetErrorCode() const
{
return SQMOD_GET_VALID(*this)->ErrNo();
}
/* --------------------------------------------------------------------------------------------
* Return the extended numeric result code for the most recent failed API call (if any).
*/
Int32 GetExtendedErrorCode() const
{
return SQMOD_GET_VALID(*this)->ExErrNo();
}
/* --------------------------------------------------------------------------------------------
* Retrieve the message of the last received error code.
*/
CSStr GetErrStr() const
{
return SQMOD_GET_VALID(*this)->ErrStr();
}
/* --------------------------------------------------------------------------------------------
* Return the last error message associated with this database connection.
*/
CSStr GetErrMsg() const
{
return SQMOD_GET_VALID(*this)->ErrMsg();
}
/* --------------------------------------------------------------------------------------------
* Attempt to open the specified database.
*/
void Open(CSStr name);
/* --------------------------------------------------------------------------------------------
* Attempt to open the specified database.
*/
void Open(CSStr name, Int32 flags);
/* --------------------------------------------------------------------------------------------
* Attempt to open the specified database.
*/
void Open(CSStr name, Int32 flags, CSStr vfs);
/* --------------------------------------------------------------------------------------------
* Attempt to execute the specified query.
*/
Int32 Exec(CSStr str);
/* --------------------------------------------------------------------------------------------
* Attempt to queue the specified query.
*/
void Queue(CSStr str);
/* --------------------------------------------------------------------------------------------
* Attempt to create a statement from the specified query.
*/
Object Query(CSStr str) const;
/* --------------------------------------------------------------------------------------------
* See if the database connection was opened in read-only mode.
*/
bool IsReadOnly() const;
/* --------------------------------------------------------------------------------------------
* Shortcut to test if a table exists.
*/
bool TableExists(CCStr name) const;
/* --------------------------------------------------------------------------------------------
* See if the database connection is or is not in auto-commit mode.
*/
bool GetAutoCommit() const
{
return sqlite3_get_autocommit(SQMOD_GET_CREATED(*this)->mPtr);
}
/* --------------------------------------------------------------------------------------------
* Get the row-id of the most recent successful INSERT into the database from the current connection.
*/
Object GetLastInsertRowID() const
{
return MakeSLongObj(sqlite3_last_insert_rowid(SQMOD_GET_CREATED(*this)->mPtr));
}
/* --------------------------------------------------------------------------------------------
* Returns the number of database rows that were changed, inserted or deleted
* by the most recently completed SQL statement.
*/
Int32 GetChanges() const
{
return sqlite3_changes(SQMOD_GET_CREATED(*this)->mPtr);
}
/* --------------------------------------------------------------------------------------------
* Returns the total number of row changes caused by INSERT, UPDATE or DELETE statements
* since the database connection was opened.
*/
Int32 GetTotalChanges() const
{
return sqlite3_total_changes(SQMOD_GET_CREATED(*this)->mPtr);
}
/* --------------------------------------------------------------------------------------------
* See if this database connection has tracing enabled.
*/
bool GetTracing() const
{
return SQMOD_GET_VALID(*this)->mTrace;
}
/* --------------------------------------------------------------------------------------------
* Activate or deactivate tracing on this database connection.
*/
void SetTracing(bool toggle);
/* --------------------------------------------------------------------------------------------
* See if this database connection has profiling enabled.
*/
bool GetProfiling() const
{
return SQMOD_GET_VALID(*this)->mProfile;
}
/* --------------------------------------------------------------------------------------------
* Activate or deactivate profiling on this database connection.
*/
void SetProfiling(bool toggle);
/* --------------------------------------------------------------------------------------------
* Set a busy handler that sleeps for a specified amount of time when a table is locked.
*/
void SetBusyTimeout(Int32 millis);
/* --------------------------------------------------------------------------------------------
* Causes any pending database operation to abort and return at its earliest opportunity.
*/
void InterruptOperation() const
{
sqlite3_interrupt(SQMOD_GET_CREATED(*this)->mPtr);
}
/* --------------------------------------------------------------------------------------------
* Attempts to free as much heap memory as possible from the database connection.
*/
void ReleaseMemory() const
{
sqlite3_db_release_memory(SQMOD_GET_CREATED(*this)->mPtr);
}
/* --------------------------------------------------------------------------------------------
* Returns internal runtime status information associated with the current database connection.
*/
Int32 GetInfo(Int32 operation)
{
return GetInfo(operation, false, false);
}
/* --------------------------------------------------------------------------------------------
* Returns internal runtime status information associated with the current database connection.
*/
Int32 GetInfo(Int32 operation, bool highwater)
{
return GetInfo(operation, highwater, false);
}
/* --------------------------------------------------------------------------------------------
* Returns internal runtime status information associated with the current database connection.
*/
Int32 GetInfo(Int32 operation, bool highwater, bool reset);
/* --------------------------------------------------------------------------------------------
* Retrieve the number of queries in the queue.
*/
Uint32 QueueSize() const
{
return ConvTo< Uint32 >::From(SQMOD_GET_VALID(*this)->mQueue.size());
}
/* --------------------------------------------------------------------------------------------
* Reserve space upfront for the specified amount of queries in the query queue.
*/
void ReserveQueue(Uint32 num);
/* --------------------------------------------------------------------------------------------
* Release memory that is not occupied from the query queue.
*/
void CompactQueue()
{
SQMOD_GET_VALID(*this)->mQueue.shrink_to_fit();
}
/* --------------------------------------------------------------------------------------------
* Remove all queries from the queue without executing them.
*/
void ClearQueue()
{
SQMOD_GET_VALID(*this)->mQueue.clear();
}
/* --------------------------------------------------------------------------------------------
* Remove the last query from the queue.
*/
void PopQueue();
/* --------------------------------------------------------------------------------------------
* Flush all queries from the queue.
*/
Int32 Flush();
/* --------------------------------------------------------------------------------------------
* Flush a specific amount of queries from the queue.
*/
Int32 Flush(SQInteger num);
/* --------------------------------------------------------------------------------------------
* Flush all queries from the queue and handle errors manually.
*/
Int32 Flush(Object & env, Function & func);
/* --------------------------------------------------------------------------------------------
* Flush a specific amount of queries from the queue and handle errors manually.
*/
Int32 Flush(SQInteger num, Object & env, Function & func);
/* --------------------------------------------------------------------------------------------
* Attempt to execute the specified query.
*/
static SQInteger ExecF(HSQUIRRELVM vm);
/* --------------------------------------------------------------------------------------------
* Attempt to queue the specified query.
*/
static SQInteger QueueF(HSQUIRRELVM vm);
/* --------------------------------------------------------------------------------------------
* Attempt to create a statement from the specified query.
*/
static SQInteger QueryF(HSQUIRRELVM vm);
};
} // Namespace:: SqMod
#endif // _SQSQLITE_CONNECTION_HPP_