Imported Upstream version 6.1.20110713

1 files changed, 32 insertions, 29 deletions

diff --git a/connect/ncbi_socket_connector.h b/connect/ncbi_socket_connector.h
index d968dc14..192132bd 100644
--- a/connect/ncbi_socket_connector.h
+++ b/connect/ncbi_socket_connector.h
@@ -1,7 +1,7 @@
 #ifndef CONNECT___NCBI_SOCKET_CONNECTOR__H
 #define CONNECT___NCBI_SOCKET_CONNECTOR__H
 
-/* $Id: ncbi_socket_connector.h,v 6.12 2010/02/01 13:54:31 kazimird Exp $
+/* $Id: ncbi_socket_connector.h,v 6.14 2010/12/14 19:41:14 kazimird Exp $
  * ===========================================================================
  *
  *                            PUBLIC DOMAIN NOTICE
@@ -51,52 +51,55 @@ extern "C" {
 #endif
 
 
-/* This is equivalent to SOCK_CreateConnectorEx(host, port, max_try, 0,0,0),
- * see below.
- */
-extern NCBI_XCONNECT_EXPORT CONNECTOR SOCK_CreateConnector
-(const char*    host,   /* server:  host                            */
- unsigned short port,   /* server:  service port                    */
- unsigned int   max_try /* max.number of attempts to establish conn */
- );
-
-
-typedef enum { /* DEPRECATED -- DON'T USE! */
-    fSCC_DebugPrintout  = fSOCK_LogOn,
-    fSCC_Secure         = fSOCK_Secure,
-    fSCC_SetReadOnWrite = fSOCK_ReadOnWrite
-} ESCC_Flags;
-
-/* Create new CONNECTOR structure to handle connection to a socket.
- * Make up to "max_try" attempts to connect to the "host:port" before
- * giving up.
+/* Create new CONNECTOR, which handles connection to a network socket.
+ * Make up to "max_try" attempts to connect to "host:port" before giving up.
  * On successful connect, send the first "init_size" bytes from buffer
- * "init_data"(can be NULL -- then send nothing, regardless of "init_size")
+ * "init_data" (can be NULL -- then send nothing, regardless of "init_size")
  * to the newly opened connection.
  * NOTE:  the connector makes (and then uses) its own copy of the "init_data".
  * Return NULL on error.
  */
 extern NCBI_XCONNECT_EXPORT CONNECTOR SOCK_CreateConnectorEx
-(const char*    host,      /* server:  host                                  */
- unsigned short port,      /* server:  service port                          */
- unsigned int   max_try,   /* max.number of attempts to establish connection */
+(const char*    host,      /* host to connect to                             */
+ unsigned short port,      /* port to connect to                             */
+ unsigned short max_try,   /* max.number of attempts to establish connection */
  const void*    init_data, /* data to send to server on connect              */
  size_t         init_size, /* size of the "init_data" buffer                 */
- TSOCK_Flags    flags      /* bitwise OR of additional flags: see above      */
+ TSOCK_Flags    flags      /* bitwise OR of additional socket flags          */
  );
 
 
-/* Create new CONNECTOR structure on top of existing socket object (SOCK),
+/* Equivalent to SOCK_CreateConnectorEx(host, port, max_try, 0, 0, 0)
+ */
+extern NCBI_XCONNECT_EXPORT CONNECTOR SOCK_CreateConnector
+(const char*    host,      /* host to connect to                             */
+ unsigned short port,      /* port to connect to                             */
+ unsigned short max_try    /* max.number of attempts to establish connection */
+ );
+
+
+/* Create new CONNECTOR structure on top of existing socket handle (SOCK),
  * acquiring the ownership of the socket "sock" if "own_sock" passed non-zero,
  * and overriding all timeouts that might have been set already in it.
  * Timeout values will be taken from connection (CONN), after the connector
- * is used in CONN_Create() call.
+ * is used in the CONN_Create() call.
  * Non-owned socket will not be closed when the connection gets closed;
  * and may further be used, as necessary (including closing it explicitly).
+ * Note that this call can build a (dysfunctional) connector on top of a NULL
+ * sock, and that the delayed connection open will always result in eIO_Closed.
+ */
+extern NCBI_XCONNECT_EXPORT CONNECTOR SOCK_CreateConnectorOnTopEx
+(SOCK                   sock,    /* existing socket handle (may not be NULL) */
+ unsigned short/*bool*/ own_sock,/* non-zero if connector will own "sock"    */
+ const char*            hostport /* connection point name taken verbatim     */
+ );
+
+
+/* Equivalent to SOCK_CreateConnectorOnTopEx(sock, own_sock, 0)
  */
 extern NCBI_XCONNECT_EXPORT CONNECTOR SOCK_CreateConnectorOnTop
-(SOCK                 sock,    /* socket object                              */
- unsigned int/*bool*/ own_sock /* non-zero if connector will own "sock"      */
+(SOCK                   sock,    /* existing socket handle (may not be NULL) */
+ unsigned short/*bool*/ own_sock /* non-zero if connector will own "sock"    */
  );