ncbi_socket.h File Reference

#include <connect/ncbi_core.h>

Include dependency graph for ncbi_socket.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Go to the SVN repository for this file.

Classes
struct	SSOCK_ApproveInfo
	User-level connection approval hook. More...
struct	SSOCK_Poll
	I/O polling structure. More...
struct	SSOCK_ErrInfo
struct	SPOLLABLE_Poll

Macros
#define	SOCK_Destroy(s)   SOCK_Close(s)
#define	SOCK_NetToHostLong   SOCK_HostToNetLong
#define	SOCK_NetToHostShort   SOCK_HostToNetShort
#define	NCBI_SOCK_DEPRECATED   NCBI_DEPRECATED
#define	SOCK_ntohl   SOCK_htonl
#define	SOCK_ntohs   SOCK_htons

Typedefs
typedef unsigned	EBIO_Event
typedef unsigned	EBIO_Status
typedef struct LSOCK_tag *	LSOCK
typedef struct SOCK_tag *	SOCK
typedef struct TRIGGER_tag *	TRIGGER
typedef EIO_Status(*	FSOCK_ApproveHook) (const SSOCK_ApproveInfo *info, void *data)
	The approve hook is global per API and gets called with an arbitrary user "data", if so desired as a second argument, which was specified when the hook was installed with the SOCK_SetApproveHookAPI() call. More...
typedef unsigned int	TSOCK_Flags
	bitwise "OR" of ESOCK_Flags More...
typedef void(*	FSOCK_ErrHook) (const SSOCK_ErrInfo *info, void *data)
typedef struct SPOLLABLE_tag *	POLLABLE
typedef struct SNcbiCred *	NCBI_CRED
	Opaque type for credentials. More...
typedef const struct SOCKSSL_struct *	SOCKSSL
	Opaque type for SSL implementation. More...
typedef SOCKSSL(*	FSSLSetup) (void)
	SSL setup callback. More...

Enumerations
enum	ENH_ByteOrder { eNH_HostByteOrder , eNH_NetworkByteOrder }
	Network and host byte order enumeration type. More...
enum	ESOCK_Type { eSOCK_Listening = 0 , eSOCK_Trigger = 1 , eSOCK_Socket = 2 , eSOCK_Datagram = 3 }
	Socket type (internal) More...
enum	ESOCK_Side { eSOCK_Server = 0 , eSOCK_Client = 1 }
	Sides of socket. More...
enum	ESOCK_IOWaitSysAPI { eSOCK_IOWaitSysAPIAuto , eSOCK_IOWaitSysAPIPoll , eSOCK_IOWaitSysAPISelect }
	Selector of I/O wait system API: auto, poll(), or select(). More...
enum	ESOCK_Flags {   fSOCK_LogOff = eOff , fSOCK_LogOn = eOn , fSOCK_LogDefault = eDefault , fSOCK_KeepAlive = 8 ,   fSOCK_BindAny = 0 , fSOCK_BindLocal = 0x10 , fSOCK_KeepOnExec = 0x20 , fSOCK_CloseOnExec = 0 ,   fSOCK_Secure = 0x40 , fSOCK_KeepOnClose = 0x80 , fSOCK_CloseOnClose = 0 , fSOCK_ReadOnWrite = 0x100 ,   fSOCK_InterruptOnSignal = 0x200 }
enum	ESOCK_AddressFormat { eSAF_Full = 0 , eSAF_Port , eSAF_IP }
	Get textual representation of the socket's peer. More...
enum	ESOCK_ErrType { eSOCK_ErrInit = 1 , eSOCK_ErrDns , eSOCK_ErrIO }
	User-level error hook. More...

Functions
EIO_Status	SOCK_InitializeAPI (void)
	Initialize all internal/system data & resources to be used by the SOCK API. More...
EIO_Status	SOCK_ShutdownAPI (void)
	Cleanup; destroy all internal/system data & resources used by the SOCK API. More...
size_t	SOCK_OSHandleSize (void)
	Get size of OS-dependent native socket handle. More...
