dbdriver.h

来自「Shorthand是一个强大的脚本语言」· C头文件 代码 · 共 227 行

#ifndef __dbdriver_h
#define __dbdriver_h

#include "cstring.h"


typedef unsigned long ShhDbHandle;
typedef unsigned long ShhCursorHandle;
typedef unsigned long ShhResultHandle;
typedef unsigned long ShhRowHandle;

class ShhDbExecutor
{
public:
    virtual const char* 
        fpi_StoreParameter(int index, const char* value) = 0;
    virtual ShhDbHandle
        fpi_GetConnection() = 0;
};

/**
 * Database Driver.
 * 
 * This class defines "service provider interface" (SPI) and is intended
 * only for developers of database drivers and ShortHand core.
 *
 * Database Access Objects (ShhDbSession, ShhSQL, ShhDML, etc) are
 * consumers of actual implementations. 
 */
class ShhDbDriver 
{
public:
    /**
     * Returns true if driver implementation recognizes
     * specified driver name as supported by itself.
     */
    virtual bool 
        spi_RecognizeDriverName(const char* driverName) = 0;

    /**
     * Returns 3-character driver prefix used in error
     * messages and warnings ('MYQ','PRG','ORA','IFX', ...)
     */
    virtual const char*
        spi_GetDriverPrefix() = 0;
    
    /**
     * Puts long driver description. For example "Oracle (OCI8)"
     *
     * The size of supplied buffer is 255 characters, 
     * not counting terminating zero.
     */
    virtual int 
        spi_GetDriverDescription(string& driverDescription) = 0;
    
    /**
     * Tries to open connection using connection string as
     * parameter. Interpretation of connection string completely
     * depends on implementation. ShortHand framework does not
     * perform validation or translation of connection string.
     * 
     * Upon success, driver returns an instance of object 
     * implementing <a href="ShhDbHandle.html">ShhDbHandle</a> 
     * interface.
     * If connection fails, this method throws exception derived
     * from ShhObjectException
     * 
     * @param connString driver-specific connection string
     * @return connection handle if connection has been established.
     * @throws ShhObjectException if connection fails. 
     */
    virtual ShhDbHandle
        spi_Connect(const char* connString) = 0;

    /**
     * Obtains information about last error.
     *
     * @param session valid database connection handle
     * @param message variable that receives error text
     * @return error code (must be zero if no error detected).
     */
    virtual int
        spi_GetLastError(ShhDbHandle session, string& message) = 0;

    /**
     * Closes database connection and releases connection handle
     * (and frees the structure if connection handle is a pointer
     * to the session structor).
     * Connection handle value cannot be used after this operation.
     *
     * @param conn valid database connection handle.
     */
    virtual void
        spi_Disconnect(ShhDbHandle session) = 0;

    /**
     * Creates cursor for a given statement, and "prepares" the 
     * statement, if applicable.
     * 
     * @param conn valid database connection handle.
     * @return cursor handle
     */
    virtual ShhCursorHandle
        spi_PrepareSQL(ShhDbHandle session, const char* sql) = 0;

    /**
     * Closes cursor and releases any associated resources.
     *
     * @
     */
    virtual void
        spi_CloseCursor(ShhCursorHandle cursor) = 0;

    /**
     * Executes SQL or DML/DDL statement without overhead of 
     * creating any cursors and result set structures. Useful 
     * for simple DMLs or control commands like COMMIT.
     *
     * @param conn valid database connection handle
     * @param sql SQL statement to execute
     */
    virtual int
        spi_ExecuteImmediate(ShhDbHandle conn, const char* sql) = 0;

    /**
     * Executes prepared cursor.
     * Note that both cursor handle and raw SQL are passed to this method.
     * Drivers that do not have or do not use prepared SQL statements, 
     * can use raw SQL to execute the statement (cursor parameter in this
     * case is be ignored and can be NULL).
     *
     * @param session database connection handle
     * @param cursor cursor(statement) handle
     * @param sql original SQL text that (maybe) was used to prepare the statement.
     * @return result set handle
     */
    virtual ShhResultHandle
        spi_ExecuteCursor(ShhDbHandle session, ShhCursorHandle cursor, const char* sql) = 0;
      
    /**
     * Closes result set and releases all associated resources.
     */
    virtual void
        spi_CloseResult(ShhResultHandle resultSet) = 0;

    /**
     * Closes result set and releases all associated resources.
     */
    virtual void
        spi_CloseRow(ShhRowHandle rowHandle) = 0;


    /**
     * Returns number of fields in the result set.
     */
    virtual int
        spi_GetFieldCount(ShhResultHandle resultSet) = 0;

    /**
     * Returns number of rows in the result set.
     *
     * @param resultSet result set handle
     * @return number of rows in the result set.
     *         -1 means that number of rows that the statement will return
     *         is not known at this point (but it may return rows).
     */
    virtual int
        spi_GetRowCount(ShhResultHandle resultSet) = 0;

    /**
     * Clears any parameter bindings.
     */
    virtual int
        spi_ClearParameters(ShhCursorHandle hCursor) = 0;

    /**
     * Pastes parameter value into SQL statement.
     * If the driver supports parameter bindings and markers, it 
     * pastes marker (usually "?") into SQL instead of value itself 
     * and binds supplied value to that marker using native driver API.
     * If the driver doesn't support binding/markers, it pastes quotes
     * and escapes special characters inside strings as necessary.
     */
    virtual int
        spi_PasteValue(ShhCursorHandle hCursor, ShhDbExecutor* executor, int index, string& output, const char* value) = 0;

    virtual int
        spi_BindValue(ShhCursorHandle hCursor, ShhDbExecutor* executor, int index, const char* value) = 0;

    /**
     * Obtains the name of result set field.
     *
     * @param resultSet result set handle
     * @param fieldNumber field number (first field has number 0).
     * @param fieldName variable that receives field name
     * @return length of the field name
     */
    virtual int
        spi_GetFieldName(ShhResultHandle resultSet, int fieldNumber, string& fieldName) = 0;

    /**
     * Fetches next row 
     */
    virtual ShhRowHandle
        spi_Fetch(ShhResultHandle resultSet) = 0;

    /**
     * Retrieves value of the current row field.
     * @param row row handle
     * @param fieldNumber field number (first field has number 0).
     * @param value variable that receives field value
     * @return length of the field value
     */
    virtual int
        spi_GetStringValue(ShhResultHandle resultSet, ShhRowHandle row, int fieldNumber, string& value) = 0;

    /**
     * Returns number of rows affected by last executed statement,
     * if applicable. If implementation doesn't support this function, 
     * it throws ShhObjectException.
     */
    virtual int
        spl_GetAffectedRows(ShhCursorHandle connection) = 0;
};


#endif // __dbdriver_h