ncbi_socket.h

ncbi源码

/******************************************************************************
 *  Connectionless (datagram) sockets
 *
 *  How the datagram exchange API works:
 *
 *  Datagram socket is created with special DSOCK_Create[Ex] calls but the
 *  resulting object is a SOCK handle. That is, almost all SOCK routines
 *  may be applied to the handle. There are few exceptions, though.
 *  In datagram sockets I/O differs from how it is done in stream sockets:
 *
 *  SOCK_Write() writes data into an internal message buffer, appending new
 *  data as they come with each SOCK_Write(). When the message is complete,
 *  SOCK_SendMsg() should be called (optionally with additional last,
 *  or the only [if no SOCK_Write() preceded the call] message fragment)
 *  to actually send the message down the wire. If successful, SOCK_SendMsg()
 *  cleans the internal buffer, and the process may repeat. If unsuccessful,
 *  SOCK_SendMsg() can be repeated with restiction that no additional data are
 *  provided in the call. This way, the entire message will be attempted to
 *  be sent again. On the other hand, if after any SOCK_SendMsg() new data
 *  are added [regardless of whether previous data were successfully sent
 *  or not], all previously written [and kept in the internal send buffer]
 *  data get dropped and replaced with the new data.
 *
 *  DSOCK_WaitMsg() can be used to learn whether there is a new message
 *  available for read by DSOCK_RecvMsg() immediately.
 *
 *  SOCK_RecvMsg() receives the message into an internal receive buffer,
 *  and optionally can return the initial datagram fragment via provided
 *  buffer [this initial fragment is then stripped from what remains unread
 *  in the internal buffer]. Optimized version can supply a maximal message
 *  size (if known in advance), or 0 to get a message of any allowed size.
 *  The actual size of the received message can be obtained via a
 *  pointer-type argument 'msgsize'. The message kept in the internal buffer
 *  can be read out in several SOCK_Read() calls, last returning eIO_Closed,
 *  when all data have been taken out. SOCK_Wait() returns eIO_Success while
 *  there are data in the internal message buffer that SOCK_Read() can read.
 *
 *  SOCK_WipeMsg() can be used to clear the internal message buffers in
 *  either eIO_Read or eIO_Write directions, meaning receive and send
 *  buffers correspondingly.
 */


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Create
(SOCK*           sock                   /* [out] socket created              */
 );


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_CreateEx
(SOCK*           sock,                  /* [out] socket created              */
 ESwitch         log                    /* [in]  whether to log data activity*/
 );


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Bind
(SOCK            sock,                  /* [in]  SOCK from DSOCK_Create[Ex]()*/
 unsigned short  port                   /* [in]  port to bind to (!=0)       */
 );


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_Connect
(SOCK            sock,                  /* [in]  SOCK from DSOCK_Create[Ex]()*/
 const char*     host,                  /* [in]  peer host                   */
 unsigned short  port                   /* [in]  peer port                   */
 );


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_WaitMsg
(SOCK            sock,                  /* [in]  SOCK from DSOCK_Create[Ex]()*/
 const STimeout* timeout                /* [in]  time to wait for message    */
 );


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_SendMsg
(SOCK            sock,                  /* [in]  SOCK from DSOCK_Create[Ex]()*/
 const char*     host,                  /* [in]  hostname or dotted IP       */
 unsigned short  port,                  /* [in]  port number, host byte order*/
 const void*     data,                  /* [in]  additional data to send     */
 size_t          datalen                /* [in]  size of addtl data (bytes)  */
 );


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_RecvMsg
(SOCK            sock,                  /* [in]  SOCK from DSOCK_Create[Ex]()*/
 void*           buf,                   /* [in]  buf to store msg at,m.b.NULL*/
 size_t          buflen,                /* [in]  buf length provided         */
 size_t          maxmsglen,             /* [in]  maximal expected message len*/
 size_t*         msglen,                /* [out] actual msg size, may be NULL*/
 unsigned int*   sender_addr,           /* [out] net byte order, may be NULL */
 unsigned short* sender_port            /* [out] host byte order, may be NULL*/
);


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_WipeMsg
(SOCK            sock,                  /* [in]  SOCK from DSOCK_Create[Ex]()*/
 EIO_Event       direction              /* [in]  either of eIO_Read|eIO_Write*/
 );


