Wrapper for the C concept of a socket. More...

#include <rw/network/RWSocket.h>

Inheritance diagram for RWSocket:

Public Member Functions
	RWSocket ()

	RWSocket (const RWSocket &s)

	RWSocket (const RWSockType &socketType)

	RWSocket (SOCKET existingSocket)

RWSocket	accept (RWSockAddr *addr=0) const

void	bind (const RWSockAddrBase &address)

void	close ()

void	closesocket ()

void	connect (const RWSockAddrBase &address)

RWSockAddr	getpeername () const

SOCKET	getSocket () const

RWSockAddr	getsockname () const

void	getsockopt (int level, int option, void optval, RWSockLenType optlen) const

int	getsockopt (int option) const

RWSockType	getsocktype () const

RWCString	id (unsigned level=0) const

int	ioctl (long cmd) const

void	ioctl (long cmd, int arg) const

void	ioctl (long cmd, void *arg) const

int	ioctlsocket (long cmd) const

void	ioctlsocket (long cmd, int arg) const

void	ioctlsocket (long cmd, void *arg) const

bool	isValid () const

void	listen (const RWSockAddrBase &addr, int backlog=5)

void	listen (int backlog=5) const

RWSocket &	operator= (const RWSocket &s)

int	recv (char buf, int len, int flags=0, RWNetBuf::State s=0) const

RWNetBuf	recv (int flags=0) const

int	recvAtLeast (char buf, int len, int n, RWNetBuf::State s=0) const

RWNetBuf	recvAtLeast (int n) const

int	recvfrom (char buf, int len, RWSockAddr addr=0, int flags=0, RWNetBuf::State *state=0) const

RWNetBuf	recvfrom (RWSockAddr *addr=0, int flags=0) const

int	recvmsg (msghdr msg, int flags=0, RWNetBuf::State s=0) const

int	send (const char *buf, int len, int flags=0) const

int	send (const RWCString &buf, int flags=0) const

void	sendAtLeast (const char *buf, int len) const

int	sendAtLeast (const char *buf, int len, int n) const

void	sendAtLeast (const RWCString &buf) const

int	sendAtLeast (const RWCString &buf, int n) const

int	sendmsg (msghdr *msg, int flags=0) const

int	sendto (const char *buf, int len, const RWSockAddrBase &to, int flags=0) const

int	sendto (const RWCString &buf, const RWSockAddrBase &to, int flags=0) const

void	setsockopt (int level, int option, void *optval, int optlen) const

void	setsockopt (int option, int optval) const

void	shutdown (int how=2) const

void	shutdownread () const

void	shutdownwrite () const

void	socket (const RWSockType &type)

Protected Member Functions
void	clearError () const

int	lastError () const

void	raise (const char *funcName) const

void	raise (const char *funcName, int err) const

void	raiseUnlessWouldBlock (const char *funcName) const

void	raiseUnlessWouldBlock (const char *funcName, int err) const

Static Protected Member Functions
static void	doRaise (int err, const char *funcName)

Protected Attributes
SOCKET	socket_

Related Symbols
(Note that these are not member symbols.)
bool	operator!= (const RWSocket &lhs, const RWSocket &rhs)

std::ostream &	operator<< (std::ostream &, const RWSocket &sock)

bool	operator== (const RWSocket &lhs, const RWSocket &rhs)

void	rwSetBlocking (RWSocket &s)

void	rwSetNonBlocking (RWSocket &s)

#define	SET_BLOCKING(rwsocket)

#define	SET_NON_BLOCKING(rwsocket)

typedef int	SOCKET

Detailed Description

RWSocket is a wrapper for the C concept of a socket. Its member functions correspond exactly to the C functions in the Berkeley sockets API. Typically, RWSocket member functions have the same names as the corresponding C API functions, but the arguments and return values may be different to reflect the C++ environment. For example, many member functions have default arguments to handle the most common cases. Some member functions take alternate parameter types that simplify the interface (for example, using the RWSockAddrBase class instead of the sockaddr structure). Sometimes, multiple overloads of a member function exist to provide alternate APIs for different occasions.

Almost all Berkeley sockets calls that use a single socket are encapsulated in this class. Omitted calls include:

