ncbi_http_connector.h
上传用户:yhdzpy8989
上传日期:2007-06-13
资源大小:13604k
文件大小:10k
源码类别:

生物技术

开发平台:

C/C++

  1. /*
  2.  * ===========================================================================
  3.  * PRODUCTION $Log: ncbi_http_connector.h,v $
  4.  * PRODUCTION Revision 1000.0  2003/10/29 16:31:14  gouriano
  5.  * PRODUCTION PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R6.13
  6.  * PRODUCTION
  7.  * ===========================================================================
  8.  */
  9. #ifndef CONNECT___HTTP_CONNECTOR__H
  10. #define CONNECT___HTTP_CONNECTOR__H
  11. /*  $Id: ncbi_http_connector.h,v 1000.0 2003/10/29 16:31:14 gouriano Exp $
  12.  * ===========================================================================
  13.  *
  14.  *                            PUBLIC DOMAIN NOTICE
  15.  *               National Center for Biotechnology Information
  16.  *
  17.  *  This software/database is a "United States Government Work" under the
  18.  *  terms of the United States Copyright Act.  It was written as part of
  19.  *  the author's official duties as a United States Government employee and
  20.  *  thus cannot be copyrighted.  This software/database is freely available
  21.  *  to the public for use. The National Library of Medicine and the U.S.
  22.  *  Government have not placed any restriction on its use or reproduction.
  23.  *
  24.  *  Although all reasonable efforts have been taken to ensure the accuracy
  25.  *  and reliability of the software and data, the NLM and the U.S.
  26.  *  Government do not and cannot warrant the performance or results that
  27.  *  may be obtained by using this software or data. The NLM and the U.S.
  28.  *  Government disclaim all warranties, express or implied, including
  29.  *  warranties of performance, merchantability or fitness for any particular
  30.  *  purpose.
  31.  *
  32.  *  Please cite the author in any work or product based on this material.
  33.  *
  34.  * ===========================================================================
  35.  *
  36.  * Author:  Denis Vakatov
  37.  *
  38.  * File Description:
  39.  *   Implement CONNECTOR for the HTTP-based network connection
  40.  *
  41.  *   See in "ncbi_connector.h" for the detailed specification of the underlying
  42.  *   connector("CONNECTOR", "SConnectorTag") methods and structures.
  43.  *
  44.  */
  45. #include <connect/ncbi_connutil.h>
  46. /** @addtogroup Connectors
  47.  *
  48.  * @{
  49.  */
  50. #ifdef __cplusplus
  51. extern "C" {
  52. #endif
  53. /* Create new CONNECTOR structure to hit the specified URL using HTTP
  54.  * with either POST or GET method.
  55.  * Use the configuration values recorded in "net_info". If "net_info" is NULL,
  56.  * then use the default info (created by "ConnNetInfo_Create(0)").
  57.  *
  58.  * In order to workaround some HTTP communication features, this code does:
  59.  *  1) Accumulate all output data in an internal memory buffer until the
  60.  *     first "Read" (or "Peek", or "Close", or "Wait" on read) is attempted.
  61.  *  2) On the first "Read" (or "Peek", or "Close", or "Wait" on read), compose
  62.  *     and send the whole HTTP request as:
  63.  *        {POST|GET} <info->path>?<info->args> HTTP/1.0rn
  64.  *        <user_headerrn>
  65.  *        Content-Length: <accumulated_data_length>rn
  66.  *        rn
  67.  *        <accumulated_data>
  68.  *     NOTE:
  69.  *       if <user->header> is neither a NULL pointer nor an empty string, then:
  70.  *       - it must NOT contain "empty lines":  'rnrn';
  71.  *       - it must be terminated by a single 'rn';
  72.  *       - it gets inserted to the HTTP header "as is", without any
  73.  *         automatic checking or encoding.
  74.  *     After the request has been sent, reply data from the peer
  75.  *     CGI program are then can be actually read out.
  76.  *  4) On any "Write" operation. which follows data reading, the connection
  77.  *     to the peer CGI program is forcedly closed (the peer CGI process will
  78.  *     presumably die if has not done yet so), and data to be written are
  79.  *     again are stored in the buffer until next "Read" etc, see item 1).
  80.  *
  81.  *  *) If "fHCC_AutoReconnect" is set in "flags", then the connector makes
  82.  *     an automatic reconnect to the same CGI program with just the
  83.  *     same parameters, and micro-session steps (1,2,3) are repeated with
  84.  *     another instance of the CGI program.
  85.  *
  86.  *     If "fHCC_AutoReconnect" is not set then only one
  87.  *     "Write ... Write Read ... Read" micro-session is allowed, any
  88.  *     following "Write" attempt fails with error status "eIO_Closed".
  89.  *
  90.  *  Other flags:
  91.  *
  92.  *  fHCC_SureFlush --
  93.  *       make the connector to send at least the HTTP header on "CLOSE" and
  94.  *       re-"CONNECT", even if no data was written
  95.  *  fHCC_KeepHeader --
  96.  *       do not strip HTTP header (i.e. everything up to the first "rnrn",
  97.  *       including the "rnrn") from the CGI script's response
  98.  *  fHCC_UrlDecodeInput --
  99.  *       strip the HTTP header from the input data;  assume the input
  100.  *       data are single-part, URL-encoded;  perform the URL-decoding on read
  101.  *       NOTE:  this flag disables the "fHCC_KeepHeader" flag
  102.  *  fHCC_DropUnread --
  103.  *       do not collect incoming data in "Read" mode before switching into
  104.  *       "Write" mode for storing output data in buffer; by default all
  105.  *       data sent by the CGI program are stored even if not all requested
  106.  *       before "Write" following "Read" was issued (stream emulation)
  107.  *  fHCC_NoUpread --
  108.  *       do not do internal reading into temporary buffer while sending
  109.  *       data to CGI program; by default any send operation tries to
  110.  *       extract data(if any) coming back from the CGI program in order to
  111.  *       prevent connection blocking
  112.  *
  113.  * NOTE: the URL encoding/decoding (in the "fHCC_Url_*" cases and "info->args")
  114.  *       is performed by URL_Encode() and URL_Decode() -- "ncbi_connutil.[ch]".
  115.  */
  116. typedef enum {
  117.     fHCC_AutoReconnect    = 0x1,  /* see (*) above                           */
  118.     fHCC_SureFlush        = 0x2,  /* always send HTTP request on CLOSE/RECONN*/
  119.     fHCC_KeepHeader       = 0x4,  /* dont strip HTTP header from CGI response*/
  120.     fHCC_UrlDecodeInput   = 0x8,  /* strip HTTP header, URL-decode content   */
  121.     fHCC_UrlEncodeOutput  = 0x10, /* URL-encode all output data              */
  122.     fHCC_UrlCodec         = 0x18, /* fHCC_UrlDecodeInput | ...EncodeOutput   */
  123.     fHCC_UrlEncodeArgs    = 0x20, /* URL-encode "info->args"                 */
  124.     fHCC_DropUnread       = 0x40, /* each microsession drops yet unread data */
  125.     fHCC_NoUpread         = 0x80  /* do not use SOCK_ReadWhileWrite() at all */
  126. } EHCC_Flags;
  127. typedef int THCC_Flags;  /* binary OR of "EHttpCreateConnectorFlags"         */
  128. extern NCBI_XCONNECT_EXPORT CONNECTOR HTTP_CreateConnector
  129. (const SConnNetInfo* net_info,
  130.  const char*         user_header,
  131.  THCC_Flags          flags
  132.  );
  133. /* An extended version of URL_CreateConnector() to change the URL of the
  134.  * server CGI "on-the-fly":
  135.  *  -- "parse_http_hdr()" is called each time the HTTP header received
  136.  *      from HTTP server and only if fHCC_KeepHeader is NOT set; false return
  137.  *      value is equivalent of having an error from the HTTP server itself.
  138.  *  -- "adjust_net_info()" is invoked each time before starting a
  139.  *      new "HTTP micro-session" making a hit if the prior hit has failed;
  140.  *      it is passed "net_info" stored in the connector, and the number of
  141.  *      previously unsuccessful attempts since the connection was opened;
  142.  *      false return value terminates retry attempts.
  143.  *  -- "adjust_cleanup()" is called when the connector is being destroyed.
  144.  */
  145. typedef int/*bool*/ (*FHttpParseHTTPHeader)
  146. (const char* http_header,           /* HTTP header to parse, ''-terminated */
  147.  void*       adjust_data,           /* supplemental user data                */
  148.  int/*bool*/ server_error           /* true if HTTP server reported an error */
  149.  );
  150. typedef int/*bool*/ (*FHttpAdjustNetInfo)
  151. (SConnNetInfo* net_info,            /* net_info to adjust (in place)         */
  152.  void*         adjust_data,         /* supplemental user data                */
  153.  unsigned int  failure_count        /* how many failures since open          */
  154.  );
  155. typedef void (*FHttpAdjustCleanup)
  156. (void* adjust_data                  /* supplemental user data for cleanup    */
  157.  );
  158. extern NCBI_XCONNECT_EXPORT CONNECTOR HTTP_CreateConnectorEx
  159. (const SConnNetInfo*  net_info,
  160.  THCC_Flags           flags,
  161.  FHttpParseHTTPHeader parse_http_hdr, /* may be NULL, then no addtl. parsing */
  162.  FHttpAdjustNetInfo   adjust_net_info,/* may be NULL, then no adjustments    */
  163.  void*                adjust_data,    /* for "adjust_info" & "adjust_cleanup"*/
  164.  FHttpAdjustCleanup   adjust_cleanup  /* may be NULL                         */
  165. );
  166. #ifdef __cplusplus
  167. }  /* extern "C" */
  168. #endif
  169. /* @} */
  170. /*
  171.  * --------------------------------------------------------------------------
  172.  * $Log: ncbi_http_connector.h,v $
  173.  * Revision 1000.0  2003/10/29 16:31:14  gouriano
  174.  * PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R6.13
  175.  *
  176.  * Revision 6.13  2003/05/29 20:13:15  lavr
  177.  * -#include <connect/ncbi_connector.h>
  178.  *
  179.  * Revision 6.12  2003/04/09 19:05:44  siyan
  180.  * Added doxygen support
  181.  *
  182.  * Revision 6.11  2003/01/08 01:59:32  lavr
  183.  * DLL-ize CONNECT library for MSVC (add NCBI_XCONNECT_EXPORT)
  184.  *
  185.  * Revision 6.10  2002/09/19 18:06:39  lavr
  186.  * Additional blank line inserted after inclusion of headers
  187.  *
  188.  * Revision 6.9  2002/09/06 15:41:13  lavr
  189.  * Log moved to end
  190.  *
  191.  * Revision 6.8  2001/09/28 20:46:13  lavr
  192.  * Comments revised; parameter names adjusted
  193.  *
  194.  * Revision 6.7  2001/09/10 21:15:48  lavr
  195.  * Readability issue: FParseHTTPHdr -> FParseHTTPHeader
  196.  *
  197.  * Revision 6.6  2001/05/23 21:52:00  lavr
  198.  * +fHCC_NoUpread
  199.  *
  200.  * Revision 6.5  2001/01/25 16:53:22  lavr
  201.  * New flag for HTTP_CreateConnectorEx: fHCC_DropUnread
  202.  *
  203.  * Revision 6.4  2000/12/29 17:41:44  lavr
  204.  * Pretty printed; HTTP_CreateConnectorEx constructor interface changed
  205.  *
  206.  * Revision 6.3  2000/10/03 21:20:34  lavr
  207.  * Request method changed from POST to {GET|POST}
  208.  *
  209.  * Revision 6.2  2000/09/26 22:02:55  lavr
  210.  * HTTP request method added
  211.  *
  212.  * Revision 6.1  2000/04/21 19:40:58  vakatov
  213.  * Initial revision
  214.  *
  215.  * ==========================================================================
  216.  */
  217. #endif /* CONNECT___HTTP_CONNECTOR__H */