Encapsulation of a Windows socket. More...

#include <wsockstream.h>

Inheritance diagram for mlib::sock:

Public Types
enum	shuthow { shut_read = 0 , shut_write = 1 , shut_readwrite = 2 }
	operation blocked by shutdown function More...

enum	mflags { none = 0 , out_of_band = MSG_OOB , peek = MSG_PEEK , dont_route = MSG_DONTROUTE , wait_all = MSG_WAITALL }
	Flags for send/receive operations. More...

Public Member Functions
	sock ()
	Default constructor creates a closed socket.

	sock (SOCKET soc)
	Create a sock object from a socket handle.

	sock (int type, int domain=AF_INET, int proto=0)
	Construct a sock object for the specified domain.

	sock (const sock &)
	Copy constructor.

	sock (sock &&)
	Move constructor.

virtual	~sock ()
	Destructor.

sock &	operator= (const sock &)
	Assignment operator.

sock &	operator= (sock &&)
	Move assignment.

HANDLE	handle () const
	Retrieve Windows socket handle.

bool	operator== (const sock &other) const
	Equality comparison operator.

bool	operator!= (const sock &other) const
	Inequality comparison operator.

virtual erc	open (int type, int domain=AF_INET, int proto=0)
	Open the socket.

virtual erc	close ()
	Close socket.

virtual erc	shutdown (shuthow sh) const
	Disables sends or receives on socket.

virtual bool	is_open () const
	Check if socket is opened.

size_t	recv (void *buf, size_t maxlen, mflags msgf=mflags::none) const
	Receives data from socket.

size_t	recvfrom (sockaddr &sa, void *buf, size_t maxlen, mflags msgf=mflags::none) const
	Receives data from socket.

size_t	send (const void *buf, size_t len, mflags msgf=mflags::none) const
	Send data to the connected peer.

template<typename T >
size_t	send (std::basic_string< T > buf, mflags msgf=mflags::none) const
	Send data to connected peer.

size_t	sendto (const sockaddr &sa, const void *buf, size_t len, mflags msgf=mflags::none) const
	Send data to a peer.

template<typename T >
size_t	sendto (const sockaddr &sa, std::basic_string< T > buf, mflags msgf=mflags::none) const
	Send data to a peer.

int	sendtimeout (int wp_sec) const
	Set send timeout value.

int	sendtimeout () const
	Returns the send timeout value.

int	recvtimeout (int wp_sec) const
	Set receive timeout value.

int	recvtimeout () const
	Returns the send timeout value.

bool	is_readready (int wp_sec, int wp_usec=0) const
	Check if socket is "readable".

bool	is_writeready (int wp_sec, int wp_usec=0) const
	Check if socket is "writable".

bool	is_exceptionpending (int wp_sec, int wp_usec=0) const
	Check if socket has OOB data or any exceptional error conditions.

unsigned int	nread () const
	Return number of characters waiting in socket's buffer.

erc	bind (const inaddr &) const
	Associates a local address with the socket.

erc	bind () const
	Associates a local address with the socket.

erc	connect (const inaddr &peer) const
	Establishes a connection to specified peer.

erc	connect (const inaddr &peer, int wp_sec) const
	Establishes a connection to a specified address.

erc	listen (int num=SOMAXCONN) const
	Places the socket in a state in which it is listening for incoming connections.

erc	accept (sock &client, inaddr *sa=nullptr) const
	Permits an incoming connection attempt on the socket.

erc	accept (sock &client, int wp_sec, inaddr *sa=nullptr) const
	Permits an incoming connection attempt on the socket.

erc	name (inaddr &addr) const
	Return the local name for the object.

erc	peer (inaddr &addr) const
	Retrieves the name of the peer to which the socket is connected.

int	getopt (int op, void *buf, int len, int level=SOL_SOCKET) const
	Returns a socket option.

erc	setopt (int op, void *buf, int len, int level=SOL_SOCKET) const
	Set a socket option.

int	gettype () const
	Return socket type (SOCK_DGRAM or SOCK_STREAM)

int	clearerror () const
	Return and clear the socket error flag.

bool	debug () const
	Return the debug flag.

void	debug (bool opt) const
	Set the debug flag.

bool	reuseaddr () const
	Return the "reuse address" flag.

