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

Classes

struct  SCONN_Callback
 
struct  SMetaConnector
 Standard set of connector methods to handle a connection (corresponding connectors are also in here), part of the 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_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 NOT be NULL) 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 (depending on the "event" value) becomes available, or until "timeout" expires, or until error occurs. 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 *data, size_t size)
 Push "size" bytes from the buffer "data" 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 a 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 NULL) 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 *init_data, size_t init_size, void *user_data, FHTTP_Adjust adjust, 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, 0, 0, sock) More...
 
void HTTP_SetNcbiMessageHook (FHTTP_NcbiMessageHook)
 Set a 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)
 

Variables

FCONN_Callback SCONN_Callback::func
 function address to call on the event More...
 
void * SCONN_Callback::data
 data to pass to the callback as its last arg More...
 
const STimeout g_NcbiDefConnTimeout
 DEF_CONN_TIMEOUT as STimeout. More...
 
FConnectorGetType SMetaConnector::get_type
 
CONNECTOR SMetaConnector::c_get_type
 
FConnectorDescr SMetaConnector::descr
 
CONNECTOR SMetaConnector::c_descr
 
FConnectorOpen SMetaConnector::open
 
CONNECTOR SMetaConnector::c_open
 
FConnectorWait SMetaConnector::wait
 
CONNECTOR SMetaConnector::c_wait
 
FConnectorWrite SMetaConnector::write
 
CONNECTOR SMetaConnector::c_write
 
FConnectorFlush SMetaConnector::flush
 
CONNECTOR SMetaConnector::c_flush
 
FConnectorRead SMetaConnector::read
 
CONNECTOR SMetaConnector::c_read
 
FConnectorStatus SMetaConnector::status
 
CONNECTOR SMetaConnector::c_status
 
FConnectorClose SMetaConnector::close
 
CONNECTOR SMetaConnector::c_close
 
const STimeoutSMetaConnector::default_timeout
 default timeout pointer More...
 
STimeout SMetaConnector::default_tmo
 storage for default_timeout More...
 
CONNECTOR SMetaConnector::list
 
SMetaConnectorSConnectorTag::meta
 back link to original meta More...
 
FSetupVTable SConnectorTag::setup
 init meta, may not be NULL More...
 
FDestroy SConnectorTag::destroy
 destroys handle, can be NULL More...
 
void * SConnectorTag::handle
 data handle of the connector More...
 
CONNECTOR SConnectorTag::next
 linked list More...
 
EFILE_ConnMode SFILE_ConnAttr::w_mode
 
TNCBI_BigCount SFILE_ConnAttr::w_pos
 
TNCBI_BigCount SFILE_ConnAttr::r_pos
 
FFTP_Callback SFTP_Callback::func
 
void * SFTP_Callback::data
 
void * SSERVICE_Extra::data
 
FSERVICE_Reset SSERVICE_Extra::reset
 
FHTTP_Adjust SSERVICE_Extra::adjust
 
FSERVICE_Cleanup SSERVICE_Extra::cleanup
 
FHTTP_ParseHeader SSERVICE_Extra::parse_header
 
FSERVICE_GetNextInfo SSERVICE_Extra::get_next_info
 
THTTP_Flags SSERVICE_Extra::flags
 

Detailed Description

Macro Definition Documentation

◆ CONN_N_CALLBACKS

#define CONN_N_CALLBACKS   6

Definition at line 478 of file ncbi_connection.h.

◆ CONN_SET_DEFAULT_TIMEOUT

#define CONN_SET_DEFAULT_TIMEOUT (   meta,
  timeout 
)
Value:
do { \
if (timeout == kDefaultTimeout) { \
meta->default_timeout = &g_NcbiDefConnTimeout; \
} else if (timeout) { \
meta->default_tmo = *timeout; \
meta->default_timeout = &meta->default_tmo; \
} else \
meta->default_timeout = kInfiniteTimeout/*0*/; \
} while (0)
const STimeout g_NcbiDefConnTimeout
DEF_CONN_TIMEOUT as STimeout.
Definition: ncbi_connutil.c:54
#define kInfiniteTimeout
Definition: ncbi_types.h:82
#define kDefaultTimeout
Definition: ncbi_types.h:81

Definition at line 215 of file ncbi_connector.h.

