#include <evo/impl/sysio_sock.h>

Inheritance diagram for IoSocket:

Detailed Description

Socket I/O device (used internally).

This is an internal low-level interface with public members, use Socket instead
Members are public for quick access and simple low-level interface
This does not do any read/write buffering
Implementation is OS specific, low-level error codes can be read from errno
- Windows: This sets errno on error – from WSAGetLastError()
IoSocket::init() (or Socket::sysinit()) should be called as early as possible before using this

Classes
struct	Init
	Used internally to initialize system socket API. More...

Public Types
typedef ExceptionSocketIn	ExceptionInT
	Input exception type for socket stream. More...

typedef ExceptionSocketOut	ExceptionOutT
	Output exception type for socket stream. More...

typedef int	Handle
	System socket handle. More...

typedef int	OptNum
	General number type for socket options. More...

enum	Shutdown { sIN = SHUT_RD, sOUT = SHUT_WR, sINOUT = SHUT_RDWR }
	Used with shutdown(). More...

Public Member Functions
	IoSocket ()
	Constructor. More...

	IoSocket (Handle socket)
	Constructor attaching to existing socket. More...

	~IoSocket ()
	Destructor. More...

bool	accept (Error &err, IoSocket &client_socket, SocketAddressBase *client_address=NULL)
	Accept connection from listening socket. More...

bool	accept_nonblock (Error &err, IoSocket &client_socket, SocketAddressBase *client_address=NULL)
	Accept connection from listening socket and set the new connection as non-blocking. More...

void	attach (Handle socket)
	Attach new socket handle. More...

bool	bind (Error &err, struct sockaddr *address, socklen_t address_len, int socktype=SOCK_DGRAM, int protocol=0)
	Create and bind datagram socket to address. More...

bool	cast (Error &err, int family=AF_INET, int socktype=SOCK_DGRAM, int protocol=0)
	Create unbound datagram socket for casting. More...

void	close ()
	Close connection and socket. More...

bool	connect (Error &err, struct addrinfo *address_info, bool all=true)
	Create and connect socket using address info. More...

bool	connect (Error &err, struct sockaddr *address, socklen_t address_len, int socktype=SOCK_STREAM, int protocol=0)
	Create and connect socket using address. More...

bool	connect_wait (Error &err, ulong timeout_ms)
	Wait until socket connection is established and ready to write. More...

Handle	detach ()
	Detach and return socket handle. More...

Error	getopt (int level, int optname, void *buf, uint &size)
	Get socket option value. More...

bool	isopen () const
	Get whether socket is open. More...

bool	listen (Error &err, struct addrinfo *address_info, int backlog=SOMAXCONN, bool all=true)
	Create and bind socket using address info and listen for connections. More...

bool	listen (Error &err, struct sockaddr *address, socklen_t address_len, int backlog=SOMAXCONN, int socktype=SOCK_STREAM, int protocol=0)
	Create and bind socket to address and listen for connections. More...

ulongl	pos (Error &err)
	Not supported with sockets. More...

ulong	read (Error &err, void *buf, ulong size, ulong timeout_ms=0)
	Read input data from device. More...

ulong	read (Error &err, void *buf, ulong size)

bool	read_wait (Error &err, ulong timeout_ms)
	Wait until socket is ready to read. More...

ulong	readfrom (Error &err, void buf, ulong size, struct sockaddr address=NULL, socklen_t *address_len=NULL, int flags=0)
	Read message from socket device. More...

ulongl	seek (Error &err, ulongl, Seek)
	Not supported with sockets. More...

Error	set_nonblock (bool enable=true)
	Enable/Disable non-blocking I/O. More...

Error	setopt (int level, int optname, const void *buf, uint size)
	Set socket option with new value. More...

bool	shutdown (Shutdown how=sINOUT)
	Shutdown socket communication. More...

ulong	write (Error &err, const void *buf, ulong size, ulong timeout_ms=0)
	Write output data to device. More...

ulong	write (Error &err, const void *buf, ulong size)

bool	write_wait (Error &err, ulong timeout_ms)
	Wait until socket is ready to write. More...

