interfaces.hpp

ncbi源码

    // Get # of items (columns) in the result
    virtual unsigned int NofItems() const = 0;

    // Get name of a result item.
    // Return NULL if "item_num" >= NofItems().
    virtual const char* ItemName(unsigned int item_num) const = 0;

    // Get size (in bytes) of a result item.
    // Return zero if "item_num" >= NofItems().
    virtual size_t ItemMaxSize(unsigned int item_num) const = 0;

    // Get datatype of a result item.
    // Return 'eDB_UnsupportedType' if "item_num" >= NofItems().
    virtual EDB_Type ItemDataType(unsigned int item_num) const = 0;

    // Fetch next row
    virtual bool Fetch() = 0;

    // Return current item number we can retrieve (0,1,...)
    // Return "-1" if no more items left (or available) to read.
    virtual int CurrentItemNo() const = 0;

    // Get a result item (you can use either GetItem or ReadItem).
    // If "item_buf" is not NULL, then use "*item_buf" (its type should be
    // compatible with the type of retrieved item!) to retrieve the item to;
    // otherwise allocate new "CDB_Object".
    virtual CDB_Object* GetItem(CDB_Object* item_buf = 0) = 0;

    // Read a result item body (for text/image mostly).
    // Return number of successfully read bytes.
    // Set "*is_null" to TRUE if the item is <NULL>.
    // Throw an exception on any error.
    virtual size_t ReadItem(void* buffer, size_t buffer_size,
                            bool* is_null = 0) = 0;

    // Get a descriptor for text/image column (for SendData).
    // Return NULL if this result doesn't (or can't) have img/text descriptor.
    // NOTE: you need to call ReadItem (maybe even with buffer_size == 0)
    //       before calling this method!
    virtual I_ITDescriptor* GetImageOrTextDescriptor() = 0;

    // Skip result item
    virtual bool SkipItem() = 0;

public:
    virtual ~I_Result();

    friend class CDB_Result;
};


    
/////////////////////////////////////////////////////////////////////////////
//
//  I_DriverContext::
//

class NCBI_DBAPIDRIVER_EXPORT I_DriverContext
{
public:
    // Connection mode
    enum EConnectionMode {
        fBcpIn             = 0x1,
        fPasswordEncrypted = 0x2,
        fDoNotConnect      = 0x4   // Use just connections from NotInUse pool
        // all driver-specific mode flags > 0x100
    };
    typedef int TConnectionMode;  // holds a binary OR of "EConnectionMode"

    // Set login and connection timeouts.
    // NOTE:  if "nof_secs" is zero or is "too big" (depends on the underlying
    //        DB API), then set the timeout to infinite.
    // Return FALSE on error.
    virtual bool SetLoginTimeout (unsigned int nof_secs = 0) = 0;
    virtual bool SetTimeout      (unsigned int nof_secs = 0) = 0;

    // Set maximal size for Text and Image objects. Text and Image objects
    // exceeding this size will be truncated.
    // Return FALSE on error (e.g. if "nof_bytes" is too big).
    virtual bool SetMaxTextImageSize(size_t nof_bytes) = 0;

    // Create new connection to specified server (within this context).
    // It is your responsibility to delete the returned connection object.
    virtual CDB_Connection* Connect(const string&   srv_name,
                                    const string&   user_name,
                                    const string&   passwd, 
                                    TConnectionMode mode,
                                    bool            reusable  = false,
                                    const string&   pool_name = kEmptyStr) = 0;

    // Return number of currently open connections in this context.
    // If "srv_name" is not NULL, then return # of conn. open to that server.
    virtual unsigned int NofConnections(const string& srv_name  = kEmptyStr,
                                        const string& pool_name = kEmptyStr)
        const;

    // Add message handler "h" to process 'context-wide' (not bound 
    // to any particular connection) error messages.
    virtual void PushCntxMsgHandler(CDB_UserHandler* h);

    // Remove message handler "h" and all handlers above it in the stack
    virtual void PopCntxMsgHandler(CDB_UserHandler* h);

    // Add `per-connection' err.message handler "h" to the stack of default
    // handlers which are inherited by all newly created connections.
    virtual void PushDefConnMsgHandler(CDB_UserHandler* h);

    // Remove `per-connection' mess. handler "h" and all above it in the stack.
    virtual void PopDefConnMsgHandler(CDB_UserHandler* h);

    // Report if the driver supports this functionality
    enum ECapability {
        eBcp,
        eReturnITDescriptors,
        eReturnComputeResults
    };
    virtual bool IsAbleTo(ECapability cpb) const = 0;

