NCBI C++ ToolKit
Classes | Macros | Typedefs | Enumerations | Functions
Connectors
+ Collaboration diagram for Connectors:

Classes

struct  SCONN_Callback
 
struct  SMetaConnector
 Standard set of connector methods to handle a connection (corresponding connectors are also here), part of connection handle("CONN"). More...
 
struct  SConnectorTag
 Connector specification. More...
 
struct  SFILE_ConnAttr
 
struct  SFTP_Callback
 
struct  SSERVICE_Extra
 

Macros

#define CONN_N_CALLBACKS   6
 
#define _CONN_TWO2ONE(a, b)   a##b
 
#define CONN_SET_METHOD(meta, method, function, connector)
 
#define CONN_SET_DEFAULT_TIMEOUT(meta, timeout)
 
#define SERVICE_CreateConnector(service)   SERVICE_CreateConnectorEx(service, fSERV_Any, 0, 0)
 

Typedefs

typedef struct SConnectionTagCONN
 connection handle More...
 
typedef unsigned int TCONN_Flags
 bitwise OR of ECONN_Flag More...
 
typedef unsigned int TCONN_Callback
 
typedef EIO_Status(* FCONN_Callback) (CONN conn, TCONN_Callback type, void *data)
 
typedef struct SConnectorTagCONNECTOR
 connector handle More...
 
typedef const char *(* FConnectorGetType) (CONNECTOR connector)
 Get the name of the connector (may be NULL on error) More...
 
typedef char *(* FConnectorDescr) (CONNECTOR connector)
 Get the human readable connector's description (may be NULL on error) More...
 
typedef EIO_Status(* FConnectorOpen) (CONNECTOR connector, const STimeout *timeout)
 Open connection. More...
 