◆ CONN_SET_METHOD

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

Definition at line 208 of file ncbi_connector.h.

◆ SERVICE_CreateConnector

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

Definition at line 77 of file ncbi_service_connector.h.

Typedef Documentation

◆ CONN

typedef struct SConnectionTag* CONN

connection handle

Definition at line 64 of file ncbi_connection.h.

◆ CONNECTOR

typedef struct SConnectorTag* CONNECTOR

connector handle

Definition at line 54 of file ncbi_connector.h.

◆ FCONN_Callback

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

Definition at line 482 of file ncbi_connection.h.

◆ FConnectorClose

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

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

Note
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 / reused or recycled.
FConnectorClose() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).

Definition at line 181 of file ncbi_connector.h.

◆ FConnectorDescr

typedef char*(* FConnectorDescr) (CONNECTOR connector)

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

Definition at line 82 of file ncbi_connector.h.

◆ FConnectorFlush

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 133 of file ncbi_connector.h.

◆ FConnectorGetType

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

Get the name of the connector (may NOT be NULL)

Definition at line 75 of file ncbi_connector.h.

◆ FConnectorOpen

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 92 of file ncbi_connector.h.

◆ FConnectorRead

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. Upon return, the number of bytes actually read must get reflected in "*n_read", and it may never be greater than "size".

Warning
This call may not return eIO_Success if no data at all have been read (unless "size" was passed 0).
Note
This call should use the eIO_Closed return code solely to indicate true EOF in data; and never for other read errors (such as transport or medium issues of any sort, like being unable to open a file or an underlying connection, if any; or being unable to negotiate).
FConnectorRead() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).

Definition at line 152 of file ncbi_connector.h.

◆ FConnectorStatus

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

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

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

Definition at line 168 of file ncbi_connector.h.

◆ FConnectorWait

typedef EIO_Status(* FConnectorWait) (CONNECTOR connector, EIO_Event event, const STimeout *timeout)

Wait until either read or write (depending on the "event" value) becomes available, or until "timeout" expires, or until error occurs.

Note
The passed "event" is guaranteed to be either eIO_Read or eIO_Write.
FConnectorWait() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).

Definition at line 104 of file ncbi_connector.h.

◆ FConnectorWrite

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. Upon return, the number of bytes actually written must get reflected in "*n_written", and it may never be greater than "size".

Warning
This call may not return eIO_Success if no data at all have been written (unless "size" was passed as 0).
Note
FConnectorWrite() is guaranteed to be called after FConnectorOpen(), and only if the latter succeeded (returned eIO_Success).

Definition at line 120 of file ncbi_connector.h.

◆ FDestroy

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 258 of file ncbi_connector.h.

◆ FFTP_Callback

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

Definition at line 301 of file ncbi_ftp_connector.h.

◆ FHTTP_Adjust

typedef int(* FHTTP_Adjust) (SConnNetInfo *net_info, void *user_data, unsigned int failure_count)
Parameters
net_infonet_info to adjust (in place)
user_datasupplemental user data
failure_countlow word: # of failures since open

Definition at line 248 of file ncbi_http_connector.h.

◆ FHTTP_Cleanup

typedef void(* FHTTP_Cleanup) (void *user_data)
Parameters
user_datasupplemental user data

Definition at line 254 of file ncbi_http_connector.h.

◆ FHTTP_NcbiMessageHook

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

Definition at line 385 of file ncbi_http_connector.h.

◆ FHTTP_ParseHeader

typedef EHTTP_HeaderParse(* FHTTP_ParseHeader) (const char *http_header, void *user_data, int server_error)
Parameters
http_headerHTTP header to parse
user_datasupplemental user data
server_error!= 0 if HTTP error (NOT 2xx code)

Definition at line 236 of file ncbi_http_connector.h.

◆ FSERVICE_Cleanup

typedef void(* FSERVICE_Cleanup) (void *data)

Definition at line 55 of file ncbi_service_connector.h.

◆ FSERVICE_GetNextInfo

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

Definition at line 56 of file ncbi_service_connector.h.

◆ FSERVICE_Reset

typedef void(* FSERVICE_Reset) (void *data)

Definition at line 54 of file ncbi_service_connector.h.

◆ FSetupVTable

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 249 of file ncbi_connector.h.

◆ SConnector