The database calls of form getXbyY (for example, gethostbyname()), and IP address conversion routines (for example, inet_ntoa()). These are encapsulated by the RWInetHost and RWInetPort classes.
The host-network conversion calls, such as htons(). These calls are not needed – the C++ API does the conversions automatically.
select(). This is encapsulated by the RWSocketAttribute class.

In addition to the functions that match the sockets API, some convenience functions are included. They are id(), isValid(), getSocket(), recvAtLeast(), and sendAtLeast().

The socket is not shut down by a destructor. It must be explicitly shut down by calling close(), closesocket(), or shutdown(). Use the RWPortal layer for objects that close the portal automatically using a destructor.

RWSocket has no state. All state (such as whether the socket blocks) is kept in the communications channel.

The Networking package provides a C++ wrapper for the native socket API. As a result, return values from socket API calls are returned to the caller unaltered.

Note: This can result in different return values and, in some cases, different behavior between calls to the same member functions on different platforms (BSD or Winsock, for instance).

For example, a connect call on a non-blocking socket returns with EINPROGRESS from BSD, but returns with WSAVEWOULDBLOCK from Winsock. You should consult your implementation-specific user's guide to identify expected behavior.

Constructor & Destructor Documentation

◆ RWSocket() [1/4]

RWSocket::RWSocket ( )

The default constructor sets the socket to an invalid state. You must initialize it with a call to socket(), connect(), bind(), or listen() before it can be used.

◆ RWSocket() [2/4]

RWSocket::RWSocket ( const RWSocket & s )

Creates an RWSocket that encapsulates the same C socket as s.

◆ RWSocket() [3/4]

RWSocket::RWSocket ( const RWSockType & socketType )

Creates an unconnected socket of the specified type. The resulting socket must be bound to an address using bind(), connect(), or listen() before it can be used.

◆ RWSocket() [4/4]

RWSocket::RWSocket ( SOCKET existingSocket )

Creates an RWSocket that encapsulates the C socket.

Member Function Documentation

◆ accept()

RWSocket RWSocket::accept ( RWSockAddr * addr = 0 ) const

Accepts a connection that is waiting at this socket. A queue for incoming connections must first be created using listen(). If addr is non-null, the peer's address is returned in addr. You can also get this information by calling getpeername() on the returned RWSocket.

If the socket is set to block (the default), then accept() blocks until a connection request arrives. If the socket is set to be non-blocking, accept() returns right away. If no connections are available, the returned socket is invalid (use isValid() to check) and *addr is unchanged.

◆ bind()

void RWSocket::bind ( const RWSockAddrBase & address )

Assigns an address to an as-yet unnamed socket. This function is used primarily by servers that need to specify the port on which they wait for connections.

Note: When the bind() member function is invoked on an uninitialized socket, the function initializes the socket and sets the SO_REUSEADDR option on the socket. If you do not want this option to be set, call the socket() member function to initialize the socket before you invoke bind(). See section "Socket Security" under Chapter 8, "The Windows Socket Adapter" in the Essential Networking Module User's Guide for more information.

◆ clearError()

void RWSocket::clearError ( ) const

protected

Sets the error code to no error. To make your application portable, use this function instead of the underlying OS specific function calls.

◆ close()

void RWSocket::close ( )

Terminates the connection and removes the socket. The socket is set to an invalid state. Unless this socket is being shared with another process, the resources used to maintain the socket are deallocated and any unread data is discarded.

◆ closesocket()

void RWSocket::closesocket ( )

Alias for close().

◆ connect()

void RWSocket::connect ( const RWSockAddrBase & address )

Connects to a remote socket. If it is a stream socket, connect() performs the initial handshaking with the remote side. If it is a datagram socket, connect() sets up the target for communication, but data is not sent. If the socket has not been initialized with socket(), then connect() initializes it.

◆ doRaise()

static void RWSocket::doRaise	(	int	err,
		const char *	funcName )

staticprotected

Deprecated: As of SourcePro 4, use raise(const char*, int) instead.

Throws an RWSocketError exception based on the value of the parameter err.

◆ getpeername()

RWSockAddr RWSocket::getpeername ( ) const

Returns the address of the peer connected to this socket.

◆ getSocket()

SOCKET RWSocket::getSocket ( ) const