typedef EIO_Status(* FConnectorWait) (CONNECTOR connector, EIO_Event event, const STimeout *timeout)
 Wait until either read or write (dep. More...
 
typedef EIO_Status(* FConnectorWrite) (CONNECTOR connector, const void *buf, size_t size, size_t *n_written, const STimeout *timeout)
 Write to connector. More...
 
typedef EIO_Status(* FConnectorFlush) (CONNECTOR connector, const STimeout *timeout)
 Flush yet unwritten output data, if any. More...
 
typedef EIO_Status(* FConnectorRead) (CONNECTOR connector, void *buf, size_t size, size_t *n_read, const STimeout *timeout)
 Read from connector. More...
 
typedef EIO_Status(* FConnectorStatus) (CONNECTOR connector, EIO_Event direction)
 Obtain last I/O completion code from the transport level (connector). More...
 
typedef EIO_Status(* FConnectorClose) (CONNECTOR connector, const STimeout *timeout)
 Close data link (if any) and cleanup related data structures. More...
 
typedef void(* FSetupVTable) (CONNECTOR connector)
 Upcall on request to setup virtual function table (called from connection). More...
 
typedef void(* FDestroy) (CONNECTOR connector)
 Destroy connector and its data handle. More...
 
typedef struct SConnectorTag SConnector
 Connector specification. More...
 
typedef unsigned int TFTP_Flags
 
typedef EIO_Status(* FFTP_Callback) (void *data, const char *cmd, const char *arg)
 
typedef unsigned int THTTP_Flags
 Bitwise OR of EHTTP_Flag. More...
 
typedef unsigned int THCC_Flags
 bitwise OR of EHCC_Flag, deprecated More...
 
typedef EHTTP_HeaderParse(* FHTTP_ParseHeader) (const char *http_header, void *user_data, int server_error)
 
typedef int(* FHTTP_Adjust) (SConnNetInfo *net_info, void *user_data, unsigned int failure_count)
 
typedef void(* FHTTP_Cleanup) (void *user_data)
 
typedef void(* FHTTP_NcbiMessageHook) (const char *message)
 
typedef void(* FSERVICE_Reset) (void *data)
 
typedef void(* FSERVICE_Cleanup) (void *data)
 
typedef const SSERV_Info *(* FSERVICE_GetNextInfo) (void *data, SERV_ITER iter)
 

Enumerations

enum  ECONN_Flag { fCONN_Untie = 1, fCONN_Supplement = 64 }
 CONN flags should be kept compatible with CConn_IOStream::TConn_Flags. More...
 
enum  ECONN_Callback {
  eCONN_OnClose = 0, eCONN_OnRead = 1, eCONN_OnWrite = 2, eCONN_OnFlush = 3,
  eCONN_OnTimeout = 4, eCONN_OnOpen = 8
}
 Set user callback function to be invoked upon an event specified by the callback type. More...
 
enum  EFILE_ConnMode { eFCM_Truncate, eFCM_Append, eFCM_Seek }
 
enum  EFTP_Flag {
  fFTP_LogControl = 0x1, fFTP_LogData = 0x2, fFTP_LogAll = fFTP_LogControl | fFTP_LogData, fFTP_UseFeatures = 0x4,
  fFTP_NotifySize = 0x8, fFTP_UsePassive = 0x10, fFTP_UseActive = 0x20, fFTP_UseTypeL8 = 0x40,
  fFTP_UncleanIAC = 0x80, fFTP_IgnorePath = 0x100, fFTP_UncorkUpload = 0x200, fFTP_NoSizeChecks = 0x400,
  fFTP_NoExtensions = 0x800, fFTP_DelayRestart = 0x1000, fFTP_UseProxy = 0x2000
}
 
enum  EHTTP_Flag {
  fHTTP_AutoReconnect = 0x1, fHTTP_Flushable = 0x2, fHTTP_KeepHeader = 0x4, fHTTP_PushAuth = 0x10,
  fHTTP_WriteThru = 0x20, fHTTP_NoUpread = 0x40, fHTTP_DropUnread = 0x80, fHTTP_NoAutoRetry = 0x100,
  fHTTP_NoAutomagicSID = 0x200, fHTTP_UnsafeRedirects = 0x400, fHTTP_AdjustOnRedirect = 0x800, fHTTP_SuppressMessages = 0x1000
}
 
enum  EHCC_Flag { fHCC_UrlEncodeArgs = 0x8, fHCC_UrlDecodeInput = 0x10, fHCC_UrlEncodeOutput = 0x20, fHCC_UrlCodec = 0x30 }
 DEPRECATED, do not use! More...
 
enum  EHTTP_HeaderParse { eHTTP_HeaderError = 0, eHTTP_HeaderSuccess = 1, eHTTP_HeaderContinue = 2, eHTTP_HeaderComplete = 3 }
 The extended version HTTP_CreateConnectorEx() is able to track the HTTP response chain and also change the URL of the server "on-the-fly": More...
 

Functions

EIO_Status CONN_CreateEx (CONNECTOR connector, TCONN_Flags flags, CONN *conn)
 Create all data necessary to establish a new connection (merely bind it to the specified connector). More...
 
EIO_Status CONN_Create (CONNECTOR connector, CONN *conn)
 Same as CONN_CreateEx() called with 0 in the "flags" parameter. More...
 
EIO_Status CONN_ReInit (CONN conn, CONNECTOR connector)
 Reinit using new "connector". More...
 
const char * CONN_GetType (CONN conn)
 Get verbal representation of connection type as a character string. More...
 
char * CONN_Description (CONN conn)
 Return a human-readable description of the connection as a character '\0'-terminated string. More...
 
TNCBI_BigCount CONN_GetPosition (CONN conn, EIO_Event event)
 Get read ("event" == eIO_Read) or write ("event" == eIO_Write) position within the connection. More...
 
EIO_Status CONN_SetTimeout (CONN conn, EIO_Event event, const STimeout *timeout)
 Specify timeout for the connection I/O, including "Connect" (aka "Open") and "Close". More...
 
const STimeoutCONN_GetTimeout (CONN conn, EIO_Event event)
 Retrieve current timeout, return NULL(kInfiniteTimeout) if it is infinite. More...
 
EIO_Status CONN_Wait (CONN conn, EIO_Event event, const STimeout *timeout)
 Block on the connection until it becomes available for either reading or writing (depending on "event"), until timeout expires, or until any error. More...
 
EIO_Status CONN_Write (CONN conn, const void *buf, size_t size, size_t *n_written, EIO_WriteMethod how)
 
EIO_Status CONN_Pushback (CONN conn, const void *buf, size_t size)
 Push "size" bytes from the buffer "buf" back into connection. More...
 
EIO_Status CONN_Flush (CONN conn)
 Explicitly flush connection from any pending data written by CONN_Write(). More...
 
EIO_Status CONN_Read (CONN conn, void *buf, size_t size, size_t *n_read, EIO_ReadMethod how)
 
EIO_Status CONN_ReadLine (CONN conn, char *line, size_t size, size_t *n_read)
 Read up to "size" bytes from connection into the string buffer pointed to by "line". More...
 
EIO_Status CONN_Status (CONN conn, EIO_Event dir)
 Obtain status of the last I/O operation. More...
 
EIO_Status CONN_Close (CONN conn)
 Close the connection and destroy all relevant internal data. More...
 
EIO_Status CONN_SetCallback (CONN conn, ECONN_Callback type, const SCONN_Callback *new_cb, SCONN_Callback *old_cb)
 
EIO_Status CONN_GetSOCK (CONN conn, SOCK *sock)
 Get an underlying SOCK handle for connection that is implemented as a socket. More...
 
EIO_Status CONN_SetFlags (CONN conn, TCONN_Flags flags)
 Set connection processing flags. More...
 
TCONN_Flags CONN_GetFlags (CONN conn)
 Get connection processing flags currently in effect. More...
 
EIO_Status CONN_SetUserData (CONN conn, void *data)
 Associate an arbitraty user data pointer with the connection. More...
 
void * CONN_GetUserData (CONN conn)
 Get current value of the user's data pointer last associated with the connection, or NULL (if CONN is NULL or no pointer is currently set). More...
 
EIO_Status METACONN_Insert (SMetaConnector *meta, CONNECTOR connector)
 Insert a connector in the beginning of the connection's list of connectors. More...
 
EIO_Status METACONN_Remove (SMetaConnector *meta, CONNECTOR connector)
 Delete given "connector" all its descendants (all connectors if "connector" is 0) from the connections's list of connectors. More...
 
CONNECTOR FILE_CreateConnector (const char *ifname, const char *ofname)
 
CONNECTOR FILE_CreateConnectorEx (const char *ifname, const char *ofname, const SFILE_ConnAttr *attr)
 
CONNECTOR FTP_CreateConnectorSimple (const char *host, unsigned short port, const char *user, const char *pass, const char *path, TFTP_Flags flag, const SFTP_Callback *cmcb)
 
CONNECTOR FTP_CreateConnector (const SConnNetInfo *info, TFTP_Flags flag, const SFTP_Callback *cmcb)
 
CONNECTOR HTTP_CreateConnector (const SConnNetInfo *net_info, const char *user_header, THTTP_Flags flags)
 Same as HTTP_CreateConnector(net_info, flags, 0, 0, 0, 0) with the passed "user_header" overriding the value provided in "net_info->http_user_header". More...
 
CONNECTOR HTTP_CreateConnectorEx (const SConnNetInfo *net_info, THTTP_Flags flags, FHTTP_ParseHeader parse_header, void *user_data, FHTTP_Adjust adjust, FHTTP_Cleanup cleanup)
 Create new CONNECTOR structure to hit the specified URL using HTTP with either POST / GET (or ANY) method. More...
 
EIO_Status HTTP_CreateTunnelEx (const SConnNetInfo *net_info, THTTP_Flags flags, const void *data, size_t size, SOCK *sock)
 Create a tunnel to "net_info->host:net_info->port" via an HTTP proxy server located at "net_info->http_proxy_host:net_info->http_proxy_port". More...
 
EIO_Status HTTP_CreateTunnel (const SConnNetInfo *net_info, THTTP_Flags flags, SOCK *sock)
 Same as HTTP_CreateTunnelEx(net_info, flags, 0, 0, sock) More...
 
void HTTP_SetNcbiMessageHook (FHTTP_NcbiMessageHook)
 Set message hook procedure for messages originating from NCBI via HTTP. More...
 
CONNECTOR MEMORY_CreateConnector (void)
 
CONNECTOR MEMORY_CreateConnectorEx (BUF buf, unsigned int own_buf)
 
CONNECTOR NAMEDPIPE_CreateConnector (const string &pipename, size_t pipesize=0)
 Create CNamedPipe-based CONNECTOR. More...
 
CONNECTOR PIPE_CreateConnector (const string &cmd, const vector< string > &args, CPipe::TCreateFlags flags=0, CPipe *pipe=0, EOwnership own_pipe=eTakeOwnership, size_t pipe_size=0)
 Create CPipe-based CONNECTOR. More...
 
CONNECTOR SERVICE_CreateConnectorEx (const char *service, TSERV_Type types, const SConnNetInfo *net_info, const SSERVICE_Extra *extra)
 
CONNECTOR SOCK_CreateConnectorEx (const char *host, unsigned short port, unsigned short max_try, const void *data, size_t size, TSOCK_Flags flags)
 
CONNECTOR SOCK_CreateConnector (const char *host, unsigned short port, unsigned short max_try)
 
CONNECTOR SOCK_CreateConnectorOnTopEx (SOCK sock, unsigned short own_sock, const char *hostport)
 
CONNECTOR SOCK_CreateConnectorOnTop (SOCK sock, unsigned short own_sock)
 

Detailed Description

Macro Definition Documentation

#define _CONN_TWO2ONE (   a,
  b 
)    a##b

Definition at line 196 of file ncbi_connector.h.

#define CONN_N_CALLBACKS   6

Definition at line 387 of file ncbi_connection.h.

Referenced by CONN_SetCallback(), x_Callback(), and x_CB2IDX().

#define CONN_SET_DEFAULT_TIMEOUT (   meta,
  timeout 
)
Value:
do { \
if (timeout) { \
meta->default_tmo = *timeout; \
meta->default_timeout = &meta->default_tmo; \
} else \
meta->default_timeout = kInfiniteTimeout/*0*/; \
} while (0)
#define kInfiniteTimeout
Definition: ncbi_types.h:82
if(yy_accept[yy_current_state])

Definition at line 205 of file ncbi_connector.h.

Referenced by s_Setup().

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

Definition at line 198 of file ncbi_connector.h.

Referenced by s_Reset(), s_Setup(), and s_VT_Open().

#define SERVICE_CreateConnector (   service)    SERVICE_CreateConnectorEx(service, fSERV_Any, 0, 0)

Definition at line 77 of file ncbi_service_connector.h.

Typedef Documentation

typedef struct SConnectionTag* CONN

connection handle

Definition at line 64 of file ncbi_connection.h.