void	SOCK_AllowSigPipeAPI (void)
	By default (on UNIX platforms) the SOCK API functions automagically call "signal(SIGPIPE, SIG_IGN)" on initialization. More...
void	SOCK_SetApproveHookAPI (FSOCK_ApproveHook hook, void *data)
	The hook is installed when non-NULL, and de-installed otherwise. More...
const STimeout *	SOCK_SetSelectInternalRestartTimeout (const STimeout *timeslice)
	This is a helper call that can improve I/O behavior. More...
ESOCK_IOWaitSysAPI	SOCK_SetIOWaitSysAPI (ESOCK_IOWaitSysAPI api)
	This is a helper call that can improve I/O performance (ignored for MSVC). More...
EIO_Status	TRIGGER_Create (TRIGGER *trigger, ESwitch log)
	Create an event trigger. More...
EIO_Status	TRIGGER_Close (TRIGGER trigger)
	Close an event trigger. More...
EIO_Status	TRIGGER_Set (TRIGGER trigger)
	Set an event trigger. More...
EIO_Status	TRIGGER_IsSet (TRIGGER trigger)
	Check whether the trigger has been set. More...
EIO_Status	TRIGGER_Reset (TRIGGER trigger)
	Reset the trigger. More...
EIO_Status	LSOCK_CreateEx (unsigned short port, unsigned short backlog, LSOCK *lsock, TSOCK_Flags flags)
	[SERVER-side] Create and initialize the server-side(listening) socket (socket() + bind() + listen()) More...
EIO_Status	LSOCK_Create (unsigned short port, unsigned short backlog, LSOCK *lsock)
	[SERVER-side] Create and initialize the server-side(listening) socket Same as LSOCK_CreateEx() called with the last argument provided as fSOCK_LogDefault. More...
EIO_Status	LSOCK_AcceptEx (LSOCK lsock, const STimeout *timeout, SOCK *sock, TSOCK_Flags flags)
	[SERVER-side] Accept connection from a client. More...
EIO_Status	LSOCK_Accept (LSOCK lsock, const STimeout *timeout, SOCK *sock)
	[SERVER-side] Accept connection from a client. More...
EIO_Status	LSOCK_Close (LSOCK lsock)
	[SERVER-side] Close the listening socket, destroy relevant internal data. More...
EIO_Status	LSOCK_GetOSHandleEx (LSOCK lsock, void *handle_buf, size_t handle_size, EOwnership owndership)
	Get an OS-dependent native socket handle to use by platform-specific API. More...
EIO_Status	LSOCK_GetOSHandle (LSOCK lsock, void *handle_buf, size_t handle_size)
	Same as LSOCK_GetOSHandleEx(lsock, handle_buf, handle_size, eNoOwnership). More...
unsigned short	LSOCK_GetPort (LSOCK lsock, ENH_ByteOrder byte_order)
	Get socket port number, which it listens on. More...
EIO_Status	SOCK_CreateEx (const char *host, unsigned short port, const STimeout *timeout, SOCK *sock, const void *data, size_t size, TSOCK_Flags flags)
	[CLIENT-side] Connect client to another(server-side, listening) socket (socket() + connect() [+ select()]) More...
EIO_Status	SOCK_Create (const char *host, unsigned short port, const STimeout *timeout, SOCK *sock)
	[CLIENT-side] Connect client to another(server-side, listening) socket (socket() + connect() [+ select()]) Equivalent to SOCK_CreateEx(host, port, timeout, sock, 0, 0, fSOCK_LogDefault). More...
EIO_Status	SOCK_CreateOnTopEx (const void *handle, size_t handle_size, SOCK *sock, const void *data, size_t size, TSOCK_Flags flags)
	[SERVER-side] Create a SOCKet on top of either an OS-dependent "handle" (file descriptor on Unix, SOCKET on MS-Windows) or an existing SOCK object. More...
EIO_Status	SOCK_CreateOnTop (const void *handle, size_t handle_size, SOCK *sock)
	[SERVER-side] Create a socket on top of a "handle". More...