ulong	writeto (Error &err, const void buf, ulong size, const struct sockaddr address, socklen_t address_len, int flags=0)
	Write message to device and socket address. More...

Static Public Member Functions
template<class TOut >
static TOut &	errormsg_out (TOut &out, Error err)
	Write detailed error message with errno to output stream/string. More...

static const Init &	init ()
	Initialize socket library. More...

Public Attributes
bool	autoresume
	Whether to auto-resume I/O operation after signal received [Linux/Unix]. More...

Handle	handle
	Socket handle/descriptor. More...

bool	nonblock
	Whether non-blocking I/O is enabled. More...

ulong	timeout_ms
	Current timeout in milliseconds, 0 for indefinite. More...

Static Public Attributes
static const Handle	INVALID = -1
	Invalid handle value (used internally) More...

static const int	SOCK_ERROR = -1
	Socket error value (used internally) More...

static const bool	STREAM_SEEKABLE = false
	Socket streams are not seekable with Stream. More...

static const ulong	TIMEOUT_DEFAULT = 30000
	Default timeout used in milliseconds. More...

Member Typedef Documentation

◆ ExceptionInT

typedef ExceptionSocketIn ExceptionInT

Input exception type for socket stream.

◆ ExceptionOutT

typedef ExceptionSocketOut ExceptionOutT

Output exception type for socket stream.

◆ Handle

typedef int Handle

System socket handle.

◆ OptNum

typedef int OptNum

General number type for socket options.

Member Enumeration Documentation

◆ Shutdown

enum Shutdown

Used with shutdown().

Enumerator
sIN	Shutdown input (reads) on socket.
sOUT	Shutdown output (writes) on socket.
sINOUT	Shutdown both input and output (reads and writes) on socket.

Constructor & Destructor Documentation

◆ IoSocket() [1/2]

IoSocket ( )

inline

Constructor.

◆ IoSocket() [2/2]

IoSocket ( Handle socket )

inline

Constructor attaching to existing socket.

This is equivalent to using default constructor and calling attach()

Parameters

socket Socket handle to attach

◆ ~IoSocket()

~IoSocket ( )

inline

Destructor.

Calls close().

Member Function Documentation

◆ accept()

bool accept	(	Error &	err,
		IoSocket &	client_socket,
		SocketAddressBase *	client_address = `NULL`
	)

inline

Accept connection from listening socket.

Socket must be in listen mode, see listen()

Parameters

err	Set to error code on failure, ETimeout on timeout
client_socket	Attached to connected client socket on success (unchanged on error)
client_address	Pointer to store client socket address on success (ignored on error), NULL to skip

Returns: Whether connection successfully accepted, false on error

◆ accept_nonblock()

bool accept_nonblock	(	Error &	err,
		IoSocket &	client_socket,
		SocketAddressBase *	client_address = `NULL`
	)

inline

Accept connection from listening socket and set the new connection as non-blocking.

Socket must be in listen mode, see listen()
This is equivalent to accept() then set_nonblock() on the new connection, except may be more efficient on some systems (Linux)

Parameters

err	Set to error code on failure, ETimeout on timeout
client_socket	Attached to connected client socket on success (unchanged on error)
client_address	Pointer to store client socket address on success (ignored on error), NULL to skip

Returns: Whether connection successfully accepted, false on error

◆ attach()

void attach ( Handle socket )

inline

Attach new socket handle.

If socktype is tUNKNOWN, you won't get a client IP address from accept()

Parameters

socket Socket handle to attach

◆ bind()

bool bind	(	Error &	err,
		struct sockaddr *	address,
		socklen_t	address_len,
		int	socktype = `SOCK_DGRAM`,
		int	protocol = `0`
	)

inline

Create and bind datagram socket to address.

Parameters

err	Set to ENone on success, EExist if address/port already used, otherwise set to error code
address	Socket address to bind to, must not be NULL
address_len	Socket address length to bind to, must be positive
socktype	Socket type
protocol	Network protocol, 0 for default

Returns: Whether successful, false on error

◆ cast()