typedef struct SConnectorTag* CONNECTOR

connector handle

Definition at line 54 of file ncbi_connector.h.

typedef EIO_Status(* FCONN_Callback) (CONN conn, TCONN_Callback type, void *data)

Definition at line 391 of file ncbi_connection.h.

typedef EIO_Status(* FConnectorClose) (CONNECTOR connector, const STimeout *timeout)

Close data link (if any) and cleanup related data structures.

Note
FConnectorClose() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).
FConnectorFlush() gets called before FConnectorClose() automatically.
It may return eIO_Closed to indicate an unusual close condition.
The same connector may now be either re-opened / re-used or recylced.

Definition at line 170 of file ncbi_connector.h.

typedef char*(* FConnectorDescr) (CONNECTOR connector)

Get the human readable connector's description (may be NULL on error)

Definition at line 79 of file ncbi_connector.h.

typedef EIO_Status(* FConnectorFlush) (CONNECTOR connector, 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).

Definition at line 128 of file ncbi_connector.h.

typedef const char*(* FConnectorGetType) (CONNECTOR connector)

Get the name of the connector (may be NULL on error)

Definition at line 72 of file ncbi_connector.h.

typedef EIO_Status(* FConnectorOpen) (CONNECTOR connector, const STimeout *timeout)

Open connection.

Used to setup all related data structures, but not necessarily has to actually open the data channel.

Note
Regardless of the returned status, the connection is considered open (so this call doesn't get re-issued) after this call returns.

Definition at line 89 of file ncbi_connector.h.

typedef EIO_Status(* FConnectorRead) (CONNECTOR connector, void *buf, size_t size, size_t *n_read, const STimeout *timeout)

Read from connector.

The passed "n_read" is always non-NULL, and "*n_read" is always zero. The number of bytes actually read bytes gets returned in "*n_read". It may not return eIO_Success if no data at all have been read.

Note
FConnectorRead() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).

Definition at line 141 of file ncbi_connector.h.

typedef EIO_Status(* FConnectorStatus) (CONNECTOR connector, EIO_Event direction)

Obtain last I/O completion code from the transport level (connector).

Note
FConnectorStatus() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).
"direction" is guaranteed to be either eIO_Read or eIO_Write.
Should return eIO_Success in case of inexistent (incomplete) low level transport, if any.

Definition at line 157 of file ncbi_connector.h.

typedef EIO_Status(* FConnectorWait) (CONNECTOR connector, EIO_Event event, 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
FConnectorWait() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).
The passed "event" is guaranteed to be either eIO_Read or eIO_Write.

Definition at line 101 of file ncbi_connector.h.

typedef EIO_Status(* FConnectorWrite) (CONNECTOR connector, const void *buf, size_t size, size_t *n_written, const STimeout *timeout)

Write to connector.

The passed "n_written" is always non-NULL, and "*n_written" is always zero. The number of bytes actually written gets returned in "*n_written". It may not return eIO_Success if no data at all have been written.

Note
FConnectorWrite() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).

Definition at line 115 of file ncbi_connector.h.

typedef void(* FDestroy) (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 must be called prior to this call).

Definition at line 247 of file ncbi_connector.h.

typedef EIO_Status(* FFTP_Callback) (void *data, const char *cmd, const char *arg)

Definition at line 289 of file ncbi_ftp_connector.h.

typedef int(* FHTTP_Adjust) (SConnNetInfo *net_info,void *user_data,unsigned int failure_count)

Definition at line 221 of file ncbi_http_connector.h.

typedef void(* FHTTP_Cleanup) (void *user_data)

Definition at line 227 of file ncbi_http_connector.h.

typedef void(* FHTTP_NcbiMessageHook) (const char *message)

Definition at line 349 of file ncbi_http_connector.h.

typedef EHTTP_HeaderParse(* FHTTP_ParseHeader) (const char *http_header,void *user_data,int server_error)

Definition at line 215 of file ncbi_http_connector.h.

typedef void(* FSERVICE_Cleanup) (void *data)

Definition at line 55 of file ncbi_service_connector.h.

typedef const SSERV_Info*(* FSERVICE_GetNextInfo) (void *data, SERV_ITER iter)

Definition at line 56 of file ncbi_service_connector.h.

typedef void(* FSERVICE_Reset) (void *data)

Definition at line 54 of file ncbi_service_connector.h.

typedef void(* FSetupVTable) (CONNECTOR connector)

Upcall on request to setup virtual function table (called from connection).

NB: May not detect any failures (follow up in Open to fail if necessary).

Definition at line 238 of file ncbi_connector.h.

typedef struct SConnectorTag SConnector

Connector specification.

typedef unsigned int TCONN_Callback

Definition at line 389 of file ncbi_connection.h.

typedef unsigned int TCONN_Flags

bitwise OR of ECONN_Flag

Definition at line 73 of file ncbi_connection.h.

typedef unsigned int TFTP_Flags

Definition at line 70 of file ncbi_ftp_connector.h.

typedef unsigned int THCC_Flags

bitwise OR of EHCC_Flag, deprecated

Definition at line 156 of file ncbi_http_connector.h.

typedef unsigned int THTTP_Flags

Bitwise OR of EHTTP_Flag.

Definition at line 139 of file ncbi_http_connector.h.

Enumeration Type Documentation

Set user callback function to be invoked upon an event specified by the callback type.

Note that the callback function gets always called prior to the event to happen, e.g. the eCONN_OnClose callback is called when the connection is about to close, but has not yet been closed.

The callback function is supplied with 3 arguments: the connection handle, a type of event (except for eCONN_OnTimeout), and a user data (specified when the callback was set). When eCONN_OnTimeout callback occurs, the callback type eCONN_OnTimeout gets OR'ed with I/O direction, which has timed out: eIO_Open (when opening), eIO_Read, eIO_Write, or both (when flushing), then passed in the "type" argument.
CONN_SetCallback() stores previous callback in "old_cb" (if it is not NULL).
The callbacks remain valid until they are explicitly changed / de-activated or the connection becomes closed.
This also means that if a callback is intercepted and then relayed to an old handler, the interceptor may not always assume the callback remains set, and so in general must reinstate itself upon each upcall of the old handler.
Normally, callback would return eIO_Success and let the operation continue; non-eIO_Success return value causes it to be returned to the caller level (but possibly with some processing already completed by then, e.g. such as a partial read for eCONN_OnRead from an internal connection buffer).
Note
eIO_Interrupt returned from the callback switches connection into a cancelled state irreversibly, causing any further I/O for this handle to fail with eIO_Interrupt.
non-eIO_Success from an eCONN_OnClose callback cannot postpone the connection closure (but the error code is still passed through to the user).
by returning eIO_Success, eCONN_OnTimeout restarts the I/O that has timed out (except for open).
eCONN_OnTimeout for connection open is only called if eCONN_OnOpen was also set for that connection.
See also
CONN_Read, CONN_Write, CONN_Close
Enumerator
eCONN_OnClose 

NB: CONN has been flushed prior to the call.

eCONN_OnRead 

Read from connector is about to occur.

eCONN_OnWrite 

Write to connector is about to occur.

eCONN_OnFlush 

About to be flushed (NB: == eIO_ReadWrite)

eCONN_OnTimeout 

Connector I/O has timed out.

eCONN_OnOpen 

Call prior to open (NB: "conn" still closed)

Definition at line 379 of file ncbi_connection.h.

enum ECONN_Flag