typedef struct SConnectorTag SConnector

Connector specification.

◆ TCONN_Callback

typedef unsigned int TCONN_Callback

Definition at line 480 of file ncbi_connection.h.

◆ TCONN_Flags

typedef unsigned int TCONN_Flags

bitwise OR of ECONN_Flag

Definition at line 73 of file ncbi_connection.h.

◆ TFTP_Flags

typedef unsigned int TFTP_Flags

Definition at line 70 of file ncbi_ftp_connector.h.

◆ THCC_Flags

typedef unsigned int THCC_Flags

bitwise OR of EHCC_Flag, deprecated

Definition at line 162 of file ncbi_http_connector.h.

◆ THTTP_Flags

typedef unsigned int THTTP_Flags

Bitwise OR of EHTTP_Flag.

Definition at line 145 of file ncbi_http_connector.h.

Enumeration Type Documentation

◆ ECONN_Callback

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 a 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 caller).
by returning eIO_Success, eCONN_OnTimeout restarts the I/O that has timed out (with possibly eCONN_OnOpen, eCONN_OnRead, eCONN_OnWrite, or eCONN_OnFlush callbacks invoked again, if they are set).
eCONN_OnTimeout for connection open is only called if eCONN_OnOpen was also set for that connection.
there's no timeout callback on connection close – if timeout occurs, the connection is still closed with eIO_Timeout status.
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 470 of file ncbi_connection.h.

◆ ECONN_Flag

enum ECONN_Flag

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

Enumerator
fCONN_Untie 

do not call flush method prior to reading

fCONN_Supplement 

supplement I/O with extended return codes

Definition at line 69 of file ncbi_connection.h.

◆ EFILE_ConnMode

Enumerator
eFCM_Truncate 
eFCM_Append 
eFCM_Seek 

Definition at line 67 of file ncbi_file_connector.h.

◆ EFTP_Flag

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.

◆ EHCC_Flag

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 148 of file ncbi_http_connector.h.

◆ EHTTP_Flag

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 incomning HTTP 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.

Present credentials to the server if they are set in the connection parameters when sending 1st request.

Normally, the credentials are only presented on a retry when the server rejects the initial request with 401 / 407. This saves a hit, but is only honored with HTTP/1.1.

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 have been requested prior to a "Write" that followed data reading (stream emulation).

fHTTP_NoAutoRetry 

No auto-retries allowed.

