ncbi_connection.h

ncbi源码

 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Flush
(CONN conn              /* [in] connection handle                      */ 
 );


/* Read up to "size" bytes from a connection to the buffer to pointed by "buf".
 * In "*n_read", return the number of successfully read bytes.
 * If there is absolutely no data available to read and the timeout (see
 * CONN_SetTimeout()) is expired then return eIO_Timeout (and "*n_read" := 0).
 * The arg "how" means:
 *   eIO_ReadPlain   -- read presently available data only and return
 *   eIO_ReadPeek    -- eIO_ReadPlain but dont discard read data from inp.queue
 *   eIO_ReadPersist -- try to read exactly "n" bytes;  return eIO_Timeout if
 *                      could not read the requested # of bytes, and read
 *                      timeout has expired.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Read
(CONN           conn,   /* [in]  connection handle                  */
 void*          buf,    /* [out] memory buffer to read to           */
 size_t         size,   /* [in]  max. # of bytes to read            */
 size_t*        n_read, /* [out, non-NULL] # of actually read bytes */
 EIO_ReadMethod how     /* [in]  read/peek | persist                */
 );


/* Read up to "size" bytes from a connection into the string buffer pointed
 * to by "line".  Stop reading if either '\n' or an error is encountered.
 * Replace '\n' with '\0'.  Upon return "*n_read" contains the number
 * of characters written to "line", not including the terminating '\0'.
 * If not enough space provided in "line" to accomodate the '\0'-terminated
 * line, then all "size" bytes are used and "*n_read" equals "size" on return.
 * This is the only case when "line" will not be '\0'-terminated.
 * Return code advises the caller whether another line read can be attempted:
 *   eIO_Success -- read completed successfully, keep reading;
 *   other code  -- an error occurred, and further attempt may fail.
 *
 * This call utilizes eIO_Read timeout as set by CONN_SetTimeout().
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_ReadLine
(CONN    conn,
 char*   line,
 size_t  size,
 size_t* n_read
 );


/* Obtain status of the last IO operation. This is NOT a completion
 * code of the last CONN-call, but rather a status from the lower level
 * connector's layer.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Status
(CONN      conn,   /* [in]  connection handle       */
 EIO_Event dir     /* [in] = {eIO_Read | eIO_Write} */
 );


/* Close the connection, destroy relevant internal data.
 * NOTE:  whatever error code is returned, the connection handle "conn"
 *        will become invalid (so, you should not use it anymore).
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Close
(CONN conn  /* [in] connection handle */
 );


/* Set user callback function to be called upon an event specified by the
 * callback type. Note that the callback function is always called prior to
 * the event to happen, e.g. the eCONN_OnClose callback is called when
 * the connection is about to close, but not closed yet.
 * The callback function is supplied with 3 arguments: connection handle,
 * type of event, and user data (specified when the callback was set).
 * CONN_SetCallback stores previous callback in "old_cb" (if it is not NULL).
 */
typedef enum {
    eCONN_OnClose = 0
#define CONN_N_CALLBACKS 1
} ECONN_Callback;

typedef void (*FConnCallback)(CONN conn, ECONN_Callback type, void* data);

typedef struct {
    FConnCallback func;  /* Function to call on event                */
    void*         data;  /* Data to pass to the callback as last arg */
} SCONN_Callback;

extern NCBI_XCONNECT_EXPORT EIO_Status CONN_SetCallback
(CONN                  conn,    /* [in]  connection to set callback for     */
 ECONN_Callback        type,    /* [in]  callback type                      */
 const SCONN_Callback* new_cb,  /* [in]  callback to set (may be 0)         */
 SCONN_Callback*       old_cb   /* [out] to save old callback at (may be 0) */
);