CONN flags should be kept compatible with CConn_IOStream::TConn_Flags.

Enumerator
fCONN_Untie 

do not call flush method prior to every read

fCONN_Supplement 

supplement I/O with extended return codes

Definition at line 69 of file ncbi_connection.h.

Enumerator
eFCM_Truncate 
eFCM_Append 
eFCM_Seek 

Definition at line 67 of file ncbi_file_connector.h.

enum EFTP_Flag
Enumerator
fFTP_LogControl 
fFTP_LogData 
fFTP_LogAll 
fFTP_UseFeatures 
fFTP_NotifySize 
fFTP_UsePassive 
fFTP_UseActive 
fFTP_UseTypeL8 
fFTP_UncleanIAC 
fFTP_IgnorePath 
fFTP_UncorkUpload 
fFTP_NoSizeChecks 
fFTP_NoExtensions 
fFTP_DelayRestart 
fFTP_UseProxy 

Definition at line 53 of file ncbi_ftp_connector.h.

enum EHCC_Flag

DEPRECATED, do not use!

Enumerator
fHCC_UrlEncodeArgs 

NB: Error-prone semantics, do not use!

fHCC_UrlDecodeInput 

Obsolete, may not work, do not use!

Assume the response body as single-part, URL-encoded; perform the URL-decoding on read, and deliver decoded data to the user.

Obsolete.

fHCC_UrlEncodeOutput 

Obsolete, may not work, do not use!

fHCC_UrlCodec 

fHCC_UrlDecodeInput | ...EncodeOutput

Definition at line 142 of file ncbi_http_connector.h.

enum EHTTP_Flag
Enumerator
fHTTP_AutoReconnect 

See HTTP_CreateConnectorEx()

fHTTP_Flushable 

Connector will really flush on Flush()

HTTP connector flags.

HTTP/1.0 or when fHTTP_WriteThru is not set: by default all data written to the connection are kept until read begins (even though CONN_Flush() might have been called in between the writes); with this flag set, CONN_Flush() will result the data to be actually sent to the server side, so the following write will form a new request, and not get added to the previous one; also this flag assures that the connector sends at least an HTTP header on "CLOSE" and re-"CONNECT", even if no data for HTTP body have been written.

HTTP/1.1 and when fHTTP_WriteThru is set: CONN_Flush() attempts to send all pending data down to server.

fHTTP_KeepHeader 

Keep HTTP header (see limitations)

Do not strip HTTP header (i.e.

everything up to the first "\r\n\r\n", including the "\r\n\r\n") from the CGI script's response (including any server error, which then is made available for reading as well) *NOTE* this flag disables automatic authorization and redirection.

fHTTP_PushAuth 

HTTP/1.1 pushes out auth if present.

fHTTP_WriteThru 

HTTP/1.1 writes through (chunked)

Valid only with HTTP/1.1: Connection to the server is made upon a first CONN_Write(), or CONN_Flush() if fHTTP_Flushable is set, or CONN_Wait(eIO_Write), and each CONN_Write() forms a chunk of HTTP data to be sent to the server.

Reading / waiting for read from the connector finalizes the body and, if reading, fetches the response.

fHTTP_NoUpread 

Do not use SOCK_SetReadOnWrite()

Do *not* do internal reading into temporary buffer while sending data to HTTP server; by default any send operation tries to fetch data as they are coming back from the server in order to prevent stalling due to data clogging the connection.

fHTTP_DropUnread 

Each microsession drops unread data.

Do not collect incoming data in "Read" mode before switching into "Write" mode for preparing next request; by default all data sent by the server get stored even if not all of it had been requested prior to a "Write" following a "Read" was issued (stream emulation).

fHTTP_NoAutoRetry 

No auto-retries allowed.

Do not attempt any auto-retries in case of failing connections (this flag effectively means having SConnNetInfo::max_try set to 1).

fHTTP_NoAutomagicSID 

Do not add NCBI SID automagically.

fHTTP_UnsafeRedirects 

Any redirect will be honored.

For security reasons the following redirects comprise security risk, and thus, are prohibited: switching from https to http, and/or re-POSTing data (regardless of the transport, either http or https); this flag allows such redirects (when encountered) to be honored.

Note
URL encoding/decoding (in the "fHCC_Url*" cases and "net_info->args") is performed by URL_Encode() and URL_Decode() – see "ncbi_connutil.[ch]".
See also
SConnNetInfo, ConnNetInfo_OverrideUserHeader, URL_Encode, URL_Decode
fHTTP_AdjustOnRedirect 

Call adjust routine for redirects, too.

fHTTP_SuppressMessages 

Most annoying ones reduced to traces.

Definition at line 121 of file ncbi_http_connector.h.

The extended version HTTP_CreateConnectorEx() is able to track the HTTP response chain and also change the URL of the server "on-the-fly":

  • FHTTP_ParseHeader() gets called every time a new HTTP response header is received from the server, and only if fHTTP_KeepHeader is NOT set. Return code from the parser adjusts the existing server error condition (if any) as the following: + eHTTP_HeaderError: unconditionally flag a server error; + eHTTP_HeaderSuccess: header parse successful, retain existing condition (note that in case of an already existing server error condition the response body can be logged but will not be made available for the user code to read, and eIO_Unknown will result on read); + eHTTP_HeaderContinue: if there was already a server error condition, the response body will be made available for the user code to read (but only if HTTP connector cannot post-process the request such as for redirects, authorization etc); otherwise, this code has the same effect as eHTTP_HeaderSuccess; + eHTTP_HeaderComplete: flag this request as processed completely, and do not do any post-processing (such as redirects, authorization etc), yet make the response body (if any, and regardless of whether there was a server error or not) available for reading.
  • FHTTP_Adjust() gets invoked every time before starting a new "HTTP micro-session" making a hit when a previous hit has failed; it is passed "net_info" as stored within the connector, and the number of previously unsuccessful consecutive attempts (in the least significant word) since the connection was opened, pass 0 in that parameter if calling for redirects (when fHTTP_AdjustOnRedirect was set); a zero (false) return value ends the retries;
  • FHTTP_Cleanup() gets called when the connector is about to be destroyed; "user_data" is guaranteed not to be referenced anymore (so this is a good place to clean up "user_data" if necessary).
    See also
    SConnNetInfo::max_try
Enumerator
eHTTP_HeaderError 

Parse failed, treat as a server error.

eHTTP_HeaderSuccess 

Parse succeeded, retain server status.

eHTTP_HeaderContinue 

Parse succeeded, continue with body.

eHTTP_HeaderComplete 

Parse succeeded, no more processing.

Definition at line 208 of file ncbi_http_connector.h.

Function Documentation

EIO_Status CONN_Close ( CONN  conn)

Close the connection and destroy all relevant internal data.

Note
Whatever the error code is returned, the connection handle "conn" will have become invalid (so, it should not be used anymore).
See also
CONN_Create
Parameters
[in]connconnection handle

Definition at line 1113 of file ncbi_connection.c.

References SConnectionTag::buf, BUF_Destroy(), CONN_NOT_NULL, SConnectionTag::data, eIO_Closed, eIO_Success, SConnectionTag::magic, and x_ReInit().

Referenced by s_CONN_Destroy(), s_Open(), s_Resolve(), and CConn_Streambuf::x_Close().

EIO_Status CONN_Create ( CONNECTOR  connector,
CONN conn 
)