EIO_Status	SOCK_Reconnect (SOCK sock, const char *host, unsigned short port, const STimeout *timeout)
	[CLIENT-side] Close the socket referred to by "sock" and then connect it to another "host:port"; fail if it takes more than "timeout" (close() + connect() [+ select()]) More...
EIO_Status	SOCK_Shutdown (SOCK sock, EIO_Event how)
	Shutdown the connection in only one direction (specified by "direction"). More...
EIO_Status	SOCK_Close (SOCK sock)
	Close the SOCK handle, and destroy all relevant internal data. More...
EIO_Status	SOCK_CloseEx (SOCK sock, int destroy)
	Close the SOCK handle, and conditionally destroy relevant internal data. More...
EIO_Status	SOCK_CloseOSHandle (const void *handle, size_t handle_size)
	Close socket OS handle (ungracefully aborting the connection if necessary). More...
EIO_Status	SOCK_Wait (SOCK sock, EIO_Event event, const STimeout *timeout)
	Block on the socket until either the specified "event" is available or "timeout" expires (if "timeout" is NULL then assume it infinite). More...
EIO_Status	SOCK_Poll (size_t n, SSOCK_Poll polls[], const STimeout *timeout, size_t *n_ready)
	Block until at least one of the sockets enlisted in "polls" array (of size "n") becomes available for requested operation (SSOCK_Poll::event), or until timeout expires (wait indefinitely if timeout is passed as NULL). More...
EIO_Status	SOCK_SetTimeout (SOCK sock, EIO_Event event, const STimeout *timeout)
	Specify timeout for the connection I/O (see SOCK_[Read|Write|Close]()). More...
const STimeout *	SOCK_GetTimeout (SOCK sock, EIO_Event event)
	Get the connection's i/o timeout (or NULL, if the timeout is infinite). More...
EIO_Status	SOCK_Read (SOCK sock, void *buf, size_t size, size_t *n_read, EIO_ReadMethod how)
	Read/peek up to "size" bytes from "sock" to a buffer pointed to by "buf". More...
EIO_Status	SOCK_ReadLine (SOCK sock, char *line, size_t size, size_t *n_read)
	Read a line from SOCK. More...
EIO_Status	SOCK_Pushback (SOCK sock, const void *data, size_t size)
	Push the specified data back to the socket's input queue (in the socket's internal read buffer). More...
EIO_Status	SOCK_Status (SOCK sock, EIO_Event direction)
	Return low-level socket I/O status of *last* socket operation. More...
EIO_Status	SOCK_Write (SOCK sock, const void *data, size_t size, size_t *n_written, EIO_WriteMethod how)
	Write "size" bytes of "data" to "sock". More...
EIO_Status	SOCK_Abort (SOCK sock)
	If there is outstanding connection or output data pending, cancel it. More...
unsigned short	SOCK_GetLocalPortEx (SOCK sock, int trueport, ENH_ByteOrder byte_order)
	Get local port of the socket (true or cached / stored). More...
unsigned short	SOCK_GetLocalPort (SOCK sock, ENH_ByteOrder byte_order)
	Get local port of the socket. More...
void	SOCK_GetPeerAddress (SOCK sock, unsigned int *host, unsigned short *port, ENH_ByteOrder byte_order)
	Get host and port of the socket's peer (remote end). More...
unsigned short	SOCK_GetRemotePort (SOCK sock, ENH_ByteOrder byte_order)
	Get remote port of the socket (the port it is connected to). More...
char *	SOCK_GetPeerAddressStringEx (SOCK sock, char *buf, size_t bufsize, ESOCK_AddressFormat format)
char *	SOCK_GetPeerAddressString (SOCK sock, char *buf, size_t bufsize)
	Equivalent to SOCK_GetPeerAddressStringEx(.,.,.,eSAF_Full) More...
EIO_Status	SOCK_GetOSHandleEx (SOCK sock, void *handle_buf, size_t handle_size, EOwnership ownership)
	Get an OS-dependent native socket handle to use by platform-specific API. More...
EIO_Status	SOCK_GetOSHandle (SOCK sock, void *handle_buf, size_t handle_size)
	Same as SOCK_GetOSHandleEx(sock, handle_buf, handle_size, eNoOwnership). More...