Do not attempt any auto-retries in case of failing connections (this flag effectively overrides SConnNetInfo::max_try with 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 127 of file ncbi_http_connector.h.

◆ EHTTP_HeaderParse

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" (e.g. to make a hit when a previous hit has failed, to follow a redirect, or to change a URL to hit next). It is passed the live "net_info" exactly as stored within the connector, and: 1. a positive number of previously unsuccessful consecutive attempts (in the least significant word of "failure_count") since the connector was successfully opened; or 2. 0 in "failure_count" if being called for a redirect (when fHTTP_AdjustOnRedirect was set); or 3. -1 in "failure_count" if the callback is invoked when a new request is about to be made (as a solicitaiton of new URL for the hit, if any available). A zero (false) return value ends the request/retries and issues an error. A non-zero continues with the request: an advisory value of greater than 0 means an adjustment was made, and a negative value indicates no changes (and in case "3" above would not initiate any subsequent new request). If a new HTTP request is started as a result of the callback, the updated SConnNetInfo parameters ("net_info") are going to be used.
  • 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 230 of file ncbi_http_connector.h.

Function Documentation

◆ CONN_Close()

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 1162 of file ncbi_connection.c.

References BUF_Destroy(), conn, CONN_NOT_NULL, eIO_Success, free(), and x_ReInit().

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

◆ CONN_Create()

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 457 of file ncbi_connection.c.

References conn, and CONN_CreateEx().

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

◆ CONN_CreateEx()

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 "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.
CONN does not buffer any output data, but passes it directly to the underlying CONNECTOR. CONN may buffer input data internally, but only in the following circumstances: CONN_Read() with "peek", CONN_ReadLine(), or CONN_Pushback().
See also
CONN_Close
Parameters
[in]connectorconnector
[in]flagsconnection flags
[out]connhandle of the created connection

Definition at line 417 of file ncbi_connection.c.

References assert, calloc(), conn, CONN_CALLTRACE, CONN_LOG, CONNECTION_MAGIC, eCONN_Unusable, eIO_InvalidArg, eIO_Success, eIO_Unknown, eLOG_Error, fCONN_Flush, flags, free(), int, kDefaultTimeout, and x_ReInit().

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

◆ CONN_Description()

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 the space occupied by the returned string when the description is no longer needed.

Parameters
[in]connconnection handle

Definition at line 484 of file ncbi_connection.c.

References conn, CONN_NOT_NULL_EX, and eCONN_Unusable.

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

◆ CONN_Flush()

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 833 of file ncbi_connection.c.

References assert, conn, CONN_LOG, CONN_NOT_NULL, eCONN_Open, eIO_Success, eIO_Timeout, eLOG_Trace, eLOG_Warning, kDefaultTimeout, s_Open(), and x_Flush().

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

◆ CONN_GetFlags()

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 1257 of file ncbi_connection.c.

References conn, CONN_CALLTRACE, and fCONN_Flush.

◆ CONN_GetPosition()

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, for every successive byte of data, and only consider I/O that has caused calling the actual CONNECTOR's "read" (i.e. pushbacks never counted, 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 493 of file ncbi_connection.c.

References assert, conn, CONN_LOG_EX, CONN_NOT_NULL_EX, eIO_Open, eIO_Read, eIO_Write, and eLOG_Error.

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

◆ CONN_GetSOCK()

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.

Warning
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 1209 of file ncbi_connection.c.

References assert, SMetaConnector::c_get_type, conn, CONN_NOT_NULL, eCONN_Open, eIO_InvalidArg, eIO_Success, g_kNcbiSockNameAbbr, SMetaConnector::get_type, SConnectorTag::handle, if(), SConnectorTag::meta, s_Open(), and util::strcmp().

Referenced by CRPCClient< TRequest, TReply >::AsyncConnect(), CConn_IOStream::GetSOCK(), and CConn_Streambuf::x_Init().

◆ CONN_GetTimeout()

const STimeout* CONN_GetTimeout ( CONN  conn,
EIO_Event  event 
)

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

Parameters
eventCan be one of eIO_Open, eIO_Read, eIO_Write, and eIO_Close. In case of the event specified as eIO_ReadWrite, the current read timeout gets actually returned with a warning logged.
Returns
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().
See also
CONN_SetTimeout
Parameters
[in]connconnection handle
[in]eventI/O direction, not "eIO_ReadWrite"!

Definition at line 576 of file ncbi_connection.c.

References assert, conn, CONN_LOG_EX, CONN_NOT_NULL_EX, eIO_Close, eIO_Open, eIO_Read, eIO_ReadWrite, eIO_Write, eLOG_Error, and eLOG_Warning.

Referenced by CConn_FtpStream::Drain(), CConn_Streambuf::Fetch(), CConn_IOStream::GetTimeout(), CConn_Streambuf::overflow(), CConn_Streambuf::showmanyc(), CConn_Streambuf::underflow(), CConn_Streambuf::x_Close(), CConn_Streambuf::x_Read(), and CConn_Streambuf::xsputn().

◆ CONN_GetType()

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 475 of file ncbi_connection.c.

References conn, CONN_NOT_NULL_EX, and eCONN_Unusable.

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

◆ CONN_GetUserData()

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 1277 of file ncbi_connection.c.

References conn, and CONN_CALLTRACE.

◆ CONN_Pushback()

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

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

Return eIO_Success on success (including when pushing back nothing if "size" is zero – the "data" pointer is ignored then), 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 most recently pushed back data are taken out first.
As the pushback data do not actually go back into the underlying CONNECTOR (but stored internally into a pending input buffer of CONN), that can desynchronize the CONNECTOR (so use it wisely).
See also
CONN_Read, CONN_ReadLine
Parameters
[in]connconnection handle
[in]datapointer to the data being pushed back
[in]size# of bytes to push back

Definition at line 808 of file ncbi_connection.c.

References assert, BUF_Pushback(), conn, CONN_NOT_NULL, data, eCONN_Open, eCONN_Unusable, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_Unknown, and ncbi::grid::netcache::search::fields::size.

Referenced by CConn_Streambuf::Pushback(), s_CONN_IO(), and CConn_Streambuf::x_Pushback().

◆ CONN_Read()

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

◆ CONN_ReadLine()

EIO_Status CONN_ReadLine ( CONN  conn,
char *  line,
size_t  size,
size_t *  n_read 
)

Read up to "size" bytes from connection into a 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 stored in "line", not including the terminating '\0'. If there was not enough space provided in "line" to accomodate the '\0'-termination, then all "size" bytes are used up, and "*n_read" is equal to "size" upon return - this is the _only_ case when "line" is _not_ be '\0'-terminated.

Return code advises the caller whether another read can be attempted: * eIO_Success – read completed successfully ('
' is seen or the buffer has been filled up completely), keep reading; * other code – an error occurred, and further read attempt may fail.

Note
This call may cause some data read from the underlying CONNECTOR to be stored in an internal pending input buffer of CONN.

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

See also
CONN_SetTimeout, CONN_Read, CONN_PushBack
Parameters
[in]connconnection handle
[out]linebuffer to read to, non-NULL
[in]sizebuffer size (may not be 0)
[out]n_readline length, may not be NULL

Definition at line 1035 of file ncbi_connection.c.

References assert, BUF_Pushback(), BUF_Size(), conn, CONN_LOG_EX, CONN_NOT_NULL, done, eCONN_Corrupt, eCONN_Open, eIO_InvalidArg, eIO_Success, eIO_Unknown, eLOG_Critical, fCONN_Flush, fCONN_Supplement, fCONN_Untie, i, len, ReadLine(), s_CONN_Read(), s_Open(), ncbi::grid::netcache::search::fields::size, x_Flush(), and x_size().

Referenced by xx_LoadLocalIPs().

◆ CONN_ReInit()

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 465 of file ncbi_connection.c.

References conn, CONN_NOT_NULL, and x_ReInit().

◆ CONN_SetCallback()

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 1178 of file ncbi_connection.c.

References assert, conn, 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().

◆ CONN_SetFlags()

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 1243 of file ncbi_connection.c.

References conn, CONN_CALLTRACE, eIO_InvalidArg, eIO_Success, fCONN_Flush, and flags.

◆ CONN_SetTimeout()

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.

Parameters
eventCan be one of eIO_Open, eIO_Read, eIO_ReadWrite, eIO_Write, and eIO_Close. In case of eIO_ReadWrite, the timeout value updates both read and write timeouts simultaneously, effectively equivalent to making this call twice with eIO_Read and eIO_Write events, respectively.
Note
If "timeout" is NULL (aka kInfiniteTimeout) then set the timeout to be infinite.
If "timeout" is kDefaultTimeout then an underlying, CONNECTOR-specific value is used.
See also
CONN_GetTimeout
Parameters
[in]connconnection handle
[in]eventI/O direction
[in]timeoutnew timeout

Definition at line 520 of file ncbi_connection.c.

References assert, conn, CONN_LOG_EX, CONN_NOT_NULL, eIO_Close, eIO_InvalidArg, eIO_Open, eIO_Read, eIO_ReadWrite, eIO_Success, eIO_Write, eLOG_Error, and kDefaultTimeout.

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

◆ CONN_SetUserData()

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() in 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 1265 of file ncbi_connection.c.

References conn, CONN_CALLTRACE, data, eIO_InvalidArg, and eIO_Success.

◆ CONN_Status()

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).

Note
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 for availability of any data or I/O), and returns eIO_Success if it is open, or an error code otherwise.
A special case of eIO_ReadWrite clears internally cached read and write
status (so that any following CONN_Status() call with either eIO_Read or eIO_Write would have to access the underlying CONNECTOR), and otherwise is equivalent to eIO_Open.
See also
CONN_Create, CONN_Read, CONN_Write, CONN_Flush
Parameters
[in]connconnection handle
[in]direIO_Open, eIO_Read, eIO_Write, or eIO_ReadWrite