#ifdef IMPLEMENTED__CONN_WaitAsync
/* Wait for an asynchronous I/O event, then call the specified handler.
 * In the "handler" function:
 *   "event"  -- is the I/O direction where the async. event happened
 *   "status" -- must be "eIO_Success" if it is ready for I/O
 *   "data"   -- callback data (passed as "data" in CONN_WaitAsync())
 * If "handler" is NULL then discard the current handler, if any.
 * The "cleanup" function to be called right after the call to "handler" or
 * by CONN_Close(), or if the handler is reset by calling CONN_WaitAsync()
 * again -- whichever happens first.
 */
typedef void (*FConnAsyncHandler)
(CONN       conn,
 EIO_Event  event,
 EIO_Status status,
 void*      data
);
typedef void (*FConnAsyncCleanup)(void* data);

extern EIO_Status CONN_WaitAsync
(CONN              conn,      /* [in] connection handle */
 EIO_Event         event,     /* [in] I/O direction     */
 FConnAsyncHandler handler,   /* [in] callback function */
 void*             data,      /* [in] callback data     */
 FConnAsyncCleanup cleanup    /* [in] cleanup procedure */
 );
#endif /* IMPLEMENTED__CONN_WaitAsync */


#ifdef __cplusplus
}  /* extern "C" */
#endif


/* @} */


/*
 * ---------------------------------------------------------------------------
 * $Log: ncbi_connection.h,v $
 * Revision 1000.2  2004/06/01 18:44:35  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R6.19
 *
 * Revision 6.19  2004/05/24 19:58:29  lavr
 * +NCBI_XCONNECT_EXPORT for CONN_ReadLine()
 *
 * Revision 6.18  2004/05/24 19:53:30  lavr
 * +CONN_ReadLine()
 *
 * Revision 6.17  2004/02/23 15:23:36  lavr
 * New (last) parameter "how" added in CONN_Write() API call
 *
 * Revision 6.16  2003/05/14 03:47:12  lavr
 * +CONN_Description()
 *
 * Revision 6.15  2003/04/09 17:58:43  siyan
 * Added doxygen support
 *
 * Revision 6.14  2003/01/15 19:50:17  lavr
 * +CONN_PushBack()
 *
 * Revision 6.13  2003/01/08 01:59:32  lavr
 * DLL-ize CONNECT library for MSVC (add NCBI_XCONNECT_EXPORT)
 *
 * Revision 6.12  2002/09/19 18:00:04  lavr
 * Header file guard macro changed
 *
 * Revision 6.11  2002/09/06 15:40:32  lavr
 * More comments and notes to the API
 *
 * Revision 6.10  2002/08/07 16:27:33  lavr
 * EIO_ReadMethod enums changed accordingly; log moved to the bottom
 *
 * Revision 6.9  2001/08/20 20:00:22  vakatov
 * CONN_SetTimeout() to return "EIO_Status".
 *
 * Revision 6.8  2001/06/28 22:00:31  lavr
 * Added function: CONN_SetCallback
 * Added callback: eCONN_OnClose
 *
 * Revision 6.7  2001/04/24 21:19:29  lavr
 * Introduced CONN_DEFAULT_TIMEOUT for use as a CONNECTOR-specific timeout
 *
 * Revision 6.6  2001/03/02 20:07:33  lavr
 * Typo fixed
 *
 * Revision 6.5  2001/02/09 17:33:38  lavr
 * CONN_GetType added
 *
 * Revision 6.4  2001/01/03 22:29:22  lavr
 * Changed IOStatus -> Status
 *
 * Revision 6.3  2000/12/29 17:43:42  lavr
 * Pretty printed;
 * Reconnect renamed to ReInit with ability to close current connector
 *
 * Revision 6.2  2000/04/07 19:59:47  vakatov
 * Moved forward-declaration of CONNECTOR from "ncbi_connection.h"
 * to "ncbi_connector.h"
 *
 * Revision 6.1  2000/03/24 22:52:20  vakatov
 * Initial revision
 *
 * ===========================================================================
 */

#endif /* CONNECT___NCBI_CONNECTION__H */