Same as CONN_CreateEx() called with 0 in the "flags" parameter.

Parameters
[in]connectorconnector
[out]connhandle of the created connection

Definition at line 437 of file ncbi_connection.c.

References CONN_CreateEx().

Referenced by CreateAsnConn_ServiceEx(), s_CONN_Create(), s_Open(), and s_Resolve().

EIO_Status CONN_CreateEx ( CONNECTOR  connector,
TCONN_Flags  flags,
CONN conn 
)

Create all data necessary to establish a new connection (merely bind it to the specified connector).

Unsuccessful completion sets "*conn" to NULL, and leaves the connector intact (can be used again).

Note
Connection is not established right away but at the moment of the first call to one of "Flush", "Wait", "Write", or "Read" methods.
"Connection establishment" at this level of abstraction may differ from actual link establishment at the underlying connector's level.
Initial timeout values are set to kDefaultTimeout, meaning that connector-specific timeouts are in force for the connection.
See also
CONN_Close
Parameters
[in]connectorconnector
[in]flagsconnection flags
[out]connhandle of the created connection

Definition at line 397 of file ncbi_connection.c.

References assert, SConnectionTag::c_timeout, conn, CONN_CALLTRACE, CONN_LOG, CONNECTION_MAGIC, eCONN_Unusable, eIO_InvalidArg, eIO_Success, eIO_Unknown, eLOG_Error, fCONN_Flush, SConnectionTag::flags, int, kDefaultTimeout, SConnectionTag::magic, SConnectionTag::o_timeout, SConnectionTag::r_timeout, SConnectionTag::state, SConnectionTag::w_timeout, and x_ReInit().

Referenced by CConn_Streambuf::CConn_Streambuf(), and CONN_Create().

char* CONN_Description ( CONN  conn)

Return a 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 must call free() to deallocate space occupied by the returned string when the description is no longer needed.

Parameters
[in]connconnection handle

Definition at line 463 of file ncbi_connection.c.

References SMetaConnector::c_descr, CONN_NOT_NULL_EX, SMetaConnector::descr, eCONN_Unusable, SMetaConnector::list, SConnectionTag::meta, and SConnectionTag::state.

Referenced by CReaderServiceConnector::GetConnDescription(), CConn_IOStream::GetDescription(), CId2FetchApp::x_InitConnection(), and CConn_Streambuf::x_Message().

EIO_Status CONN_Flush ( CONN  conn)

Explicitly flush connection from any pending data written by CONN_Write().