Definition at line 1118 of file ncbi_connection.c.

References assert, conn, CONN_NOT_NULL, eCONN_Cancel, eCONN_Corrupt, eCONN_Open, eCONN_Unusable, eIO_Interrupt, eIO_InvalidArg, eIO_NotSupported, eIO_Open, eIO_Read, eIO_ReadWrite, eIO_Success, eIO_Unknown, and eIO_Write.

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

◆ CONN_Wait()

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-specific).
See also
CONN_Read, CONN_Write
Parameters
[in]connconnection handle
[in]eventcan only be either of eIO_Read,eIO_Write
[in]timeoutthe maximal wait time

Definition at line 615 of file ncbi_connection.c.

References assert, BUF_Size(), conn, CONN_LOG, CONN_NOT_NULL, eCONN_Open, eIO_Interrupt, eIO_InvalidArg, eIO_NotSupported, eIO_Read, eIO_Success, eIO_Timeout, eIO_Write, eLOG_Critical, eLOG_Error, eLOG_Trace, eLOG_Warning, kDefaultTimeout, s_Open(), STimeoutTag::sec, and STimeoutTag::usec.

Referenced by CConnTest::CheckFWConnections(), CReaderServiceConnector::Connect(), CConnTest::ExtraCheckOnFailure(), CConn_Streambuf::Fetch(), CConn_IOStream::Wait(), and CId2FetchApp::x_InitConnection().