void	reuseaddr (bool opt) const
	Set the "reuse address" flag.

bool	keepalive () const
	Return "keep alive" flag.

void	keepalive (bool opt) const
	Set "keep alive" flag.

bool	dontroute () const
	Return status of "don't route" flag.

void	dontroute (bool opt) const
	Turn on or off the "don't route" flag.

bool	broadcast () const
	Return "broadcast" option.

void	broadcast (bool opt) const
	Turn on or off the "broadcast" option.

bool	oobinline () const
	Return the status of the OOB_INLINE flag.

void	oobinline (bool opt) const
	Set the status of the OOB_INLINE flag.

int	sendbufsz () const
	Return buffer size for send operations.

void	sendbufsz (size_t sz) const
	Set buffer size for send operations.

int	recvbufsz () const
	Return buffer size for receive operations.

void	recvbufsz (size_t sz) const
	Set buffer size for receive operations.

void	blocking (bool on_off)
	Change blocking mode.

erc	setevent (HANDLE evt, long mask) const
	Associate an event object with this socket.

long	enumevents () const
	Indicates which of the FD_XXX network events have occurred.

void	linger (bool on_off, unsigned short seconds) const
	Turn on or off linger mode and lingering timeout.

bool	linger (unsigned short *seconds=0) const
	Return linger mode and lingering timeout.

Static Public Member Functions
static errfac &	Errors ()
	Return error facility used by all sock-derived classes.

static void	Errors (errfac &facitlity)
	Set the error facility use by all sock-derived classes.

Static Protected Member Functions
static erc	last_error ()
	Return an error code with the value returned by WSAGetLastError.

Friends
class	inaddr

struct	sock_initializer

Detailed Description

Encapsulation of a Windows socket.

We keep a reference counter associated with each sock object because it is more expensive to duplicate a socket handle using WSADuplicateHandle.

Member Enumeration Documentation

◆ mflags

enum mlib::sock::mflags

Flags for send/receive operations.

Enumerator
none	no flags
out_of_band	send out of band data
peek	don't remove data from the input queue
dont_route	data should not be routed
wait_all	wait until buffer full or connection closed

◆ shuthow

enum mlib::sock::shuthow

operation blocked by shutdown function

Enumerator
shut_read	blocked for reading
shut_write	blocked for writing
shut_readwrite	blocked for both

Constructor & Destructor Documentation

◆ sock() [1/3]

mlib::sock::sock	(	int	type,
		int	domain = `AF_INET`,
		int	proto = `0`
	)

explicit

Construct a sock object for the specified domain.

Parameters

type	socket type (SOCK_DGRAM or SOCK_STREAM)
domain	normally AF_INET for TCP/IP sockets
proto	protocol

Throws an exception if the socket cannot be created.

◆ sock() [2/3]

mlib::sock::sock ( const sock & sb )

Copy constructor.

The new object shares the handle with the original. This constructor only increments the reference counter associated with the socket handle.

◆ sock() [3/3]

mlib::sock::sock ( sock && sb )

Move constructor.

The new object takes over the handle of the original.

◆ ~sock()

mlib::sock::~sock ( )

virtual

Destructor.

If the 'ref_count' counter is 0, calls closesocket() to free the Winsock handle.

Member Function Documentation

◆ accept()

erc mlib::sock::accept	(	sock &	client,
		int	wp_sec,
		inaddr *	addr = `nullptr`
	)		const

Permits an incoming connection attempt on the socket.

Parameters

client	socket for communication with connected peer.
addr	optional pointer to address of the connecting peer.
wp_sec	timeout interval (in seconds)

The function waits the specified interval for a connecting peer. If no connection request is made the function returns WSAETIMEDOUT.

◆ bind()

erc mlib::sock::bind ( ) const

Associates a local address with the socket.

Winsock assigns a unique port to the socket. The application can use name() after calling bind to learn the address and the port that has been assigned to it.

◆ blocking()

void mlib::sock::blocking ( bool on_off )

inline

Change blocking mode.

sock objects are created by default as blocking sockets. They can be turned into non-blocking sockets using this function.

◆ broadcast()

void mlib::sock::broadcast ( bool b ) const

inline

Turn on or off the "broadcast" option.