    // close reusable deleted connections for specified server and/or pool
    void CloseUnusedConnections(const string& srv_name  = kEmptyStr,
                                const string& pool_name = kEmptyStr);

    virtual ~I_DriverContext();

protected:
    I_DriverContext();

    // To allow children of I_DriverContext to create CDB_Connection
    static CDB_Connection* Create_Connection(I_Connection& connection);

    // Used and unused(reserve) connections
    CPointerPot m_NotInUse;
    CPointerPot m_InUse;

    // Stacks of `per-context' and `per-connection' err.message handlers
    CDBHandlerStack m_CntxHandlers;
    CDBHandlerStack m_ConnHandlers;

    mutable CFastMutex m_Mtx;

private:
    // Return unused connection "conn" to the driver context for future
    // reuse (if "conn_reusable" is TRUE) or utilization
    void x_Recycle(I_Connection* conn, bool conn_reusable);
    friend class CDB_Connection;
};



/////////////////////////////////////////////////////////////////////////////
//
//  I_Connection::
//

class NCBI_DBAPIDRIVER_EXPORT I_Connection : public CDB_BaseEnt
{
    friend class I_DriverContext;
protected:
    // Check out if connection is alive (this function doesn't ping the server,
    // it just checks the status of connection which was set by the last
    // i/o operation)
    virtual bool IsAlive() = 0;

    // These methods:  LangCmd(), RPC(), BCPIn(), Cursor() and SendDataCmd()
    // create and return a "command" object, register it for later use with
    // this (and only this!) connection.
    // On error, an exception will be thrown (they never return NULL!).
    // It is the user's responsibility to delete the returned "command" object.

    // Language command
    virtual CDB_LangCmd* LangCmd(const string& lang_query,
                                 unsigned int  nof_params = 0) = 0;
    // Remote procedure call
    virtual CDB_RPCCmd* RPC(const string& rpc_name,
                            unsigned int  nof_args) = 0;
    // "Bulk copy in" command
    virtual CDB_BCPInCmd* BCPIn(const string& table_name,
                                unsigned int  nof_columns) = 0;
    // Cursor
    virtual CDB_CursorCmd* Cursor(const string& cursor_name,
                                  const string& query,
                                  unsigned int  nof_params,
                                  unsigned int  batch_size = 1) = 0;
    // "Send-data" command
    virtual CDB_SendDataCmd* SendDataCmd(I_ITDescriptor& desc,
                                         size_t          data_size,
                                         bool            log_it = true) = 0;

    // Shortcut to send text and image to the server without using the
    // "Send-data" command (SendDataCmd)
    virtual bool SendData(I_ITDescriptor& desc, CDB_Text& txt,
                          bool log_it = true) = 0;
    virtual bool SendData(I_ITDescriptor& desc, CDB_Image& img,
                          bool log_it = true) = 0;

    // Reset the connection to the "ready" state (cancel all active commands)
    virtual bool Refresh() = 0;

    // Get the server name, user login name, and password
    virtual const string& ServerName() const = 0;
    virtual const string& UserName() const = 0;
    virtual const string& Password() const = 0;

    // Get the bitmask for the connection mode (BCP, secure login, ...)
    virtual I_DriverContext::TConnectionMode ConnectMode() const = 0;

    // Check if this connection is a reusable one
    virtual bool IsReusable() const = 0;

    // Find out which connection pool this connection belongs to
    virtual const string& PoolName() const = 0;

    // Get pointer to the driver context
    virtual I_DriverContext* Context() const = 0;

    // Put the message handler into message handler stack
    virtual void PushMsgHandler(CDB_UserHandler* h) = 0;

    // Remove the message handler (and all above it) from the stack
    virtual void PopMsgHandler(CDB_UserHandler* h) = 0;

    virtual CDB_ResultProcessor* SetResultProcessor(CDB_ResultProcessor* rp)=0;

    // These methods to allow the children of I_Connection to create
    // various command-objects
    static CDB_LangCmd*     Create_LangCmd     (I_LangCmd&     lang_cmd    );
    static CDB_RPCCmd*      Create_RPCCmd      (I_RPCCmd&      rpc_cmd     );
    static CDB_BCPInCmd*    Create_BCPInCmd    (I_BCPInCmd&    bcpin_cmd   );
    static CDB_CursorCmd*   Create_CursorCmd   (I_CursorCmd&   cursor_cmd  );
    static CDB_SendDataCmd* Create_SendDataCmd (I_SendDataCmd& senddata_cmd);

public:
    virtual ~I_Connection();