Note
CONN_Flush() effectively opens connection (if it wasn't open yet).
Connection considered open if underlying connector's "Open" method has successfully executed; an actual data link may not yet exist.
CONN_Read() always calls CONN_Flush() before proceeding (unless the connection was created with fCONN_Untie); so does CONN_Close() but only if the connection is already open.
See also
CONN_Read, CONN_Write, CONN_Close
Parameters
[in]connconnection handle

Definition at line 800 of file ncbi_connection.c.

References assert, CONN_LOG, CONN_NOT_NULL, SMetaConnector::default_timeout, eCONN_Open, eIO_Success, eIO_Timeout, eLOG_Warning, SMetaConnector::flush, kDefaultTimeout, SMetaConnector::list, SConnectionTag::meta, s_Open(), SConnectionTag::state, SConnectionTag::w_status, SConnectionTag::w_timeout, and x_Flush().

Referenced by CConn_Streambuf::overflow(), s_Open(), and s_Resolve().

TCONN_Flags CONN_GetFlags ( CONN  conn)

Get connection processing flags currently in effect.

Returns
Current value of the flags.
See also
CONN_CreateEx, CONN_SetFlags
Parameters
[in]connconnection handle

Definition at line 1204 of file ncbi_connection.c.

References CONN_CALLTRACE, fCONN_Flush, and SConnectionTag::flags.

TNCBI_BigCount CONN_GetPosition ( CONN  conn,
EIO_Event  event 
)

Get read ("event" == eIO_Read) or write ("event" == eIO_Write) position within the connection.

Positions are advanced from 0 on, and only concerning I/O that has caused calling to the actual connector's "read" (i.e. pushbacks never considered, and peeks – not always) and "write" methods. Special case: eIO_Open as "event" causes to clear both positions with 0, and to return 0.

Parameters
[in]connconnection handle
[in]eventsee description

Definition at line 472 of file ncbi_connection.c.

References assert, CONN_LOG_EX, CONN_NOT_NULL_EX, eIO_Open, eIO_Read, eIO_Write, eLOG_Error, SConnectionTag::r_pos, and SConnectionTag::w_pos.

Referenced by s_FtpCallback(), CDownloadJob::x_Download(), and CDownloadJob::x_DownloadAndExtract().

EIO_Status CONN_GetSOCK ( CONN  conn,
SOCK sock 
)

Get an underlying SOCK handle for connection that is implemented as a socket.

Non-eIO_Success return code guarantees "*sock" is NULL. Set "*sock" to NULL when no socket handle can be obtained.

Note
The returned SOCK object remains in use by the connection.
See also
SOCK, SOCK_GetOSHandleEx
Parameters
[in]connconnection handle
[out]socknon-NULL, to get the SOCK to

Definition at line 1159 of file ncbi_connection.c.

References assert, SMetaConnector::c_get_type, CONN_NOT_NULL, eCONN_Open, eIO_Closed, eIO_InvalidArg, eIO_Success, g_kNcbiSockNameAbbr, SMetaConnector::get_type, SConnectorTag::handle, if(), SMetaConnector::list, SConnectionTag::meta, SConnectorTag::meta, s_Open(), and SConnectionTag::state.

Referenced by CConn_IOStream::CConn_IOStream(), CConn_ServiceStream::GetSOCK(), and x_GetSOCK().

const STimeout* CONN_GetTimeout ( CONN  conn,
EIO_Event  event 
)

Retrieve current timeout, return NULL(kInfiniteTimeout) if it is infinite.

The returned pointer is guaranteed to point to a valid timeout structure, or to be either NULL or kDefaultTimeout until next CONN_SetTimeout() or CONN_Close().

Parameters
[in]connconnection handle
[in]eventI/O direction, not "eIO_ReadWrite"!

Definition at line 555 of file ncbi_connection.c.

References assert, SConnectionTag::c_timeout, CONN_LOG_EX, CONN_NOT_NULL_EX, eIO_Close, eIO_Open, eIO_Read, eIO_ReadWrite, eIO_Write, eLOG_Error, eLOG_Warning, SConnectionTag::o_timeout, SConnectionTag::r_timeout, and SConnectionTag::w_timeout.

Referenced by CConn_FtpStream::Drain(), CConn_IOStream::GetTimeout(), and CConn_Streambuf::showmanyc().

const char* CONN_GetType ( CONN  conn)

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.

Parameters
[in]connconnection handle

Definition at line 454 of file ncbi_connection.c.

References SMetaConnector::c_get_type, CONN_NOT_NULL_EX, eCONN_Unusable, SMetaConnector::get_type, SMetaConnector::list, SConnectionTag::meta, and SConnectionTag::state.

Referenced by CConn_IOStream::GetType(), and CConn_Streambuf::x_Message().

void* CONN_GetUserData ( CONN  conn)

Get current value of the user's data pointer last associated with the connection, or NULL (if CONN is NULL or no pointer is currently set).

Returns
Current value of the user pointer.
See also
CONN_Create, CONN_SetUserData
Parameters
[in]connconnection handle

Definition at line 1224 of file ncbi_connection.c.

References CONN_CALLTRACE, and SConnectionTag::data.

EIO_Status CONN_Pushback ( CONN  conn,
const void *  buf,
size_t  size 
)

Push "size" bytes from the buffer "buf" back into connection.

Return eIO_Success on success, other code on error.

Note
The data pushed back may not necessarily be the same as previously obtained from the connection.
Upon a following read operation, the pushed back data are taken out first.
Pushback data can desynchronize underlying connector (so use wisely).
See also
CONN_Read, CONN_Write
Parameters
[in]connconnection handle
[in]bufpointer to the data being pushed back
[in]size# of bytes to push back

Definition at line 780 of file ncbi_connection.c.

References SConnectionTag::buf, BUF_Pushback(), CONN_NOT_NULL, eCONN_Open, eCONN_Unusable, eIO_Closed, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_Unknown, SConnectionTag::meta, SMetaConnector::read, and SConnectionTag::state.

Referenced by s_CONN_IO().

EIO_Status CONN_Read ( CONN  conn,
void *  buf,
size_t  size,
size_t *  n_read,
EIO_ReadMethod  how 
)
EIO_Status CONN_ReadLine ( CONN  conn,
char *  line,
size_t  size,
size_t *  n_read 
)

Read up to "size" bytes from connection into the string buffer pointed to by "line".

Stop reading if either '
' or an error is encountered. Replace '
' 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 up and "*n_read" is equal to "size" upon return - this is the only case when "line" will not be '\0'-terminated.

Return code advises the caller whether another read can be attempted: * eIO_Success – read completed successfully, keep reading; * other code – an error occurred, and further read attempt may fail.

This call utilizes eIO_Read timeout as set by CONN_SetTimeout().

See also
CONN_Read, CONN_SetTimeout
Parameters
[in]connconnection handle
[out]linebuffer to read to
[in]sizebuffer size
[out]n_readline length

Definition at line 1001 of file ncbi_connection.c.

References assert, SConnectionTag::buf, BUF_Pushback(), BUF_Size(), CONN_LOG_EX, CONN_NOT_NULL, done, eCONN_Bad, eCONN_Open, eIO_InvalidArg, eIO_Success, eIO_Unknown, eLOG_Critical, fCONN_Flush, fCONN_Untie, SConnectionTag::flags, i, len, SMetaConnector::list, SConnectionTag::meta, SConnectionTag::r_status, SConnectionTag::r_timeout, ReadLine(), s_CONN_Read(), s_Open(), size, SConnectionTag::state, x_Flush(), and x_size().

EIO_Status CONN_ReInit ( CONN  conn,
CONNECTOR  connector 
)

Reinit using new "connector".

If "conn" is already opened, then close the current connection first, even if "connector" is just the same as the current connector. If "connector" is NULL, then close and destroy the incumbent, and leave the 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 in "Create".
See also
CONN_Create, CONN_Close
Parameters
[in]connconnection handle
[in]connectornew connector

Definition at line 445 of file ncbi_connection.c.

References CONN_NOT_NULL, and x_ReInit().

EIO_Status CONN_SetCallback ( CONN  conn,
ECONN_Callback  type,
const SCONN_Callback new_cb,
SCONN_Callback old_cb 
)
Parameters
[in]connconnection to set callback for
[in]typecallback type
[in]new_cbcallback to set (NULL to reset)
[out]old_cbto save old callback at (may be 0)

Definition at line 1130 of file ncbi_connection.c.

References SConnectionTag::cb, CONN_LOG_EX, CONN_N_CALLBACKS, CONN_NOT_NULL, eIO_InvalidArg, eIO_Success, eLOG_Error, and x_CB2IDX().

Referenced by s_AsnSetCloseCb(), s_FtpCallback(), CConn_IOStream::SetCanceledCallback(), CConn_Streambuf::x_Close(), CDownloadJob::x_Download(), CDownloadJob::x_DownloadAndExtract(), and CConn_Streambuf::x_Init().

EIO_Status CONN_SetFlags ( CONN  conn,
TCONN_Flags  flags 
)

Set connection processing flags.

Returns
eIO_Success on success, other error code on error.
See also
CONN_CreateEx, CONN_GetFlags
Parameters
[in]connconnection handle
[in]flagsnew connection flags

Definition at line 1190 of file ncbi_connection.c.

References CONN_CALLTRACE, eIO_InvalidArg, eIO_Success, fCONN_Flush, SConnectionTag::flags, and flags.

EIO_Status CONN_SetTimeout ( CONN  conn,
EIO_Event  event,
const STimeout timeout 
)

Specify timeout for the connection I/O, including "Connect" (aka "Open") and "Close".

May be called at any time during the connection lifetime.

Note
If "timeout" is NULL then set the timeout to be infinite.
If "timeout" is kDefaultTimeout then an underlying, connector-specific value is used (this is the default).
Parameters
[in]connconnection handle
[in]eventI/O direction
[in]timeoutnew timeout

Definition at line 500 of file ncbi_connection.c.

References SConnectionTag::c_timeout, SConnectionTag::cc_timeout, CONN_LOG_EX, CONN_NOT_NULL, eIO_Close, eIO_InvalidArg, eIO_Open, eIO_Read, eIO_ReadWrite, eIO_Success, eIO_Write, eLOG_Error, kDefaultTimeout, SConnectionTag::o_timeout, SConnectionTag::oo_timeout, SConnectionTag::r_timeout, SConnectionTag::rr_timeout, SConnectionTag::w_timeout, and SConnectionTag::ww_timeout.

Referenced by CConn_FtpStream::Drain(), s_Open(), CConn_IOStream::SetTimeout(), CConn_Streambuf::showmanyc(), CId2Reader::x_ConnectAtSlot(), CId1Reader::x_ConnectAtSlot(), and CConn_Streambuf::x_Init().

EIO_Status CONN_SetUserData ( CONN  conn,
void *  data 
)

Associate an arbitraty user data pointer with the connection.

The pointer is not used by the connection itself but is retrievable with CONN_GetUserData() from the user's code as long as the CONN handle remains valid. Successive calls to CONN_SetUserData() replace the pointer value.

Returns
eIO_Success on success, other error code on error.
See also
CONN_Create, CONN_GetUserData
Parameters
[in]connconnection handle
[in]datauser data pointer

Definition at line 1212 of file ncbi_connection.c.

References CONN_CALLTRACE, SConnectionTag::data, eIO_InvalidArg, and eIO_Success.

EIO_Status CONN_Status ( CONN  conn,
EIO_Event  dir 
)

Obtain status of the last I/O operation.

This is NOT a completion code of the last CONN call, but rather some status from a lower level connector's layer (if available).

Special case: eIO_Open as "dir" checks whether the connection is in
an open state (which means the underlying connector has been successfully opened, but does not assure/check availability for any data or I/O), and returns eIO_Success if it is, or an error code otherwise.
See also
CONN_Create, CONN_Read, CONN_Write, CONN_Flush
Parameters
[in]connconnection handle
[in]direIO_Read or eIO_Write

Definition at line 1076 of file ncbi_connection.c.

References assert, SMetaConnector::c_status, CONN_NOT_NULL, eCONN_Cancel, eCONN_Open, eCONN_Unusable, eIO_Closed, eIO_Interrupt, eIO_InvalidArg, eIO_NotSupported, eIO_Open, eIO_Read, eIO_Success, eIO_Write, SConnectionTag::meta, SConnectionTag::r_status, SConnectionTag::state, SMetaConnector::status, and SConnectionTag::w_status.

Referenced by CConn_IOStream::CConn_IOStream(), CConn_Streambuf::Status(), and CConn_Streambuf::x_Close().

EIO_Status CONN_Wait ( CONN  conn,
EIO_Event  event,
const STimeout timeout 
)

Block on the connection until it becomes available for either reading or writing (depending on "event"), until timeout expires, or until any error.

Note
"timeout" can also be one of the two special values: * NULL (for infinite timeout, also known as kInfiniteTimeout); * kDefaultTimeout (connector-defined).
See also
CONN_Read, CONN_Write
Parameters
[in]connconnection handle
[in]eventcan only be either of eIO_Read, IO_Write
[in]timeoutthe maximal wait time

Definition at line 594 of file ncbi_connection.c.

References assert, SConnectionTag::buf, BUF_Size(), SMetaConnector::c_wait, CONN_LOG, CONN_NOT_NULL, eCONN_Open, eIO_Closed, eIO_Interrupt, eIO_InvalidArg, eIO_NotSupported, eIO_Read, eIO_Success, eIO_Timeout, eIO_Write, eLOG_Error, eLOG_Trace, eLOG_Warning, kDefaultTimeout, SMetaConnector::list, SConnectionTag::meta, s_Open(), STimeoutTag::sec, SConnectionTag::state, STimeoutTag::usec, and SMetaConnector::wait.

Referenced by CConnTest::CheckFWConnections(), CReaderServiceConnector::Connect(), CConnTest::ExtraCheckOnFailure(), CConn_HttpStream::Fetch(), CConn_ServiceStream::Fetch(), CConn_Streambuf::showmanyc(), and CId2FetchApp::x_InitConnection().

EIO_Status CONN_Write ( CONN  conn,
const void *  buf,
size_t  size,
size_t *  n_written,
EIO_WriteMethod  how 
)
Parameters
[in]connconnection handle
[in]bufpointer to the data buffer to write
[in]size# of bytes to write
[out]n_writtennon-NULL, # of actually written bytes
[in]howeIO_WritePlain or eIO_WritePersist

Definition at line 741 of file ncbi_connection.c.

References assert, CONN_NOT_NULL, eCONN_Open, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_WritePersist, eIO_WritePlain, fCONN_Supplement, SConnectionTag::flags, SMetaConnector::list, SConnectionTag::meta, s_CONN_Write(), s_CONN_WritePersist(), s_Open(), SConnectionTag::state, SConnectionTag::w_status, and Write().

Referenced by CConn_FtpStream::Drain(), CConn_Streambuf::overflow(), s_AsnWrite(), and CConn_Streambuf::xsputn().

CONNECTOR FILE_CreateConnector ( const char *  ifname,
const char *  ofname 
)

Definition at line 346 of file ncbi_file_connector.c.

References FILE_CreateConnectorEx(), and NULL.

CONNECTOR FILE_CreateConnectorEx ( const char *  ifname,
const char *  ofname,
const SFILE_ConnAttr attr 
)
CONNECTOR FTP_CreateConnector ( const SConnNetInfo info,
TFTP_Flags  flag,
const SFTP_Callback cmcb 
)

Definition at line 2360 of file ncbi_ftp_connector.c.

References s_CreateConnector().

Referenced by s_FtpConnectorBuilder().

CONNECTOR FTP_CreateConnectorSimple ( const char *  host,
unsigned short  port,
const char *  user,
const char *  pass,
const char *  path,
TFTP_Flags  flag,
const SFTP_Callback cmcb 
)

Definition at line 2348 of file ncbi_ftp_connector.c.

References s_CreateConnector().

CONNECTOR HTTP_CreateConnector ( const SConnNetInfo net_info,
const char *  user_header,
THTTP_Flags  flags 
)

Same as HTTP_CreateConnector(net_info, flags, 0, 0, 0, 0) with the passed "user_header" overriding the value provided in "net_info->http_user_header".

See also
HTTP_CreateConnectorEx, ConnNetInfo_OverrideUserHeader

Definition at line 2508 of file ncbi_http_connector.c.

References s_CreateConnector().

CONNECTOR HTTP_CreateConnectorEx ( const SConnNetInfo net_info,
THTTP_Flags  flags,
FHTTP_ParseHeader  parse_header,
void *  user_data,
FHTTP_Adjust  adjust,
FHTTP_Cleanup  cleanup 
)

Create new CONNECTOR structure to hit the specified URL using HTTP with either POST / GET (or ANY) method.

Use the configuration values stored in "net_info". If "net_info" is NULL, then use the default info as created by ConnNetInfo_Create(0).

If "net_info" does not explicitly specify an HTTP request method (i.e. it has it as "eReqMethod_Any"), then the actual method sent to the HTTP server depends on whether any data has been written to the connection with CONN_Write(): the presence of pending data will cause a POST request (with a "Content-Length:" tag supplied automatically and reflecting the total pending data size), and GET request method will result in the absence of any data. An explicit value for the request method will cause the specified request to be used regardless of pending data, and will flag an error if any data will have to be sent with a GET (per the standard).

When not using HTTP/1.1's fHTTP_WriteThru mode, in order to work around some HTTP communication features, this code does:

1. Accumulate all output data in an internal memory buffer until the first CONN_Read() (including peek) or CONN_Wait(on read) is attempted (also see fHTTP_Flushable flag below). 2. On the first CONN_Read() or CONN_Wait(on read), compose and send the whole HTTP request as:

*        METHOD <net_info->path>?<net_info->args> HTTP/1.0\r\n
*        <user_header\r\n>
*        Content-Length: <accumulated_data_length>\r\n
*        \r\n
*        <accumulated_data>
*        
Note
If <user_header> is neither a NULL pointer nor an empty string, then:
  • it must NOT contain any "empty lines": "\r\n\r\n";
  • multiple tags must be separated by "\r\n" (*not* just "\n");
  • it should be terminated by a single "\r\n" (will be added, if not);
  • it gets inserted to the HTTP header "as is", without any automatic checking and / or encoding (except for the trailing "\r\n");
  • the "user_header" specified in the arguments overrides any user header that can be provided via the "net_info" argument, see ConnNetInfo_OverrideUserHeader() from <connect/ncbi_connutil.h>.
Data may depart to the server side earlier if CONN_Flush()'ed in a fHTTP_Flushable connector, see "flags". 3. After the request has been sent, then the response data from the peer (usually, a CGI program) can be actually read out. 4. On a CONN_Write() operation, which follows data reading, the connection to the peer is read out until EOF (the data stored internally) then forcedly closed (the peer CGI process will presumably die if it has not done so yet on its own), and data to be written again get stored in the buffer until next "Read" etc, see item 1). The subsequent read will first see the leftovers (if any) of data stored previously, then the new data generated in response to the latest request. The behavior can be changed by the fHTTP_DropUnread flag.

When fHTTP_WriteThru is set with HTTP/1.1, writing to the connector begins upon any write operations, and reading from the connector causes the request body to finalize and response to be fetched from the server. Request method must be explicitly specified with fHTTP_WriteThru, "ANY" does not get accepted (the eIO_NotSupported error returned).

Note
If "fHTTP_AutoReconnect" is set in "flags", then the connector makes an automatic reconnect to the same URL with just the same parameters for each micro-session steps (1,2,3) repeated.
If "fHTTP_AutoReconnect" is not set then only a single "Write ... Write Read ... Read" micro-session is allowed, and any following write attempt fails with "eIO_Closed".
See also
EHTTP_Flag
Parameters
parse_headermay be NULL, then no addtl. parsing
user_datauser data for HTTP CBs (callbacks)
adjustmay be NULL
cleanupmay be NULL

Definition at line 2517 of file ncbi_http_connector.c.

References s_CreateConnector().

Referenced by s_CreateConnectorHttp(), s_HttpConnectorBuilder(), s_Open(), and s_Resolve().

EIO_Status HTTP_CreateTunnel ( const SConnNetInfo net_info,
THTTP_Flags  flags,
SOCK sock 
)

Same as HTTP_CreateTunnelEx(net_info, flags, 0, 0, sock)

Definition at line 2590 of file ncbi_http_connector.c.

References HTTP_CreateTunnelEx().

Referenced by s_Connect(), and s_SocketConnectorBuilder().

EIO_Status HTTP_CreateTunnelEx ( const SConnNetInfo net_info,
THTTP_Flags  flags,
const void *  data,
size_t  size,
SOCK sock 
)

Create a tunnel to "net_info->host:net_info->port" via an HTTP proxy server located at "net_info->http_proxy_host:net_info->http_proxy_port".

Return the tunnel as a socket via the last parameter. For compatibility with future API extensions, please make sure *sock is NULL when making the call. The proxy gets contacted via HTTPS if "net_info->scheme == eURL_Https", and the resultant socket is returned secure (with the SSL session still active).

Note
"net_info" can be passed as NULL to be constructed from the environment.
Some HTTP proxies do not process "data" correctly (e.g. Squid 3) when sent along with the tunnel creation request (despite the standard specifically allows such use), so they may require separate SOCK I/O calls to write the data to the tunnel.
Returns
eIO_Success if the tunnel has been successfully created; otherwise, return an error code and set "*sock" to NULL upon return.
See also
THTTP_Flags, SOCK_CreateEx, SOCK_Close
Parameters
datainitial data block to send via the tunnel
sizesize of the initial data block

Definition at line 2530 of file ncbi_http_connector.c.

References SConnNetInfo::args, assert, BUF_Prepend(), BUF_Size(), SHttpConnector::conn_state, eCS_ReadBody, eEM_Wait, eIO_Closed, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_Unknown, fHTTP_DropUnread, SHttpConnector::http_code, SHttpConnector::net_info, s_CreateHttpConnector(), s_DestroyHttpConnector(), s_DropConnection(), s_PreRead(), SHttpConnector::sock, SConnNetInfo::timeout, and SHttpConnector::w_buf.

Referenced by HTTP_CreateTunnel().

void HTTP_SetNcbiMessageHook ( FHTTP_NcbiMessageHook  )

Set message hook procedure for messages originating from NCBI via HTTP.

Any hook will be called not more than once. Until no hook is installed, and exactly one message is caught, a warning will be generated in the standard log file upon acceptance of every message.

Definition at line 2598 of file ncbi_http_connector.c.

References s_MessageHook, and s_MessageIssued.

CONNECTOR MEMORY_CreateConnector ( void  )

Definition at line 241 of file ncbi_memory_connector.c.

References MEMORY_CreateConnectorEx().

CONNECTOR MEMORY_CreateConnectorEx ( BUF  buf,
unsigned int  own_buf 
)
EIO_Status METACONN_Insert ( SMetaConnector meta,
CONNECTOR  connector 
)

Insert a connector in the beginning of the connection's list of connectors.

Calls connector's FSetupVTable, which must be defined.

Definition at line 85 of file ncbi_connector.c.

References assert, eIO_Success, eIO_Unknown, eLOG_Error, SMetaConnector::list, SConnectorTag::meta, METACONN_LOG, SConnectorTag::next, and SConnectorTag::setup.

Referenced by s_VT_Open(), and x_ReInit().

EIO_Status METACONN_Remove ( SMetaConnector meta,
CONNECTOR  connector 
)

Delete given "connector" all its descendants (all connectors if "connector" is 0) from the connections's list of connectors.

FDestroy (if defined) gets called for each removed connector.

Definition at line 49 of file ncbi_connector.c.

References assert, SConnectorTag::destroy, eIO_Success, eIO_Unknown, eLOG_Error, SMetaConnector::list, SConnectorTag::meta, METACONN_LOG, and SConnectorTag::next.

Referenced by s_Close(), and x_ReInit().

CONNECTOR NAMEDPIPE_CreateConnector ( const string pipename,
size_t  pipesize = 0 
)

Create CNamedPipe-based CONNECTOR.

Create new CONNECTOR structure to handle a data transfer between two process over nemed pipe. Return NULL on error.

Parameters
pipesizeuse default

Definition at line 194 of file ncbi_namedpipe_connector.cpp.

References SConnectorTag::destroy, SConnectorTag::handle, SConnectorTag::meta, SConnectorTag::next, SNamedPipeConnector::pipe, SNamedPipeConnector::pipename, SNamedPipeConnector::pipesize, s_Destroy(), s_Setup(), and SConnectorTag::setup.

CONNECTOR PIPE_CreateConnector ( const string cmd,
const vector< string > &  args,
CPipe::TCreateFlags  flags = 0,
CPipe pipe = 0,
EOwnership  own_pipe = eTakeOwnership,
size_t  pipe_size = 0 
)

Create CPipe-based CONNECTOR.

Create new CONNECTOR structure to handle data transfer between two processes over interprocess pipe. Return NULL on error.

Parameters
own_pipeonly if "pipe" given
pipe_sizeuse default

Definition at line 218 of file ncbi_pipe_connector.cpp.

References SPipeConnector::args, cmd, SPipeConnector::cmd, SConnectorTag::destroy, eTakeOwnership, SPipeConnector::flags, flags, SConnectorTag::handle, SConnectorTag::meta, SConnectorTag::next, SPipeConnector::own_pipe, SPipeConnector::pipe, SPipeConnector::pipe_size, s_Destroy(), s_Setup(), and SConnectorTag::setup.

Referenced by s_PipeConnectorBuilder().

CONNECTOR SERVICE_CreateConnectorEx ( const char *  service,
TSERV_Type  types,
const SConnNetInfo net_info,
const SSERVICE_Extra extra 
)
CONNECTOR SOCK_CreateConnector ( const char *  host,
unsigned short  port,
unsigned short  max_try 
)

Definition at line 364 of file ncbi_socket_connector.c.

References fSOCK_LogDefault, and s_Init().

CONNECTOR SOCK_CreateConnectorEx ( const char *  host,
unsigned short  port,
unsigned short  max_try,
const void *  data,
size_t  size,
TSOCK_Flags  flags 
)

Definition at line 373 of file ncbi_socket_connector.c.

References s_Init().

CONNECTOR SOCK_CreateConnectorOnTop ( SOCK  sock,
unsigned short  own_sock 
)

Definition at line 385 of file ncbi_socket_connector.c.

References s_Init().

CONNECTOR SOCK_CreateConnectorOnTopEx ( SOCK  sock,
unsigned short  own_sock,
const char *  hostport 
)

Definition at line 393 of file ncbi_socket_connector.c.

References s_Init().

Referenced by s_SocketConnectorBuilder().

Modified on Sun Nov 19 16:43:49 2017 by modify_doxy.py rev. 546573