extern NCBI_XCONNECT_EXPORT EIO_Status DSOCK_SetBroadcast
(SOCK            sock,                  /* [in]  SOCK from DSOCK_Create[Ex]()*/
 int/*bool*/     broadcast              /* [in]  set(1)/unset(0) bcast capab.*/
 );



/******************************************************************************
 *  Type information for SOCK sockets
 */


/* Return non-zero value if socket "sock" was created by DSOCK_Create[Ex]().
 * Return zero otherwise.
 */
extern NCBI_XCONNECT_EXPORT int/*bool*/ SOCK_IsDatagram(SOCK sock);


/* Return non-zero value if socket "sock" was created by SOCK_Create[Ex]().
 * Return zero otherwise.
 */
extern NCBI_XCONNECT_EXPORT int/*bool*/ SOCK_IsClientSide(SOCK sock);


/* Return non-zero value if socket "sock" was created by LSOCK_Accept().
 * Return zero otherwise.
 */
extern NCBI_XCONNECT_EXPORT int/*bool*/ SOCK_IsServerSide(SOCK sock);



/******************************************************************************
 *  AUXILIARY network-specific functions (added for the portability reasons)
 */


/* Return zero on success, non-zero on error.  See BSD gethostname().
 * On error "name" returned emptied (name[0] == '\0').
 */
extern NCBI_XCONNECT_EXPORT int SOCK_gethostname
(char*  name,          /* [out] (guaranteed to be '\0'-terminated)           */
 size_t namelen        /* [in]  max # of bytes allowed to put to "name"      */
 );


/* Return zero on success, non-zero on error.  Vaguely related to BSD's
 * inet_ntoa(). On error "buf" returned emptied (buf[0] == '\0').
 */
extern NCBI_XCONNECT_EXPORT int SOCK_ntoa
(unsigned int addr,      /* [in]  must be in the network byte-order          */
 char*        buf,       /* [out] to be filled by smth. like "123.45.67.89\0"*/
 size_t       buflen     /* [in]  max # of bytes to put to "buf"             */
 );


/* See man for the BSDisms, htonl() and htons().
 */
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_HostToNetLong
(unsigned int value
 );

#define SOCK_NetToHostLong SOCK_HostToNetLong

extern NCBI_XCONNECT_EXPORT unsigned short SOCK_HostToNetShort
(unsigned short value
 );

#define SOCK_NetToHostShort SOCK_HostToNetShort

/* Deprecated */
#define SOCK_htonl SOCK_HostToNetLong
#define SOCK_ntohl SOCK_NetToHostLong
#define SOCK_htons SOCK_HostToNetShort
#define SOCK_ntohs SOCK_NetToHostShort


/* Return INET host address (in network byte order) of the
 * specified host (or local host, if hostname is passed as NULL),
 * which can be either domain name or an IP address in
 * dotted notation (e.g. "123.45.67.89\0"). Return 0 on error.
 * NOTE: "0.0.0.0" and "255.255.255.255" are considered invalid.
 */
extern NCBI_XCONNECT_EXPORT unsigned int SOCK_gethostbyname
(const char* hostname  /* [in]  return current host address if hostname is 0 */
 );


/* Take INET host address (in network byte order) and fill out the
 * the provided buffer with the name, which the address corresponds to
 * (in case of multiple names the primary name is used). Return value 0
 * means error, while success is denoted by the 'name' argument returned.
 * Note that on error the name returned emptied (name[0] == '\0').
 */