Note: Socket semantics require that an application set this option before attempting to send a datagram to broadcast address.

◆ clearerror()

int mlib::sock::clearerror ( ) const

inline

Return and clear the socket error flag.

Returns: Error flag status

The per socket-based error code is different from the per thread error code that is handled using the WSAGetLastError function call. A successful call using the socket does not reset the socket based error code returned by this function.

◆ connect()

erc mlib::sock::connect	(	const inaddr &	peer,
		int	wp_sec
	)		const

Establishes a connection to a specified address.

Parameters

peer	address of peer
wp_sec	timeout interval (in seconds)

Waits the specified interval for a connection to be established. If it is not established the function returns WSAETIMEDOUT.

◆ enumevents()

long mlib::sock::enumevents ( ) const

inline

Indicates which of the FD_XXX network events have occurred.

The function reports only network activity and errors for which setevent() has been called.

◆ getopt()

int mlib::sock::getopt	(	int	op,
		void *	buf,
		int	len,
		int	level = `SOL_SOCKET`
	)		const

inline

Returns a socket option.

Parameters

op	option to return
buf	buffer for option value
len	size of buffer
level	level at which the option is defined

Returns: Size of returned option

◆ is_exceptionpending()

bool mlib::sock::is_exceptionpending	(	int	wp_sec,
		int	wp_usec = `0`
	)		const

Check if socket has OOB data or any exceptional error conditions.

If wp_sec or wp_usec are not 0, the function waits the specified time.

◆ is_readready()

bool mlib::sock::is_readready	(	int	wp_sec,
		int	wp_usec = `0`
	)		const

Check if socket is "readable".

If wp_sec or wp_usec are not 0, the function waits the specified time for the socket to become "readable".

If the socket is currently in the listen state, it will be marked as readable if an incoming connection request has been received such that accept() is guaranteed to complete without blocking. For other sockets, readability means that queued data is available for reading such that a call to recv() or recvfrom() is guaranteed not to block.

◆ is_writeready()

bool mlib::sock::is_writeready	(	int	wp_sec,
		int	wp_usec = `0`
	)		const

Check if socket is "writable".

If wp_sec or wp_usec are not 0, the function waits the specified time for the socket to become "writable".

If the socket is processing a connect call, the socket is writable if the connection establishment successfully completes. If the socket is not processing a connect call, being writable means a send() or sendto() are guaranteed to succeed.

◆ name()

erc mlib::sock::name ( inaddr & addr ) const

Return the local name for the object.

This function is especially useful when a connect() call has been made without doing a bind first or after calling bind() without an explicit address. name function provides the only way to determine the local association that has been set by the system.

◆ oobinline() [1/2]

bool mlib::sock::oobinline ( ) const

inline

Return the status of the OOB_INLINE flag.

If set, OOB data is being received in the normal data stream.

◆ oobinline() [2/2]

void mlib::sock::oobinline ( bool b ) const

inline

Set the status of the OOB_INLINE flag.

If set, OOB data is being received in the normal data stream.

◆ open()

erc mlib::sock::open	(	int	type,
		int	domain = `AF_INET`,
		int	proto = `0`
	)

virtual

Open the socket.

If the socket was previously opened it calls first close().

◆ operator!=()

bool mlib::sock::operator!= ( const sock & other ) const

inline

Inequality comparison operator.

Returns false if both objects have the same handle

◆ operator=()

sock & mlib::sock::operator= ( const sock & rhs )

Assignment operator.

The left hand object shares the handle of the right hand object.

◆ operator==()

bool mlib::sock::operator== ( const sock & other ) const

inline

Equality comparison operator.

Returns true if both objects point to the same underlining socket control structure

◆ peer()

erc mlib::sock::peer ( inaddr & addr ) const

Retrieves the name of the peer to which the socket is connected.

The socket must be connected.

◆ recv()

size_t mlib::sock::recv	(	void *	buf,
		size_t	len,
		mflags	msgf = `mflags::none`
	)		const

Receives data from socket.

Parameters

buf	buffer for received data
len	buffer length
msgf	message flags

Returns: Number of characters received or EOF if connection closed by peer.

◆ recvfrom()

size_t mlib::sock::recvfrom	(	sockaddr &	sa,
		void *	buf,
		size_t	len,
		mflags	msgf = `mflags::none`
	)		const