    friend class CDB_Connection;
};


typedef I_DriverContext* (*FDBAPI_CreateContext)(map<string,string>* attr);

class NCBI_DBAPIDRIVER_EXPORT I_DriverMgr
{
public:
    virtual void RegisterDriver(const string& driver_name,
                                FDBAPI_CreateContext driver_ctx_func) = 0;
    virtual ~I_DriverMgr(void);
};


END_NCBI_SCOPE


/* @} */


/*
 * ===========================================================================
 * $Log: interfaces.hpp,v $
 * Revision 1000.1  2003/11/17 22:11:27  gouriano
 * PRODUCTION: UPGRADED [ORIGINAL] Dev-tree R1.25
 *
 * Revision 1.25  2003/11/14 20:45:22  soussov
 * adds DoNotConnect mode
 *
 * Revision 1.24  2003/07/17 22:08:02  soussov
 * I_DriverContext to be friend of I_Connection
 *
 * Revision 1.23  2003/07/17 20:41:37  soussov
 * connections pool improvements
 *
 * Revision 1.22  2003/06/05 20:26:39  soussov
 * makes I_Result interface public
 *
 * Revision 1.21  2003/06/05 15:53:31  soussov
 * adds DumpResults method for LangCmd and RPC, SetResultProcessor method for Connection interface
 *
 * Revision 1.20  2003/04/11 17:46:07  siyan
 * Added doxygen support
 *
 * Revision 1.19  2003/04/01 20:25:16  vakatov
 * Temporarily rollback to R1.16 -- until more backward-incompatible
 * changes (in CException) are ready to commit (to avoid breaking the
 * compatibility twice).
 *
 * Revision 1.17  2003/02/12 22:08:32  coremake
 * Added export specifier NCBI_DBAPIDRIVER_EXPORT to the I_RPCCmd class declaration
 *
 * Revision 1.16  2002/12/26 19:29:12  dicuccio
 * Added Win32 export specifier for base DBAPI library
 *
 * Revision 1.15  2002/12/20 17:52:47  soussov
 * renames the members of ECapability enum
 *
 * Revision 1.14  2002/04/09 22:33:12  vakatov
 * Identation
 *
 * Revision 1.13  2002/03/26 15:25:16  soussov
 * new image/text operations added
 *
 * Revision 1.12  2002/01/20 07:21:00  vakatov
 * I_DriverMgr:: -- added virtual destructor
 *
 * Revision 1.11  2002/01/17 22:33:13  soussov
 * adds driver manager
 *
 * Revision 1.10  2002/01/15 17:12:40  soussov
 * renaming 'tds' driver to 'ftds' driver
 *
 * Revision 1.9  2002/01/11 21:26:16  soussov
 * changes typedef for FDBAPI_CreateContext
 *
 * Revision 1.8  2002/01/11 20:48:58  soussov
 * changes typedef for FDBAPI_CreateContext
 *
 * Revision 1.7  2002/01/11 20:22:41  soussov
 * driver manager support added
 *
 * Revision 1.6  2001/11/06 17:58:03  lavr
 * Formatted uniformly as the rest of the library
 *
 * Revision 1.5  2001/10/01 20:09:27  vakatov
 * Introduced a generic default user error handler and the means to
 * alternate it. Added an auxiliary error handler class
 * "CDB_UserHandler_Stream".
 * Moved "{Push/Pop}{Cntx/Conn}MsgHandler()" to the generic code
 * (in I_DriverContext).
 *
 * Revision 1.4  2001/09/27 20:08:29  vakatov
 * Added "DB_" (or "I_") prefix where it was missing
 *
 * Revision 1.3  2001/09/26 23:23:26  vakatov
 * Moved the err.message handlers' stack functionality (generic storage
 * and methods) to the "abstract interface" level.
 *
 * Revision 1.2  2001/09/24 20:52:18  vakatov
 * Fixed args like "string& s = 0" to "string& s = kEmptyStr"
 *
 * Revision 1.1  2001/09/21 23:39:52  vakatov
 * -----  Initial (draft) revision.  -----
 * This is a major revamp (by Denis Vakatov, with help from Vladimir Soussov)
 * of the DBAPI "driver" libs originally written by Vladimir Soussov.
 * The revamp involved massive code shuffling and grooming, numerous local
 * API redesigns, adding comments and incorporating DBAPI to the C++ Toolkit.
 *
 * ===========================================================================
 */

#endif  /* DBAPI_DRIVER___INTERFACES__HPP */