inline

Returns the C API socket descriptor encapsulated in RWSocket.

◆ getsockname()

RWSockAddr RWSocket::getsockname ( ) const

Returns the address of this socket.

◆ getsockopt() [1/2]

void RWSocket::getsockopt	(	int	level,
		int	option,
		void *	optval,
		RWSockLenType *	optlen ) const

Determines a socket option setting.

◆ getsockopt() [2/2]

int RWSocket::getsockopt ( int option ) const

Determines a socket option setting. Assumes the SOL_SOCKET level and an integer option, which is the usual case.

◆ getsocktype()

RWSockType RWSocket::getsocktype ( ) const

Returns the type information for this socket.

◆ id()

RWCString RWSocket::id ( unsigned level = 0 ) const

Returns a string describing self. The verbosity of the output is controlled by level, where level=0 is the most basic output, and level=9 is the most verbose. If not specified, a default value of 0 is used and is guaranteed not to block.

Grammar Definitions

ocal_addr ::= <the result of getsockname().id(level> peer_addr ::= <the result of getpeername().id(level>

Socket State	Output Grammar
isValid() == `false`	`"invalid"`
`bind()` call failed	`"no address"`
connected	`local_addr "-->" peer_addr`
bound	`local_addr`

◆ ioctl() [1/3]

int RWSocket::ioctl ( long cmd ) const

Gets or retrieves socket operating parameters. This overload is useful for commands that return ints (like FIONREAD or SIOCATMARK).

◆ ioctl() [2/3]

void RWSocket::ioctl	(	long	cmd,
		int	arg ) const

Gets or retrieves socket operating parameters. This overload is useful for commands that expect an integer argument and return nothing (such as FIONBIO).

This function is commonly used to set blocking or non-blocking mode on a socket. To set a socket to non-blocking, use ioctl(FIONBIO,1). To set it to blocking, use ioctl(FIONBIO,0).

Note: You can also use the global functions rwSetBlocking() and rwSetNonBlocking() to set the blocking mode on an RWSocket.

◆ ioctl() [3/3]

void RWSocket::ioctl	(	long	cmd,
		void *	arg ) const

Gets or retrieves socket operating parameters.

◆ ioctlsocket() [1/3]

int RWSocket::ioctlsocket ( long cmd ) const

Alias for ioctl(long) const

◆ ioctlsocket() [2/3]

void RWSocket::ioctlsocket	(	long	cmd,
		int	arg ) const

Alias for ioctl(long,int) const

◆ ioctlsocket() [3/3]

void RWSocket::ioctlsocket	(	long	cmd,
		void *	arg ) const

Alias for ioctl(long,void*) const

◆ isValid()

bool RWSocket::isValid ( ) const

Verifies that the socket is ready for use.

◆ lastError()

int RWSocket::lastError ( ) const

protected

Returns the last error on this socket. To make your application portable, use this function instead of the underlying OS specific function calls.

◆ listen() [1/2]

void RWSocket::listen	(	const RWSockAddrBase &	addr,
		int	backlog = 5 )

Prepares a socket to accept incoming connections. The backlog parameter specifies the number of incoming connection requests that the protocol software enqueues while a connection is being processed.

Note: When the listen() member function is invoked on an uninitialized socket, the function initializes the socket and sets the SO_REUSEADDR option on the socket. If you do not want this option to be set, call the socket() member function to initialize the socket before you invoke listen(). See section "Socket Security" under Chapter 8, "The Windows Socket Adapter" in the Essential Networking Module User's Guide for more information.

◆ listen() [2/2]

void RWSocket::listen ( int backlog = 5 ) const

Prepares a bound socket to accept incoming connections. The backlog parameter specifies the number of incoming connection requests that the protocol software enqueues while a connection is being processed.

◆ operator=()

RWSocket & RWSocket::operator= ( const RWSocket & s )

Assigns the underlying C socket from s to self. Both s and self will share the same underlying C socket.

◆ raise() [1/2]

void RWSocket::raise ( const char * funcName ) const

protected

Deprecated: As of SourcePro 4, use raise(const char*, int) in conjunction with lastError().

◆ raise() [2/2]

void RWSocket::raise	(	const char *	funcName,
		int	err ) const

protected

Throws an RWSocketError exception based on the error code passed in the parameter.

◆ raiseUnlessWouldBlock() [1/2]

void RWSocket::raiseUnlessWouldBlock ( const char * funcName ) const

protected

Deprecated: As of SourcePro 4, use raiseUnlessWouldBlock(const char*, int) in conjunction with lastError().

◆ raiseUnlessWouldBlock() [2/2]

void RWSocket::raiseUnlessWouldBlock	(	const char *	funcName,
		int	err ) const

protected

Throws an RWSocketError exception based on the error code passed in the parameter.

◆ recv() [1/2]

int RWSocket::recv	(	char *	buf,
		int	len,
		int	flags = 0,
		RWNetBuf::State *	s = 0 ) const

Receives data from the socket. recv() is used to read data from a connected socket. The flags parameter is formed by ORing one or more of MSG_OOB (out of band data), or MSG_PEEK (peek at data on the socket but do not consume it). The variant that uses an explicit buffer returns the number of bytes actually received. This may be zero in the case of a non-blocking socket without data waiting. If an error occurs, an RWSocketError exception is thrown.

◆ recv() [2/2]

RWNetBuf RWSocket::recv ( int flags = 0 ) const

Receives data from the socket. recv() is used to read data from a connected socket. The flags parameter is formed by ORing one or more of MSG_OOB (out of band data), or MSG_PEEK (peek at data on the socket but do not consume it). The variant that uses an explicit buffer returns the number of bytes actually received. This may be zero in the case of a non-blocking socket without data waiting. If an error occurs, an RWSocketError exception is thrown.

◆ recvAtLeast() [1/2]

int RWSocket::recvAtLeast	(	char *	buf,
		int	len,
		int	n,
		RWNetBuf::State *	s = 0 ) const

This is guaranteed to either receive n characters or throw an exception. The call is only valid for stream sockets. The implementation loops over recv() until all data has been received. An RWNetCantRecvError exception is thrown if one of the calls to recv() returns no data. If you call recvAtLeast() on a non-blocking socket, it will probably throw an exception.

◆ recvAtLeast() [2/2]

RWNetBuf RWSocket::recvAtLeast ( int n ) const

This is guaranteed to either receive n characters or throw an exception. The call is only valid for stream sockets. The implementation loops over recv() until all data has been received. An RWNetCantRecvError exception is thrown if one of the calls to recv() returns no data. If you call recvAtLeast() on a non-blocking socket, it will probably throw an exception.

◆ recvfrom() [1/2]

int RWSocket::recvfrom	(	char *	buf,
		int	len,
		RWSockAddr *	addr = 0,
		int	flags = 0,
		RWNetBuf::State *	state = 0 ) const

Receives data from the socket, and can be used on any socket. The flags parameter is formed by ORing one or more of MSG_OOB (out of band data) or MSG_PEEK (peek at data on the socket but do not consume it). addr, if it is specified and if the socket is a datagram socket, becomes the address of the originator of the message. This overload returns the number of bytes actually received. This may be zero in the case of a non-blocking socket without data waiting.

◆ recvfrom() [2/2]

RWNetBuf RWSocket::recvfrom	(	RWSockAddr *	addr = 0,
		int	flags = 0 ) const

Receives data from the socket, and can be used on any socket. The flags parameter is formed by ORing one or more of MSG_OOB (out of band data) or MSG_PEEK (peek at data on the socket but do not consume it). addr, if it is specified and if the socket is a datagram socket, becomes the address of the originator of the message.

◆ recvmsg()

int RWSocket::recvmsg	(	msghdr *	msg,
		int	flags = 0,
		RWNetBuf::State *	s = 0 ) const

Alias for recvfrom(char*,int,RWSockAddr*,int,RWNetBuf::State*)const.

Condition:: This method is available only on systems that provide struct msghdr.

◆ send() [1/2]

int RWSocket::send	(	const char *	buf,
		int	len,
		int	flags = 0 ) const

Sends data from a connected socket. These functions return the number of bytes sent. If an error occurs, an RWSocketError exception is thrown.

Note: When calling send(), the application must check the number of bytes sent, and resend if necessary. The sendAtLeast() method guarantees the transmission of the number of bytes specified (or the entire buffer if no size is specified).; Sending data on a closed socket may result in the generation of a SIGPIPE signal from the underlying socket library. Avoid this by checking that the socket's sock_attr_canwrite attribute is true before each call to send(). Refer to RWSocketAttribute for details on checking socket attributes. Alternatively, you can use a signal handler to explicitly handle or ignore SIGPIPE.

◆ send() [2/2]

int RWSocket::send	(	const RWCString &	buf,
		int	flags = 0 ) const

Sends data from a connected socket. These functions return the number of bytes sent. If an error occurs, an RWSocketError exception is thrown.

Note: When calling send(), the application must check the number of bytes sent, and resend if necessary. The sendAtLeast() method guarantees the transmission of the number of bytes specified (or the entire buffer if no size is specified).; Sending data on a closed socket may result in the generation of a SIGPIPE signal from the underlying socket library. Avoid this by checking that the socket's sock_attr_canwrite attribute is true before each call to send(). Refer to RWSocketAttribute for details on checking socket attributes. Alternatively, you can use a signal handler to explicitly handle or ignore SIGPIPE.

◆ sendAtLeast() [1/4]

void RWSocket::sendAtLeast	(	const char *	buf,
		int	len ) const

Guaranteed to send at least n characters or the entire buffer if n is not specified. This call is valid only for stream sockets. The implementation loops over send() to send the data. If any of the calls to send cannot send any data, an RWNetCantSendError exception is thrown. If you call sendAtLeast() on a non-blocking socket, it will probably throw an exception if n is greater than the amount of unused space in the system's buffer for the socket.

◆ sendAtLeast() [2/4]

int RWSocket::sendAtLeast	(	const char *	buf,
		int	len,
		int	n ) const

Guaranteed to send at least n characters or the entire buffer if n is not specified. This call is valid only for stream sockets. The implementation loops over send() to send the data. If any of the calls to send cannot send any data, an RWNetCantSendError exception is thrown. If you call sendAtLeast() on a non-blocking socket, it will probably throw an exception if n is greater than the amount of unused space in the system's buffer for the socket.

◆ sendAtLeast() [3/4]

void RWSocket::sendAtLeast ( const RWCString & buf ) const

Guaranteed to send at least n characters or the entire buffer if n is not specified. This call is valid only for stream sockets. The implementation loops over send() to send the data. If any of the calls to send cannot send any data, an RWNetCantSendError exception is thrown. If you call sendAtLeast() on a non-blocking socket, it will probably throw an exception if n is greater than the amount of unused space in the system's buffer for the socket.

◆ sendAtLeast() [4/4]

int RWSocket::sendAtLeast	(	const RWCString &	buf,
		int	n ) const

Guaranteed to send at least n characters or the entire buffer if n is not specified. This call is valid only for stream sockets. The implementation loops over send() to send the data. If any of the calls to send cannot send any data, an RWNetCantSendError exception is thrown. If you call sendAtLeast() on a non-blocking socket, it will probably throw an exception if n is greater than the amount of unused space in the system's buffer for the socket.

◆ sendmsg()

int RWSocket::sendmsg	(	msghdr *	msg,
		int	flags = 0 ) const

Alias for sendto(const char*, int, const RWSockAddrBase&, int) const.

Condition:: This method is available only on systems that provide struct msghdr.

◆ sendto() [1/2]

int RWSocket::sendto	(	const char *	buf,
		int	len,
		const RWSockAddrBase &	to,
		int	flags = 0 ) const

Send data from a socket, and can be used on any socket. The to parameter is ignored for a connected socket. These functions return the number of bytes sent. This is zero if the socket is non-blocking and the internal buffer for the socket is full.

◆ sendto() [2/2]

int RWSocket::sendto	(	const RWCString &	buf,
		const RWSockAddrBase &	to,
		int	flags = 0 ) const

Send data from a socket, and can be used on any socket. The to parameter is ignored for a connected socket. These functions return the number of bytes sent. This is zero if the socket is non-blocking and the internal buffer for the socket is full.

◆ setsockopt() [1/2]

void RWSocket::setsockopt	(	int	level,
		int	option,
		void *	optval,
		int	optlen ) const

Sets a socket option setting. The second function assumes the SOL_SOCKET level and an integer option, which is the usual case.

◆ setsockopt() [2/2]

void RWSocket::setsockopt	(	int	option,
		int	optval ) const

Sets a socket option setting. The second function assumes the SOL_SOCKET level and an integer option, which is the usual case.

◆ shutdown()

void RWSocket::shutdown ( int how = 2 ) const

Shuts down either the reading side (how=0), the writing side (how=1), or both sides (how=2) of a full duplex connection. Use close() or closesocket() to deallocate the socket resources.

◆ shutdownread()

void RWSocket::shutdownread ( ) const

inline

Shuts down one side of the connection.

◆ shutdownwrite()

void RWSocket::shutdownwrite ( ) const

inline

Shuts down one side of the connection.

◆ socket()

void RWSocket::socket ( const RWSockType & type )

Creates an unconnected socket of the specified type. The resulting socket must be bound to an address using bind(), connect(), or listen() before it can be used.

Friends And Related Symbol Documentation

◆ operator!=()

bool operator!=	(	const RWSocket &	lhs,
		const RWSocket &	rhs )

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	,
		const RWSocket &	sock )

Note: This class does not have an extraction (>>) operator.

◆ operator==()

bool operator==	(	const RWSocket &	lhs,
		const RWSocket &	rhs )

◆ rwSetBlocking()

void rwSetBlocking ( RWSocket & s )

◆ rwSetNonBlocking()

void rwSetNonBlocking ( RWSocket & s )

◆ SET_BLOCKING

#define SET_BLOCKING ( rwsocket )

Deprecated: As of SourcePro 1, use rwSetBlocking() instead.

◆ SET_NON_BLOCKING

#define SET_NON_BLOCKING ( rwsocket )

Deprecated: As of SourcePro 1, use rwSetNonBlocking() instead.

◆ SOCKET

typedef int SOCKET

Member Data Documentation

◆ socket_

SOCKET RWSocket::socket_

protected

Contains the socket itself. No other state is stored in this class. All state information related to the socket is kept in the socket.

SourcePro® API Reference Guide

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Related Symbols

Detailed Description

Constructor & Destructor Documentation

◆ RWSocket() [1/4]

◆ RWSocket() [2/4]

◆ RWSocket() [3/4]

◆ RWSocket() [4/4]

Member Function Documentation

◆ accept()

◆ bind()

◆ clearError()

◆ close()

◆ closesocket()

◆ connect()

◆ doRaise()

◆ getpeername()

◆ getSocket()

◆ getsockname()

◆ getsockopt() [1/2]

◆ getsockopt() [2/2]

◆ getsocktype()

◆ id()

◆ ioctl() [1/3]

◆ ioctl() [2/3]

◆ ioctl() [3/3]

◆ ioctlsocket() [1/3]

◆ ioctlsocket() [2/3]

◆ ioctlsocket() [3/3]

◆ isValid()

◆ lastError()

◆ listen() [1/2]

◆ listen() [2/2]

◆ operator=()

◆ raise() [1/2]

◆ raise() [2/2]

◆ raiseUnlessWouldBlock() [1/2]

◆ raiseUnlessWouldBlock() [2/2]

◆ recv() [1/2]

◆ recv() [2/2]

◆ recvAtLeast() [1/2]

◆ recvAtLeast() [2/2]

◆ recvfrom() [1/2]

◆ recvfrom() [2/2]

◆ recvmsg()

◆ send() [1/2]

◆ send() [2/2]

◆ sendAtLeast() [1/4]

◆ sendAtLeast() [2/4]

◆ sendAtLeast() [3/4]

◆ sendAtLeast() [4/4]

◆ sendmsg()

◆ sendto() [1/2]

◆ sendto() [2/2]

◆ setsockopt() [1/2]

◆ setsockopt() [2/2]

◆ shutdown()

◆ shutdownread()

◆ shutdownwrite()

◆ socket()

Friends And Related Symbol Documentation

◆ operator!=()

◆ operator<<()

◆ operator==()

◆ rwSetBlocking()

◆ rwSetNonBlocking()

◆ SET_BLOCKING

◆ SET_NON_BLOCKING

◆ SOCKET

Member Data Documentation

◆ socket_