Receives data from socket.

Parameters

sa	peer address
buf	buffer for received data
len	buffer length
msgf	message flags

Returns: Number of characters received or EOF if connection closed by peer.

◆ recvtimeout()

int mlib::sock::recvtimeout ( int wp_sec ) const

inline

Set receive timeout value.

Parameters

wp_sec timeout value in seconds

Return values

Previous timeout value in seconds

◆ send() [1/2]

size_t mlib::sock::send	(	const void *	buf,
		size_t	len,
		mflags	msgf = `mflags::none`
	)		const

Send data to the connected peer.

Parameters

buf	data to send
len	length of buffer.
msgf	flags (MSG_OOB or MSG_DONTROUTE)

The function returns the number of characters actually sent or EOF if connection was closed by peer.

◆ send() [2/2]

template<typename T >

size_t mlib::sock::send	(	std::basic_string< T >	buf,
		mflags	msgf = `mflags::none`
	)		const

Send data to connected peer.

Parameters

buf	data to send
msgf	flags (MSG_OOB or MSG_DONTROUTE)

The function returns the number of characters actually sent or EOF if connection was closed by peer.

◆ sendtimeout()

int mlib::sock::sendtimeout ( int wp_sec ) const

inline

Set send timeout value.

Parameters

wp_sec timeout value in seconds

Return values

Previous timeout value in seconds

◆ sendto() [1/2]

size_t mlib::sock::sendto	(	const sockaddr &	sa,
		const void *	buf,
		size_t	len,
		mflags	msgf = `mflags::none`
	)		const

Send data to a peer.

Parameters

sa	peer address
buf	data to send
len	length of buffer
msgf	flags (MSG_OOB or MSG_DONTROUTE)

The function returns the number of characters actually sent or EOF if connection was closed by peer.

◆ sendto() [2/2]

template<typename T >

size_t mlib::sock::sendto	(	const sockaddr &	sa,
		std::basic_string< T >	buf,
		mflags	msgf = `mflags::none`
	)		const

Send data to a peer.

Parameters

sa	peer address
buf	data to send
msgf	flags (MSG_OOB or MSG_DONTROUTE)

The function returns the number of characters actually sent or EOF if connection was closed by peer.

◆ setevent()

erc mlib::sock::setevent	(	HANDLE	evt,
		long	mask
	)		const

inline

Associate an event object with this socket.

Parameters

evt	handle to event object
mask	conditions that trigger the event Can be a combination of: FD_READ, FD_WRITE, FD_OOB, FD_ACCEPT, FD_CONNECT, FD_CLOSE

The event object must be a manual event. It will be set to signaled state if the corresponding socket status change.

It is not possible to specify different event objects for different network events.

The function automatically sets socket to nonblocking mode.

◆ setopt()

erc mlib::sock::setopt	(	int	op,
		void *	buf,
		int	len,
		int	level = `SOL_SOCKET`
	)		const

inline

Set a socket option.

Parameters

op	option to return
buf	buffer for option value
len	size of buffer
level	level at which the option is defined

◆ shutdown()

erc mlib::sock::shutdown ( shuthow sh ) const

virtual

Disables sends or receives on socket.

Parameters

sh	describes what types of operation will no longer be allowed

The documentation for this class was generated from the following files:

include/mlib/wsockstream.h
src/wsockstream.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ mflags

◆ shuthow

Constructor & Destructor Documentation

◆ sock() [1/3]

◆ sock() [2/3]

◆ sock() [3/3]

◆ ~sock()

Member Function Documentation

◆ accept()

◆ bind()

◆ blocking()

◆ broadcast()

◆ clearerror()

◆ connect()

◆ enumevents()

◆ getopt()

◆ is_exceptionpending()

◆ is_readready()

◆ is_writeready()

◆ name()

◆ oobinline() [1/2]

◆ oobinline() [2/2]

◆ open()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ peer()

◆ recv()

◆ recvfrom()

◆ recvtimeout()

◆ send() [1/2]

◆ send() [2/2]

◆ sendtimeout()

◆ sendto() [1/2]

◆ sendto() [2/2]

◆ setevent()

◆ setopt()

◆ shutdown()