ESwitch	SOCK_SetReadOnWriteAPI (ESwitch on_off)
	By default, sockets will not try to read data from inside SOCK_Write(). More...
ESwitch	SOCK_SetReadOnWrite (SOCK sock, ESwitch on_off)
	Control the reading-while-writing feature for socket "sock" individually. More...
void	SOCK_SetCork (SOCK sock, int on_off)
	Control OS-defined send strategy by disabling/enabling the TCP layer to send incomplete network frames (packets). More...
void	SOCK_DisableOSSendDelay (SOCK sock, int on_off)
	Control OS-defined send strategy by disabling/enabling the TCP Nagle algorithm (which is on by default) that packs multiple requests into a single packet and thus transfers the data in fewer transactions, miminizing the network traffic and generally bursting the throughput. More...
EIO_Status	DSOCK_CreateEx (SOCK *sock, TSOCK_Flags flags)
	Create a datagram socket. More...
EIO_Status	DSOCK_Create (SOCK *sock)
	Same as DSOCK_CreateEx(, fSOCK_LogDefault) More...
EIO_Status	DSOCK_Bind (SOCK sock, unsigned short port)
	Assosiate a datagram socket with a local port. More...
EIO_Status	DSOCK_Connect (SOCK sock, const char *host, unsigned short port)
	Associate a datagram socket with a destination address. More...
EIO_Status	DSOCK_WaitMsg (SOCK sock, const STimeout *timeout)
	Wait for a datagram in a datagram socket. More...
EIO_Status	DSOCK_SendMsg (SOCK sock, const char *host, unsigned short port, const void *data, size_t datalen)
	Send a datagram to a datagram socket. More...
EIO_Status	DSOCK_RecvMsg (SOCK sock, void *buf, size_t bufsize, size_t maxmsglen, size_t *msglen, unsigned int *sender_addr, unsigned short *sender_port)
	Receive a datagram from a datagram socket. More...
EIO_Status	DSOCK_WipeMsg (SOCK sock, EIO_Event direction)
	Clear message froma datagram socket. More...
EIO_Status	DSOCK_SetBroadcast (SOCK sock, int broadcast)
	Set a datagram socket for broadcast. More...
TNCBI_BigCount	DSOCK_GetMessageCount (SOCK sock, EIO_Event direction)
	Get message count. More...
int	SOCK_IsDatagram (SOCK sock)
	Check whether a socket is a datagram one. More...
int	SOCK_IsClientSide (SOCK sock)
	Check whether a socket is client-side. More...
int	SOCK_IsServerSide (SOCK sock)
	Check whether a socket is server-side. More...
int	SOCK_IsUNIX (SOCK sock)
	Check whether a socket is UNIX type. More...
int	SOCK_IsSecure (SOCK sock)
	Check whether a socket is using SSL (Secure Socket Layer). More...
TNCBI_BigCount	SOCK_GetPosition (SOCK sock, EIO_Event direction)
	Get current read or write position within a socket. More...
TNCBI_BigCount	SOCK_GetCount (SOCK sock, EIO_Event direction)
	Get counts of read or written bytes. More...
TNCBI_BigCount	SOCK_GetTotalCount (SOCK sock, EIO_Event direction)
	Get the total volume of data transferred by a socket. More...
ESwitch	SOCK_SetInterruptOnSignalAPI (ESwitch on_off)
	Control restartability of I/O interrupted by signals. More...
ESwitch	SOCK_SetInterruptOnSignal (SOCK sock, ESwitch on_off)
	Control restartability of I/O interrupted by signals on a per-socket basis. More...
ESwitch	SOCK_SetReuseAddressAPI (ESwitch on_off)
	Control address reuse for socket addresses taken by the API. More...
void	SOCK_SetReuseAddress (SOCK sock, int on_off)
	Control reuse of socket addresses on per-socket basis Note: only a boolean parameter value is can be used here. More...
ESwitch	SOCK_SetDataLoggingAPI (ESwitch log)
	By default data are not logged. More...