bool cast	(	Error &	err,
		int	family = `AF_INET`,
		int	socktype = `SOCK_DGRAM`,
		int	protocol = `0`
	)

inline

Create unbound datagram socket for casting.

Parameters

err	Set to ENone on success, otherwise set to error code
family	Socket family type (AF_INET, AF_INET6)
socktype	Socket type, SOCK_DGRAM for datagram socket
protocol	Network protocol, 0 for default

Returns: Whether successful, false on error

◆ close()

void close ( )

inline

Close connection and socket.

To gracefully shutdown call shutdown() first, unless there was an error

◆ connect() [1/2]

bool connect	(	Error &	err,
		struct addrinfo *	address_info,
		bool	all = `true`
	)

inline

Create and connect socket using address info.

In blocking mode this blocks while connecting, and could take a while for the implementation to timeout
In non-blocking mode this returns with err=ENonBlock – use write_wait() to wait/poll
This may try to create/connect multiple sockets/addresses, if all fail then err is set according to the "best" case (closest to success)
- This also sets system "errno" accordingly (even in Windows), so it matches err

Parameters

err	Set to ENone on success, otherwise set to error code
address_info	Pointer to addrinfo structure to use (first in linked list)
all	Whether to try all addresses in addrinfo until successful, false to just try the first address

Returns: Whether successful, false on error

◆ connect() [2/2]

bool connect	(	Error &	err,
		struct sockaddr *	address,
		socklen_t	address_len,
		int	socktype = `SOCK_STREAM`,
		int	protocol = `0`
	)

inline

Create and connect socket using address.

In blocking mode this blocks while connecting, and could take a while for the implementation to timeout
In non-blocking mode this returns with err=ENonBlock – use write_wait() to wait/poll

Parameters

err	Set to ENone on success, otherwise set to error code
address	Socket address to connect to, must not be NULL
address_len	Socket address length to connect to, must be positive
socktype	Socket type, usually SOCK_STREAM
protocol	Network protocol, usually 0 for default

Returns: Whether successful, false on error

◆ connect_wait()

bool connect_wait	(	Error &	err,
		ulong	timeout_ms
	)

inline

Wait until socket connection is established and ready to write.

Used with non-blocking I/O, after connection is started
If connection failed this fails with err set to the error code

Parameters

err	Set to error code on failure, ETimeout on timeout
timeout_ms	Wait timeout in milliseconds, 0 for no wait (returns immediately, useful for polling)

Returns: Whether connected, false on error

◆ detach()

Handle detach ( )

inline

Detach and return socket handle.

Returns: File handle

◆ errormsg_out()

static TOut& errormsg_out	(	TOut &	out,
		Error	err
	)

inlinestatic

Write detailed error message with errno to output stream/string.

Must call right after the error, otherwise errno may be overwritten
This includes the system formatted message for errno

Parameters

out	Stream or String to write output to
err	Error code to format message for

Returns: out

◆ getopt()

Error getopt	(	int	level,
		int	optname,
		void *	buf,
		uint &	size
	)

inline

Get socket option value.

This calls getsockopt() on the socket

Parameters

level	Option level, ex: SOL_SOCKET, IPPROTO_IP
optname	Option identifier, depends on level
buf	Buffer to store value
size	Buffer size, updated with value size stored in buffer

Returns: ENone on success, EInval on invalid value or size, EInvalOP on unknown optname, otherwise error code

◆ init()

static const Init& init ( )

inlinestatic

Initialize socket library.

This should be called near the beginning of the process to load the socket library
Implementation is OS specific, used in Windows to load WinSock DLL

◆ isopen()

bool isopen ( ) const

inline

Get whether socket is open.

Returns: Whether socket is open

◆ listen() [1/2]

bool listen	(	Error &	err,
		struct addrinfo *	address_info,
		int	backlog = `SOMAXCONN`,
		bool	all = `true`
	)

inline

Create and bind socket using address info and listen for connections.

Parameters

err	Set to ENone on success, EExist if address/port already used, otherwise set to error code
address_info	Pointer to addrinfo structure to bind to (first in linked list)
backlog	Listener queue backlog size
all	Whether to try all addresses in addrinfo until successful, false to just try the first address

