ncbi_connector.h

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbi_connector.h,v $
 * PRODUCTION Revision 1000.0  2003/10/29 16:29:56  gouriano
 * PRODUCTION PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R6.16
 * PRODUCTION
 * ===========================================================================
 */

#ifndef CONNECT___NCBI_CONNECTOR__H
#define CONNECT___NCBI_CONNECTOR__H

/*  $Id: ncbi_connector.h,v 1000.0 2003/10/29 16:29:56 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:
 *   Specifications to implement a connector("CONNECTOR") to be used to open
 *   and handle connection("CONN", see also in "ncbi_connection.[ch]") to an
 *   abstract I/O service. This is generally not for the public use.
 *   It is to be used in the modules that implement a particular connector.
 *
 */

#include <connect/ncbi_core.h>


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


#ifdef __cplusplus
extern "C" {
#endif


struct SConnectorTag;
typedef struct SConnectorTag* CONNECTOR;  /* connector handle */


/* Function type definitions for the connector method table.
 * The arguments & the behavior of "FConnector***" functions are mostly just
 * the same as those for their counterparts "CONN_***" in ncbi_connection.h.
 * First argument of these functions accepts a real connector handle
 * rather than a connection handle("CONN").
 * In every call, which has STimeout as an argument, this argument
 * can be either NULL, CONN_DEFAULT_TIMEOUT, or other non-NULL pointer,
 * pointing to finite timeout structure. NULL is treated as an infinite
 * timeout, while CONN_DEFAULT_TIMEOUT means to use any timeout, which
 * is somehow pre-defined by the connector itself.
 */


/* Get the name of the connector (may be NULL on error)
 */
typedef const char* (*FConnectorGetType)
(CONNECTOR       connector
 );


/* Get the human readable connector's description (may be NULL on error)
 */
typedef char* (*FConnectorDescr)
(CONNECTOR       connector
 );


/* Open connection. Used to setup all related data structures,
 * but not necessarily has to actually open the data channel.
 */
typedef EIO_Status (*FConnectorOpen)
(CONNECTOR       connector,
 const STimeout* timeout
 );


/* Wait until either read or write (dep. on the "direction" value) becomes
 * available, or until "timeout" expires, or until error occurs.
 * NOTE 1:  FConnectorWait is guaranteed to be called after FConnectorOpen,
 *          and only if FConnectorOpen returned "eIO_Success".
 * NOTE 2:  "event" is guaranteed to be either "eIO_Read" or "eIO_Write".
 */
typedef EIO_Status (*FConnectorWait)
(CONNECTOR       connector,
 EIO_Event       event,
 const STimeout* timeout
 );


/* The passed "n_written" is always non-NULL, and "*n_written" is always zero.
 * It returns "eIO_Success" if at least some data have been successfully
 * written; other error code if no data at all have been written.
 * It returns the # of successfully written data (in bytes) in "*n_written".
 * NOTE:  FConnectorWrite is guaranteed to be called after FConnectorOpen,
 *        and only if the latter succeeded (returned "eIO_Success").
 */
typedef EIO_Status (*FConnectorWrite)
(CONNECTOR       connector,
 const void*     buf,
 size_t          size,
 size_t*         n_written,
 const STimeout* timeout
 );


/* Flush yet unwritten output data, if any.
 * NOTE:  FConnectorFlush is guaranteed to be called after FConnectorOpen,
 *        and only if the latter succeeded (returned "eIO_Success").
 */
typedef EIO_Status (*FConnectorFlush)
(CONNECTOR       connector,
 const STimeout* timeout
 );


/* The passed "n_read" is always non-NULL, and "*n_read" is always zero.
 * It returns "eIO_Success" if at least some data have been successfully
 * read; other error code if no data at all have been read.
 * The number of successfully read bytes returned in "*n_read".
 * NOTE:  FConnectorRead is guaranteed to be called after FConnectorOpen,
 *        and only if the latter succeeded (returned "eIO_Success").
 */
typedef EIO_Status (*FConnectorRead)
(CONNECTOR       connector,
 void*           buf,
 size_t          size,
 size_t*         n_read,
 const STimeout* timeout
 );

/* Obtain last I/O completion code from the transport level (connector).
 * NOTE 1:  FConnectorStatus is guaranteed to be called after FConnectorOpen,
 *          and only if the latter succeeded (returned "eIO_Success").
 * NOTE 2:  "direction" is guaranteed to be either "eIO_Read" or "eIO_Write".
 * NOTE 3:  Should return "eIO_Success" in case of inexistent (incomplete)
 *          low level transport, if any.
 */
typedef EIO_Status (*FConnectorStatus)
(CONNECTOR       connector,
 EIO_Event       direction
 );
          

/* Close data link (if any) and cleanup related data structures.
 * NOTE 1:  FConnectorClose is guaranteed to be called after FConnectorOpen,
 *          and only if the latter succeeded (returned "eIO_Success").
 * NOTE 2:  FConnectorFlush gets called before FConnectorClose automatically.
 */
typedef EIO_Status (*FConnectorClose)
(CONNECTOR       connector,
 const STimeout* timeout
 );


/* Standard set of connector methods to handle a connection (corresponding
 * connectors are also here), part of connection handle("CONN").
 */
typedef struct {
    FConnectorGetType   get_type;    CONNECTOR c_get_type;
    FConnectorDescr     descr;       CONNECTOR c_descr;
    FConnectorOpen      open;        CONNECTOR c_open;
    FConnectorWait      wait;        CONNECTOR c_wait;
#ifdef IMPLEMENTED__CONN_WaitAsync
    FConnectorWaitAsync wait_async;  CONNECTOR c_wait_async;
#endif
    FConnectorWrite     write;       CONNECTOR c_write;
    FConnectorFlush     flush;       CONNECTOR c_flush;
    FConnectorRead      read;        CONNECTOR c_read;
    FConnectorStatus    status;      CONNECTOR c_status;
    FConnectorClose     close;       CONNECTOR c_close;
    const STimeout*     default_timeout; /* default timeout pointer     */
    STimeout            default_tmo;     /* storage for default_timeout  */
    CONNECTOR           list;
} SMetaConnector;


#define CONN_TWO2ONE(a, b)   a##b

#define CONN_SET_METHOD(meta, method, function, connector) \
    do {                                                   \
        meta->method = function;                           \
        meta->CONN_TWO2ONE(c_,method) = connector;         \
    } while (0);


#define CONN_SET_DEFAULT_TIMEOUT(meta, timeout)            \
    do {                                                   \
        if (timeout) {                                     \
            meta->default_timeout = &meta->default_tmo;    \
            meta->default_tmo     = *timeout;              \
        } else                                             \
            meta->default_timeout = 0;                     \
    } while (0);


/* Insert a connector in the beginning of the connection's list of connectors.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status METACONN_Add
(SMetaConnector* meta,
 CONNECTOR       connector
 );


/* Delete given "connector" all its descendants (all connectors if "connector"
 * is 0) from the connections's list of connectors. FConnectorDestroy is
 * called for each removed connector.
 */
extern NCBI_XCONNECT_EXPORT EIO_Status METACONN_Remove
(SMetaConnector* meta,
 CONNECTOR       connector
 );


/* Upcall on request to setup virtual function table (called from connection).
 */
typedef void (*FSetupVTable)
(SMetaConnector* meta,
 CONNECTOR       connector
 );


/* Destroy connector and its data handle. This is NOT a close request!
 * Should not to be used on open connectors (that is, for those
 * FConnectorClose has to be called first prior to this call).
 */
typedef void (*FDestroy)
(CONNECTOR       connector
 );


/* Connector specification.
 */
typedef struct SConnectorTag {
    void*                handle;    /* data handle of the connector */
    CONNECTOR            next;      /* linked list                  */
    SMetaConnector*      meta;      /* back link to CONNECTION      */
    FSetupVTable         setup;     /* used in CONNECTION init      */
    FDestroy             destroy;   /* destroys handle, can be NULL */
} SConnector;


#ifdef IMPLEMENTED__CONN_WaitAsync
typedef struct {
  CONN                   conn;
  EIO_Event              event;
  FConnAsyncHandler      handler;
  void*                  data;
  FConnAsyncCleanup      cleanup;
} SConnectorAsyncHandler;

typedef void (*FConnectorAsyncHandler)
(SConnectorAsyncHandler* data,
 EIO_Event               event,
 EIO_Status              status
 );

typedef EIO_Status (*FConnectorWaitAsync)
(CONNECTOR               connector,
 FConnectorAsyncHandler  func,
 SConnectorAsyncHandler* data
 );
#endif /* IMPLEMENTED__CONN_WaitAsync */


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


/* @} */


/*
 * --------------------------------------------------------------------------
 * $Log: ncbi_connector.h,v $
 * Revision 1000.0  2003/10/29 16:29:56  gouriano
 * PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R6.16
 *
 * Revision 6.16  2003/08/25 14:47:59  lavr
 * Get rid of old ...TIMEOUT constants [now replaced with k...Timeout]
 *
 * Revision 6.15  2003/05/21 17:52:37  lavr
 * Pre- and post-conditions clarified for read and write virtual methods
 *
 * Revision 6.14  2003/05/14 03:47:53  lavr
 * +(*FConnectorDescr)()
 *
 * Revision 6.13  2003/04/09 17:58:45  siyan
 * Added doxygen support
 *
 * Revision 6.12  2003/01/08 01:59:32  lavr
 * DLL-ize CONNECT library for MSVC (add NCBI_XCONNECT_EXPORT)
 *
 * Revision 6.11  2002/09/19 18:00:11  lavr
 * Header file guard macro changed
 *
 * Revision 6.10  2002/09/06 15:40:54  lavr
 * More comments and notes to the API; log moved to end
 *
 * Revision 6.9  2002/04/26 16:29:32  lavr
 * Add default_timeout member to meta-connector
 *
 * Revision 6.8  2002/03/22 22:18:48  lavr
 * Cosmetic update
 *
 * Revision 6.7  2001/04/24 21:20:01  lavr
 * Introduced CONN_DEFAULT_TIMEOUT and CONN_INFINITE_TIMEOUT
 *
 * Revision 6.6  2001/03/02 20:07:18  lavr
 * Typos fixed
 *
 * Revision 6.5  2001/01/11 16:39:33  lavr
 * FDestroy function is now clearly documented not to destroy
 * the connector itself, only its handle (private internal data).
 *
 * Revision 6.4  2001/01/03 22:29:22  lavr
 * Changed IOStatus -> Status
 *
 * Revision 6.3  2000/12/29 17:45:07  lavr
 * Heavily modified to have a stack of connectors
 * VTable format changed; all virtual function now accept CONNECTOR as a
 * first argument (not void* as in previous versions)
 *
 * Revision 6.2  2000/04/07 19:59:49  vakatov
 * Moved forward-declaration of CONNECTOR from "ncbi_connection.h"
 * to "ncbi_connector.h"
 *
 * Revision 6.1  2000/03/24 22:52:48  vakatov
 * Initial revision
 *
 * ==========================================================================
 */

#endif /* CONNECT___NCBI_CONNECTOR__H */