ncbi_connection.h

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbi_connection.h,v $
 * PRODUCTION Revision 1000.2  2004/06/01 18:44:35  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R6.19
 * PRODUCTION
 * ===========================================================================
 */

#ifndef CONNECT___NCBI_CONNECTION__H
#define CONNECT___NCBI_CONNECTION__H

/*  $Id: ncbi_connection.h,v 1000.2 2004/06/01 18:44:35 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Author:  Denis Vakatov
 *
 * File Description:
 *   Generic API to open and handle connection to an abstract I/O service.
 *   Several methods can be used to establish the connection, and each of them
 *   yields in a simple handle(of type "CONN") that contains a handle(of type
 *   "CONNECTOR") to a data and methods implementing the generic connection I/O
 *   operations. E.g. this API can be used to:
 *     1) connect using HTTPD-based dispatcher (e.g. to NCBI services);
 *     2) hit a CGI script;
 *     3) connect to a bare socket at some "host:port";
 *     4) whatever else can fit this paradigm -- see the SConnectorTag-related
 *        structures;  e.g. it could be a plain file I/O or even a memory area.
 *
 *  See in "ncbi_connector.h" for the detailed specification of the underlying
 *  connector("CONNECTOR", "SConnectorTag") methods and data structures.
 *
 */

#include <connect/ncbi_connector.h>


/** @addtogroup Connectors
 *
 * @{
 */


#ifdef __cplusplus
extern "C" {
#endif


struct SConnectionTag;
typedef struct SConnectionTag* CONN;      /* connection handle */


/* Compose all data necessary to establish a new connection
 * (merely bind it to the specified connector). Unsuccessful completion
 * sets conn to 0, and leaves connector intact (can be used again).
 * NOTE1:  The real connection will not be established right away. Instead,
 *         it will be established at the moment of the first call to one of
 *         "Flush", "Wait", "WaitAsync", "Write", or "Read" methods.
 * NOTE2:  "Connection establishment" at this level of abstraction may differ
 *         from actual link establishment at the underlying connector's level.
 * NOTE3:  Initial timeout values are set to CONN_DEFAULT_TIMEOUT, meaning
 *         that connector-specific timeouts are in force for the connection.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Create
(CONNECTOR connector,  /* [in]  connector                        */
 CONN*     conn        /* [out] handle of the created connection */
 );


/* Reinit, using "connector".
 * If "conn" is already opened then close the current connection at first,
 * even if "connector" is just the same as the current connector.
 * If "connector" is NULL then close and destroy current connector, and leave
 * connection empty (effective way to destroy connector(s)).
 * NOTE:  Although it closes the previous connection immediately, however it
 *        does not open the new connection right away -- see notes to "Create".
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_ReInit
(CONN      conn,      /* [in] connection handle */
 CONNECTOR connector  /* [in] new connector     */
 );


/* Get verbal representation of connection type as a character string.
 * Note that the returned value is only valid until the next
 * I/O operation in the connection. Return value NULL denotes
 * unknown connection type.
 */
extern NCBI_XCONNECT_EXPORT const char* CONN_GetType
(CONN conn  /* [in]  connection handle */ 
 );


/* Return human-readable description of the connection as a character
 * 0-terminated string. The string is not guaranteed to have any
 * particular format and is intended solely for something like
 * logging and debugging. Return NULL if the connection cannot
 * provide any description information (or if it is in a bad state).
 * Application program is responsible to deallocate the space occupied
 * by the returned string calling free() when the description is no longer
 * needed.
 */
extern NCBI_XCONNECT_EXPORT char* CONN_Description
(CONN conn  /* [in]  connection handle */
 );


/* Specify timeout for the connection I/O (including "Connect" (aka "Open")
 * and "Close"). May be called at any time during the connection lifetime.
 * NOTE1:  if "new_timeout" is NULL then set the timeout to be infinite.
 * NOTE2:  if "new_timeout" is CONN_DEFAULT_TIMEOUT then underlying
 *         connector-specific value is used (this is the default).
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_SetTimeout
(CONN            conn,        /* [in] connection handle */
 EIO_Event       event,       /* [in] I/O direction     */
 const STimeout* new_timeout  /* [in] new timeout       */
 );


/* Retrieve current timeout (return NULL if it is infinite).
 * The returned pointer is guaranteed to point to the valid timeout structure
 * (or be either NULL or CONN_DEFAULT_TIMEOUT) until the next "SetTimeout"
 * or "Close" method's call.
 */
extern NCBI_XCONNECT_EXPORT const STimeout* CONN_GetTimeout
(CONN      conn,  /* [in] connection handle                  */
 EIO_Event event  /* [in] I/O direction, not "eIO_ReadWrite" */
 );


/* Block on the connection until it becomes available for either read or
 * write (dep. on "event"), or until the timeout expires, or until any error.
 * NOTE:  "timeout" can also be one of two special values:
 *         NULL (means infinite), CONN_DEFAULT_TIMEOUT (connector-defined).
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Wait
(CONN            conn,    /* [in] connection handle                  */
 EIO_Event       event,   /* [in] can be eIO_Read or eIO_Write only! */
 const STimeout* timeout  /* [in] the maximal wait time              */
 );


/* Write "size" bytes from the mem.buffer "buf" to the connection.
 * In "*n_written", return the number of successfully written bytes.
 * Parameter "how" modifies behavior of CONN_Write():
 * eIO_WritePlain   -- return eIO_Success if some data were written and
 *                     yet write timeout had not occurred, error otherwise;
 * eIO_WritePersist -- return eIO_Success only if all data were written and
 *                     yet write timeout had not occurred, error otherwise.
 * NOTE:  See CONN_SetTimeout() hoe to set write timeout.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_Write
(CONN            conn,      /* [in]  connection handle                     */ 
 const void*     buf,       /* [in]  pointer to the data buffer to write   */ 
 size_t          size,      /* [in]  # of bytes to write                   */ 
 size_t*         n_written, /* [out, non-NULL] # of actually written bytes */
 EIO_WriteMethod how        /* [in]  eIO_WritePlain or eIO_WritePersist    */
 );


/* Push back "size" bytes from the mem.buffer "buf" into connection.
 * Return eIO_Success on success, other code on an error.
 * NOTE1:  Data pushed back are not necessarily those taken from the
 *         connection before.
 * NOTE2:  Upon successive read operation, the pushed back data are
 *         taken out first.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status CONN_PushBack
(CONN        conn,  /* [in]  connection handle                     */
 const void* buf,   /* [in]  pointer to the data being pushed back */
 size_t      size   /* [in]  # of bytes to push back               */
 );


/* Explicitly flush to the connection all data written by "CONN_Write()".
 * NOTE1:  CONN_Flush() effectively opens connection (if it wasn't open yet).
 * NOTE2:  Connection considered open if underlying connector's "Open" method
 *         has successfully executed; actual data link may not yet exist.
 * NOTE3:  CONN_Read() always calls CONN_Flush() before proceeding.
 *         So does CONN_Close() but only if connection is was open before.