extern NCBI_XCONNECT_EXPORT char* SOCK_gethostbyaddr
(unsigned int addr,    /* [in]  host address in network byte order           */
 char*        name,    /* [out] buffer to put the name to                    */
 size_t       namelen  /* [in]  size (bytes) of the buffer above             */
 );


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


/* @} */


/*
 * ---------------------------------------------------------------------------
 * $Log: ncbi_socket.h,v $
 * Revision 1000.4  2004/04/12 17:06:00  gouriano
 * PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R6.49
 *
 * Revision 6.49  2004/03/23 02:26:55  lavr
 * Typo fix
 *
 * Revision 6.48  2003/11/25 15:07:12  lavr
 * SOCK_Status() to accept eIO_Open
 *
 * Revision 6.47  2003/11/24 19:22:24  lavr
 * SetSelectInternalRestartTimeout() to accept ptr to STimeout
 *
 * Revision 6.46  2003/11/18 20:18:49  lavr
 * +SetSelectInternalRestartTimeout()
 *
 * Revision 6.45  2003/11/12 17:43:08  lavr
 * +SOCK_CloseEx()
 *
 * Revision 6.44  2003/10/24 16:51:11  lavr
 * GetTimeout(eIO_ReadWrite): return the lesser of eIO_Read and eIO_Write
 *
 * Revision 6.43  2003/10/23 12:14:33  lavr
 * Socket feature setters made returning old feature values
 *
 * Revision 6.42  2003/09/23 21:04:43  lavr
 * SOCK_Abort():  argument comment removed as irrelevant (cut&paste mishap)
 *
 * Revision 6.41  2003/08/25 14:38:00  lavr
 * Introduce POLLABLE_Poll() and [L]SOCK<->POLLABLE conversion routines
 *
 * Revision 6.40  2003/07/15 16:42:09  lavr
 * +SOCK_GetPeerAddressString()
 *
 * Revision 6.39  2003/06/12 13:21:21  lavr
 * Added eIO_Timeout as a return code for SOCK_Status()
 *
 * Revision 6.38  2003/05/20 21:24:32  lavr
 * SOCK_Write(): note added on writing 0 bytes to a socket
 *
 * Revision 6.37  2003/05/19 16:42:07  lavr
 * +SOCK_SetReuseAddress[API]() - both EXPERIMENTAL!
 *
 * Revision 6.36  2003/05/14 03:46:15  lavr
 * Revised API to include {0,0} connect timeouts, initial data block
 * Revised datagram socket API
 *
 * Revision 6.35  2003/04/30 16:59:05  lavr
 * Added notice about how datagram API is supposed to work
 *
 * Revision 6.34  2003/04/11 20:57:43  lavr
 * DSOCK_Connect() documented
 *
 * Revision 6.33  2003/04/09 19:05:54  siyan
 * Added doxygen support
 *
 * Revision 6.32  2003/04/04 21:00:09  lavr
 * +SOCK_CreateOnTop()
 *
 * Revision 6.31  2003/01/17 01:32:30  lavr
 * +LSOCK_CreateEx()
 *
 * Revision 6.30  2003/01/16 16:30:57  lavr
 * Add prototype for DSOCK_WipeMsg()
 *
 * Revision 6.29  2003/01/15 19:50:45  lavr
 * Datagram socket interface revised
 *
 * Revision 6.28  2003/01/08 01:59:33  lavr
 * DLL-ize CONNECT library for MSVC (add NCBI_XCONNECT_EXPORT)
 *
 * Revision 6.27  2003/01/07 22:01:43  lavr
 * ChangeLog message corrected
 *
 * Revision 6.26  2003/01/07 21:58:24  lavr
 * Draft DSOCK interface added
 *
 * Revision 6.25  2002/12/05 21:44:50  lavr
 * Retire SOCK_Create() as a macro; reinstate as a regular call
 *
 * Revision 6.24  2002/12/04 16:53:12  lavr
 * Introduce SOCK_CreateEx()
 *
 * Revision 6.23  2002/11/01 20:12:06  lavr
 * Specifically state which IP/name manip. routines do emtpy output buffer
 *
 * Revision 6.22  2002/09/19 18:07:06  lavr
 * Consistency check moved up to be the first thing
 *
 * Revision 6.21  2002/08/27 03:15:01  lavr
 * Deprecate SOCK_{nh}to{hn}{ls}, define more elaborate call names
 * SOCK_{Net|Host}To{Host|Net}{Long|Short} instead
 *
 * Revision 6.20  2002/08/15 18:44:18  lavr
 * SOCK_Poll() documented in more details
 *
 * Revision 6.19  2002/08/12 14:59:12  lavr
 * Additional (last) argument for SOCK_Write: write_mode
 *
 * Revision 6.18  2002/08/07 16:31:00  lavr
 * Added enum ENH_ByteOrder; renamed SOCK_GetAddress() ->
 * SOCK_GetPeerAddress() and now accepts ENH_ByteOrder as last arg;
 * added SOCK_SetInterruptOnSignal[API]; write-status (w_status) made current;
 * log moved to end
 *
 * Revision 6.17  2002/04/26 16:40:43  lavr
 * New method: SOCK_Poll()
 *
 * Revision 6.16  2002/04/22 20:52:34  lavr
 * +SOCK_htons(), macros SOCK_ntohl() and SOCK_ntohs()
 *
 * Revision 6.15  2001/12/03 21:33:48  vakatov
 * + SOCK_IsServerSide()
 *
 * Revision 6.14  2001/09/10 16:10:41  vakatov
 * SOCK_gethostbyname() -- special cases "0.0.0.0" and "255.255.255.255"
 *
 * Revision 6.13  2001/05/21 15:11:46  ivanov
 * Added (with Denis Vakatov) automatic read on write data from the socket
 * (stall protection).
 * Added functions SOCK_SetReadOnWriteAPI(), SOCK_SetReadOnWrite()
 * and internal function s_SelectStallsafe().
 *
 * Revision 6.12  2001/04/23 22:22:06  vakatov
 * SOCK_Read() -- special treatment for "buf" == NULL
 *
 * Revision 6.11  2001/03/22 17:44:14  vakatov
 * + SOCK_AllowSigPipeAPI()
 *
 * Revision 6.10  2001/03/06 23:54:10  lavr
 * Renamed: SOCK_gethostaddr -> SOCK_gethostbyname
 * Added:   SOCK_gethostbyaddr
 *
 * Revision 6.9  2001/03/02 20:05:15  lavr
 * Typos fixed
 *
 * Revision 6.8  2000/12/26 21:40:01  lavr
 * SOCK_Read modified to handle properly the case of 0 byte reading
 *
 * Revision 6.7  2000/12/05 23:27:44  lavr
 * Added SOCK_gethostaddr
 *
 * Revision 6.6  2000/11/15 18:51:05  vakatov
 * Add SOCK_Shutdown() and SOCK_Status().  Remove SOCK_Eof().
 *
 * Revision 6.5  2000/06/23 19:34:41  vakatov
 * Added means to log binary data
 *
 * Revision 6.4  2000/05/30 23:31:37  vakatov
 * SOCK_host2inaddr() renamed to SOCK_ntoa(), the home-made out-of-scratch
 * implementation to work properly with GCC on IRIX64 platforms
 *
 * Revision 6.3  2000/03/24 23:12:04  vakatov
 * Starting the development quasi-branch to implement CONN API.
 * All development is performed in the NCBI C++ tree only, while
 * the NCBI C tree still contains "frozen" (see the last revision) code.
 *
 * Revision 6.2  2000/02/23 22:33:38  vakatov
 * Can work both "standalone" and as a part of NCBI C++ or C toolkits
 *
 * Revision 6.1  1999/10/18 15:36:39  vakatov
 * Initial revision (derived from the former "ncbisock.[ch]")
 *
 * ===========================================================================
 */

#endif /* CONNECT___NCBI_SOCKET__H */