Returns: Whether successful, false on error

◆ listen() [2/2]

bool listen	(	Error &	err,
		struct sockaddr *	address,
		socklen_t	address_len,
		int	backlog = `SOMAXCONN`,
		int	socktype = `SOCK_STREAM`,
		int	protocol = `0`
	)

inline

Create and bind socket to address and listen for connections.

Parameters

err	Set to ENone on success, EExist if address/port already used, otherwise set to error code
address	Socket address to bind to, must not be NULL
address_len	Socket address length to bind to, must be positive
backlog	Listener queue backlog size
socktype	Socket type, usually SOCK_STREAM
protocol	Network protocol, usually 0 for default

Returns: Whether successful, false on error

◆ pos()

ulongl pos ( Error & err )

inline

Not supported with sockets.

Parameters

err	Set to EInval [out]

Returns: Always 0

◆ read() [1/2]

ulong read	(	Error &	err,
		void *	buf,
		ulong	size,
		ulong	timeout_ms = `0`
	)

inlineinherited

Read input data from device.

On success this reads at least 1 byte and may read less than requested size
If not open/readable, returns end-of-file (0)

Parameters

err	Stores ENone on success, error code on error [out]
buf	Buffer to store data read
size	Size to read in bytes
timeout_ms	Read timeout in milliseconds, 0 for none (don't timeout)

Returns: Size actually read in bytes, 0 on end-of-file or error

◆ read() [2/2]

ulong read	(	Error &	err,
		void *	buf,
		ulong	size
	)

inline

◆ read_wait()

bool read_wait	(	Error &	err,
		ulong	timeout_ms
	)

inline

Wait until socket is ready to read.

Socket is ready to read when it's received some data to read
Used with non-blocking I/O, before calling read()

Parameters

err	Set to error code on failure, ETimeout on timeout
timeout_ms	Wait timeout in milliseconds, 0 for indefinite

Returns: Whether ready to read, false on error

◆ readfrom()

ulong readfrom	(	Error &	err,
		void *	buf,
		ulong	size,
		struct sockaddr *	address = `NULL`,
		socklen_t *	address_len = `NULL`,
		int	flags = `0`
	)

inline

Read message from socket device.

This is used with UDP sockets to receive a packet
UDP packet size limit is usually just under 64 KB, depending on the protocol used

Parameters

err	Stores ENone on success, error code on error [out]
buf	Buffer to store data read
size	Buffer size in bytes
address	Pointer to store source socket address, NULL to ignore
address_len	Pointer to address buffer length, updated to actual length used
flags	Low-level flags to use with socket

Returns: Size actually read in bytes, 0 on end-of-file or error

◆ seek()

ulongl seek	(	Error &	err,
		ulongl	,
		Seek
	)

inline

Not supported with sockets.

Parameters

err	Set to EInval [out]

Returns: Always 0

◆ set_nonblock()

Error set_nonblock ( bool enable = true )

inline

Enable/Disable non-blocking I/O.

This updates the nonblock flag, which persists even after socket is closed and created again
If socket is open, this updates non-blocking mode on it too
With non-blocking enabled, connect/read/write operations return error code ENonBlock when they would normally block

Parameters

enable Whether to enable non-blocking mode, false to disable

Returns: ENone for success, otherwise error code

◆ setopt()

Error setopt	(	int	level,
		int	optname,
		const void *	buf,
		uint	size
	)

inline

Set socket option with new value.

This calls setsockopt() on the socket

Parameters

level	Option level, ex: SOL_SOCKET, IPPROTO_IP
optname	Option identifier, depends on level
buf	Buffer with value to set
size	Value size in buffer

Returns: ENone on success, EInval on invalid value or size, EInvalOP on unknown optname, otherwise error code

◆ shutdown()

bool shutdown ( Shutdown how = sINOUT )

inline

Shutdown socket communication.

This is a gracefull way to shutdown input and/or output on socket so the other end is informated
Don't use on error, just close the socket (or let destructor close it)

Parameters

how	Whether to shutdown input, output, or both – see Shutdown enum

Returns: Whether successful, false on error (not connected, invalid, etc)

◆ write() [1/2]

ulong write	(	Error &	err,
		const void *	buf,
		ulong	size,
		ulong	timeout_ms = `0`
	)

inlineinherited

Write output data to device.

On success at least 1 byte is written but may be less than requested size
If not open/writable, returns ENotImpl error

Parameters

err	Stores ENone on success, error code on error [out]
buf	Buffer to write from
size	Size to write in bytes
timeout_ms	Write timeout in milliseconds, 0 for none (don't timeout)

Returns: Size actually written in bytes, 0 on error (check err)

◆ write() [2/2]

ulong write	(	Error &	err,
		const void *	buf,
		ulong	size
	)

inline

◆ write_wait()

bool write_wait	(	Error &	err,
		ulong	timeout_ms
	)

inline

Wait until socket is ready to write.

Socket is ready to write when it's connected and there's room in the write buffer
Normally used with non-blocking I/O

Parameters

err	Set to error code on failure, ETimeout on timeout
timeout_ms	Wait timeout in milliseconds, 0 for indefinite

Returns: Whether ready to write, false on error

◆ writeto()

ulong writeto	(	Error &	err,
		const void *	buf,
		ulong	size,
		const struct sockaddr *	address,
		socklen_t	address_len,
		int	flags = `0`
	)

inline

Write message to device and socket address.

This is used with UDP sockets to send a packet directly to socket address
UDP packet size limit is usually just under 64 KB, depending on the protocol used

Parameters

err	Stores ENone on success, error code on error [out]
buf	Buffer to write from
size	Size to write in bytes, 0 sends an empty packet
address	Socket address to write to, must not be NULL
address_len	Socket address length to write to, must be positive
flags	Low-level flags to use with socket

Returns: Size actually written in bytes (should match size), 0 on error (check err)

Member Data Documentation

◆ autoresume

bool autoresume

Whether to auto-resume I/O operation after signal received [Linux/Unix].

◆ handle

Handle handle

Socket handle/descriptor.

◆ INVALID

const Handle INVALID = -1

static

Invalid handle value (used internally)

◆ nonblock

bool nonblock

Whether non-blocking I/O is enabled.

◆ SOCK_ERROR

const int SOCK_ERROR = -1

static

Socket error value (used internally)

◆ STREAM_SEEKABLE

const bool STREAM_SEEKABLE = false

static

Socket streams are not seekable with Stream.

◆ TIMEOUT_DEFAULT

const ulong TIMEOUT_DEFAULT = 30000

static

Default timeout used in milliseconds.

◆ timeout_ms

ulong timeout_ms

Current timeout in milliseconds, 0 for indefinite.

The documentation for this struct was generated from the following file:

evo/impl/sysio_sock.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Member Typedef Documentation

◆ ExceptionInT

◆ ExceptionOutT

◆ Handle

◆ OptNum

Member Enumeration Documentation

◆ Shutdown

Constructor & Destructor Documentation

◆ IoSocket() [1/2]

◆ IoSocket() [2/2]

◆ ~IoSocket()

Member Function Documentation

◆ accept()

◆ accept_nonblock()

◆ attach()

◆ bind()

◆ cast()

◆ close()

◆ connect() [1/2]

◆ connect() [2/2]

◆ connect_wait()

◆ detach()

◆ errormsg_out()

◆ getopt()

◆ init()

◆ isopen()

◆ listen() [1/2]

◆ listen() [2/2]

◆ pos()

◆ read() [1/2]

◆ read() [2/2]

◆ read_wait()

◆ readfrom()

◆ seek()

◆ set_nonblock()

◆ setopt()

◆ shutdown()

◆ write() [1/2]

◆ write() [2/2]

◆ write_wait()

◆ writeto()

Member Data Documentation

◆ autoresume

◆ handle

◆ INVALID

◆ nonblock

◆ SOCK_ERROR

◆ STREAM_SEEKABLE

◆ TIMEOUT_DEFAULT

◆ timeout_ms