ESwitch	SOCK_SetDataLogging (SOCK sock, ESwitch log)
	Control the data logging for socket "sock" individually. More...
void	SOCK_SetErrHookAPI (FSOCK_ErrHook hook, void *data)
EIO_Status	POLLABLE_Poll (size_t n, SPOLLABLE_Poll polls[], const STimeout *timeout, size_t *n_ready)
	Poll for I/O readiness. More...
ESOCK_Type	POLLABLE_What (POLLABLE)
	Identifies a non-NULL POLLABLE. More...
POLLABLE	POLLABLE_FromSOCK (SOCK)
	Conversion utilities from handles to POLLABLEs, and back. More...
POLLABLE	POLLABLE_FromLSOCK (LSOCK)
POLLABLE	POLLABLE_FromTRIGGER (TRIGGER)
SOCK	POLLABLE_ToSOCK (POLLABLE)
LSOCK	POLLABLE_ToLSOCK (POLLABLE)
TRIGGER	POLLABLE_ToTRIGGER (POLLABLE)
int	SOCK_ntoa (unsigned int addr, char *buf, size_t bufsize)
	Convert IP address to a string in dotted notation. More...
int	SOCK_isipEx (const char *host, int fullquad)
	Check whether the given string represents a valid IPv4 address. More...
int	SOCK_isip (const char *host)
	Equivalent of SOCK_isip(host, 0) More...
int	SOCK_IsLoopbackAddress (unsigned int ip)
	Check whether an address is a loopback one. More...
unsigned int	SOCK_HostToNetLong (unsigned int value)
	See man for the BSDisms, htonl() and htons(). More...
unsigned short	SOCK_HostToNetShort (unsigned short value)
	See man for the BSDisms, htonl() and htons(). More...
unsigned int	SOCK_htonl (unsigned int)
unsigned short	SOCK_htons (unsigned short)
int	SOCK_gethostnameEx (char *name, size_t namelen, ESwitch log)
	Get the local host name. More...
int	SOCK_gethostname (char *name, size_t namelen)
	Same as SOCK_gethostnameEx(,,<current API data logging>) More...
unsigned int	SOCK_gethostbynameEx (const char *hostname, ESwitch log)
	Find and return IPv4 address of a named host. More...
unsigned int	SOCK_gethostbyname (const char *hostname)
	Same as SOCK_gethostbynameEx(,<current API data logging>) More...
const char *	SOCK_gethostbyaddrEx (unsigned int addr, char *name, size_t namelen, ESwitch log)
	Take IPv4 host address (in network byte order) or 0 for current host, and fill out the provided buffer with the name, which the address corresponds to (in case of multiple names the primary name is used). More...
const char *	SOCK_gethostbyaddr (unsigned int addr, char *name, size_t namelen)
	Same as SOCK_gethostbyaddrEx(,,<current API data logging>) More...
unsigned int	SOCK_GetLoopbackAddress (void)
	Get loopback IPv4 address. More...
unsigned int	SOCK_GetLocalHostAddress (ESwitch reget)
	Get (and cache for faster follow-up retrievals) IPv4 address of local host. More...
const char *	SOCK_StringToHostPort (const char *str, unsigned int *host, unsigned short *port)
	Read (skipping leading blanks) "[host][:port]" from a string stopping at either EOL or a blank character. More...
size_t	SOCK_HostPortToString (unsigned int host, unsigned short port, char *buf, size_t bufsize)
	Print numeric string "host:port" into a buffer provided, not to exceed 'bufsize' bytes (including the teminating '\0' character). More...
void	SOCK_SetupSSL (FSSLSetup setup)
	Store SSL setup callback until actual initialization. More...
EIO_Status	SOCK_SetupSSLEx (FSSLSetup setup)
	Take SSL setup callback, and then init the entire API (SOCK + SSL). More...
const char *	SOCK_SSLName (void)
	Return an SSL provider name (in a const static storage), with special considerations: return NULL if SSL has not been set up (yet), and return "" if SSL has not been (properly) initialized for use. More...