◆ CONN_Write()

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 765 of file ncbi_connection.c.

References assert, conn, CONN_NOT_NULL, data, eCONN_Open, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_WritePersist, eIO_WritePlain, fCONN_Supplement, s_CONN_Write(), s_CONN_WritePersist(), s_Open(), ncbi::grid::netcache::search::fields::size, and Write().

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

◆ FILE_CreateConnector()

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

Definition at line 345 of file ncbi_file_connector.c.

References FILE_CreateConnectorEx(), and NULL.

Referenced by s_LoadLocalIPs().

◆ FILE_CreateConnectorEx()

CONNECTOR FILE_CreateConnectorEx ( const char *  ifname,
const char *  ofname,
const SFILE_ConnAttr attr 
)

◆ FTP_CreateConnector()

CONNECTOR FTP_CreateConnector ( const SConnNetInfo info,
TFTP_Flags  flag,
const SFTP_Callback cmcb 
)

Definition at line 2463 of file ncbi_ftp_connector.c.

References info, and s_CreateConnector().

Referenced by s_FtpConnectorBuilder().

◆ FTP_CreateConnectorSimple()

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 2451 of file ncbi_ftp_connector.c.

References s_CreateConnector().

Referenced by s_FtpConnectorBuilder().

◆ HTTP_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 2965 of file ncbi_http_connector.c.

References flags, and s_CreateConnector().

Referenced by s_CreateConnectorHttp(), and s_LoadLocalIPs().

◆ HTTP_CreateConnectorEx()

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. Once 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 (all the data saved 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 saved previously, then the new data generated in response to the latest request. The behavior can be changed by the fHTTP_DropUnread flag (not to save the unread data).

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 (eIO_NotSupported 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 2974 of file ncbi_http_connector.c.

References cleanup(), flags, and s_CreateConnector().

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

◆ HTTP_CreateTunnel()

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

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

Definition at line 3050 of file ncbi_http_connector.c.

References flags, and HTTP_CreateTunnelEx().

Referenced by s_SocketConnectorBuilder().

◆ HTTP_CreateTunnelEx()

EIO_Status HTTP_CreateTunnelEx ( const SConnNetInfo net_info,
THTTP_Flags  flags,
const void *  init_data,
size_t  init_size,
void *  user_data,
FHTTP_Adjust  adjust,
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. "net_info->scheme" is only used to infer the proper default form of the ":port" part in the "Host:" tag for the proxy request in case of HTTP[S] (thus, eURL_Unspec forces the ":port" part to be always present in the tag).

Note
"net_info" can be passed as NULL to be constructed from the environment.
"sock" parameter must be non-NULL but must point to a NULL SOCK (checked!).
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 (in *sock) has been successfully created; otherwise, return an error code and if "*sock" was passed non-NULL and has not been used at all in the call (consider: memory allocation errors or invalid arguments to the call), do not modify it; else, "*sock" gets closed internally and "*sock" returned cleared as 0.
See also
THTTP_Flags, SOCK_CreateEx, SOCK_Close
Parameters
init_datainitial data block to send via tunnel
init_sizesize of the initial data block
user_datauser data for the adjust callback
adjustadjust callback, may be NULL
sockreturn socket; must be non-NULL

Definition at line 2987 of file ncbi_http_connector.c.

References assert, BUF_Prepend(), BUF_Size(), SHttpConnector::conn_state, eCS_Eom, eCS_ReadBody, eEM_Wait, eIO_InvalidArg, eIO_NotSupported, eIO_Success, eIO_Unknown, fHTTP_DropUnread, flags, 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(), and s_Connect().

◆ HTTP_SetNcbiMessageHook()

void HTTP_SetNcbiMessageHook ( FHTTP_NcbiMessageHook  hook)

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

Any hook will be called no more than once. Until no hook is installed, and exactly one message is caught, a critical error will be generated in the standard log file upon acceptance of every message. *Not MT-safe*.

Parameters
hookNew hook to be installed, NULL to reset

Definition at line 3059 of file ncbi_http_connector.c.

References s_MessageHook, and s_MessageIssued.

◆ MEMORY_CreateConnector()

CONNECTOR MEMORY_CreateConnector ( void  )

Definition at line 243 of file ncbi_memory_connector.c.

References MEMORY_CreateConnectorEx().

◆ MEMORY_CreateConnectorEx()

CONNECTOR MEMORY_CreateConnectorEx ( BUF  buf,
unsigned int  own_buf 
)

◆ METACONN_Insert()

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 84 of file ncbi_connector.c.

References assert, SMetaConnector::default_timeout, eIO_InvalidArg, eIO_Success, eIO_Unknown, eLOG_Critical, eLOG_Error, g_NcbiDefConnTimeout, kDefaultTimeout, SMetaConnector::list, SConnectorTag::meta, METACONN_LOG, SConnectorTag::next, and SConnectorTag::setup.

Referenced by s_VT_Open(), and x_ReInit().

◆ METACONN_Remove()

EIO_Status METACONN_Remove ( SMetaConnector meta,
CONNECTOR  connector 
)

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

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

Definition at line 48 of file ncbi_connector.c.

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

Referenced by s_Close(), and x_ReInit().

◆ NAMEDPIPE_CreateConnector()

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 processes through a named pipe. Return NULL on error.

Parameters
pipesizeuse default

Definition at line 191 of file ncbi_namedpipe_connector.cpp.

References make_c_unique(), malloc(), s_Destroy(), and s_Setup().

◆ PIPE_CreateConnector()

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 with a spawned process (command) over an interprocess pipe. Return NULL on error.

Parameters
cmdCommand name to execute
argsVector of string arguments for the command (argv[0] excluded)
flagsSee CPipe::TCreateFlags
pipeThe connector is to be built on top of the specified CPipe (otherwise, a CPipe oobject gets created internally)
own_pipeDisposition of the "pipe" parameter when the connector gets destroyed
pipe_sizeInternal buffer size (0 uses some reasonable default)
See also
CPipe
Parameters
own_pipeonly if "pipe" given
pipe_sizeuse default

Definition at line 235 of file ncbi_pipe_connector.cpp.

References cmd, eTakeOwnership, flags, make_c_unique(), malloc(), s_Destroy(), and s_Setup().

Referenced by s_PipeConnectorBuilder().

◆ SERVICE_CreateConnectorEx()

CONNECTOR SERVICE_CreateConnectorEx ( const char *  service,
TSERV_Type  types,
const SConnNetInfo net_info,
const SSERVICE_Extra extra 
)

◆ SOCK_CreateConnector()

CONNECTOR SOCK_CreateConnector ( const char *  host,
unsigned short  port,
unsigned short  max_try 
)

Definition at line 368 of file ncbi_socket_connector.c.

References fSOCK_LogDefault, and s_Init().

◆ SOCK_CreateConnectorEx()

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

◆ SOCK_CreateConnectorOnTop()

CONNECTOR SOCK_CreateConnectorOnTop ( SOCK  sock,
unsigned short  own_sock 
)

Definition at line 389 of file ncbi_socket_connector.c.

References s_Init().

◆ SOCK_CreateConnectorOnTopEx()

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

Definition at line 397 of file ncbi_socket_connector.c.

References s_Init().

Referenced by s_SocketConnectorBuilder().

Variable Documentation

◆ adjust

FHTTP_Adjust SSERVICE_Extra::adjust

◆ c_close

CONNECTOR SMetaConnector::c_close

Definition at line 201 of file ncbi_connector.h.

Referenced by s_Close().

◆ c_descr

CONNECTOR SMetaConnector::c_descr

Definition at line 194 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ c_flush

CONNECTOR SMetaConnector::c_flush

Definition at line 198 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ c_get_type

CONNECTOR SMetaConnector::c_get_type

Definition at line 193 of file ncbi_connector.h.

Referenced by CONN_GetSOCK(), and s_VT_Open().

◆ c_open

CONNECTOR SMetaConnector::c_open

Definition at line 195 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ c_read

CONNECTOR SMetaConnector::c_read

Definition at line 199 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ c_status

CONNECTOR SMetaConnector::c_status

Definition at line 200 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ c_wait

CONNECTOR SMetaConnector::c_wait

Definition at line 196 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ c_write

CONNECTOR SMetaConnector::c_write

Definition at line 197 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ cleanup

FSERVICE_Cleanup SSERVICE_Extra::cleanup

◆ close

FConnectorClose SMetaConnector::close

Definition at line 201 of file ncbi_connector.h.

Referenced by s_Close().

◆ data [1/3]

void* SCONN_Callback::data

◆ data [2/3]

void* SFTP_Callback::data

◆ data [3/3]

void* SSERVICE_Extra::data

◆ default_timeout

const STimeout* SMetaConnector::default_timeout

default timeout pointer

Definition at line 202 of file ncbi_connector.h.

Referenced by METACONN_Insert(), and s_Setup().

◆ default_tmo

STimeout SMetaConnector::default_tmo

storage for default_timeout

Definition at line 203 of file ncbi_connector.h.

◆ descr

FConnectorDescr SMetaConnector::descr

Definition at line 194 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ destroy

FDestroy SConnectorTag::destroy

◆ flags

THTTP_Flags SSERVICE_Extra::flags

◆ flush

FConnectorFlush SMetaConnector::flush

Definition at line 198 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ func [1/2]

FCONN_Callback SCONN_Callback::func

◆ func [2/2]

FFTP_Callback SFTP_Callback::func

◆ g_NcbiDefConnTimeout

const STimeout g_NcbiDefConnTimeout
extern

DEF_CONN_TIMEOUT as STimeout.

Definition at line 54 of file ncbi_connutil.c.

Referenced by ConnNetInfo_CreateInternal(), CConn_Streambuf::Fetch(), METACONN_Insert(), s_ReadHeader(), CConnTest::SetTimeout(), and x_Large().

◆ get_next_info

FSERVICE_GetNextInfo SSERVICE_Extra::get_next_info

◆ get_type

FConnectorGetType SMetaConnector::get_type

Definition at line 193 of file ncbi_connector.h.

Referenced by CONN_GetSOCK(), and s_VT_Open().

◆ handle

void* SConnectorTag::handle

◆ list

CONNECTOR SMetaConnector::list

◆ meta

SMetaConnector* SConnectorTag::meta

◆ next

CONNECTOR SConnectorTag::next

◆ open

FConnectorOpen SMetaConnector::open

Definition at line 195 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ parse_header

FHTTP_ParseHeader SSERVICE_Extra::parse_header

◆ r_pos

TNCBI_BigCount SFILE_ConnAttr::r_pos

Definition at line 79 of file ncbi_file_connector.h.

Referenced by s_VT_Open().

◆ read

FConnectorRead SMetaConnector::read

Definition at line 199 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ reset

FSERVICE_Reset SSERVICE_Extra::reset

◆ setup

FSetupVTable SConnectorTag::setup

◆ status

FConnectorStatus SMetaConnector::status

Definition at line 200 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ w_mode

EFILE_ConnMode SFILE_ConnAttr::w_mode

Definition at line 77 of file ncbi_file_connector.h.

Referenced by s_VT_Open().

◆ w_pos

TNCBI_BigCount SFILE_ConnAttr::w_pos

Definition at line 78 of file ncbi_file_connector.h.

Referenced by s_VT_Open().

◆ wait

FConnectorWait SMetaConnector::wait

Definition at line 196 of file ncbi_connector.h.

Referenced by s_VT_Open().

◆ write

FConnectorWrite SMetaConnector::write

Definition at line 197 of file ncbi_connector.h.

Referenced by s_VT_Open().

Modified on Mon May 20 05:02:50 2024 by modify_doxy.py rev. 669887