A generic socket class. More...

#include <yateclass.h>

Inheritance diagram for Socket:

Public Types
enum	TOS { Normal = 0, LowDelay = IPTOS_LOWDELAY, MaxThroughput = IPTOS_THROUGHPUT, MaxReliability = IPTOS_RELIABILITY, MinCost = IPTOS_MINCOST }

enum	DSCP { DefaultPHB = 0x00, CS0 = 0x00, CS1 = 0x20, CS2 = 0x40, CS3 = 0x60, CS4 = 0x80, CS5 = 0xa0, CS6 = 0xc0, CS7 = 0xe0, AF11 = 0x28, AF12 = 0x30, AF13 = 0x38, AF21 = 0x48, AF22 = 0x50, AF23 = 0x58, AF31 = 0x68, AF32 = 0x70, AF33 = 0x78, AF41 = 0x88, AF42 = 0x90, AF43 = 0x98, ExpeditedFwd = 0xb8, VoiceAdmit = 0xb0 }

Public Types inherited from Stream
enum	SeekPos { SeekBegin, SeekEnd, SeekCurrent }

Public Member Functions
	Socket ()

	Socket (SOCKET handle)

	Socket (int domain, int type, int protocol=0)

virtual	~Socket ()

virtual bool	create (int domain, int type, int protocol=0)

virtual bool	terminate ()

void	attach (SOCKET handle)

SOCKET	detach ()

SOCKET	handle () const

virtual bool	canRetry () const

virtual bool	inProgress () const

virtual bool	valid () const

virtual bool	setOption (int level, int name, const void *value=0, socklen_t length=0)

bool	setIpv6OnlyOption (bool on)

virtual bool	getOption (int level, int name, void buffer, socklen_t length)

virtual bool	setParams (const NamedList &params)

virtual bool	getParams (const String &params, NamedList &result)

virtual bool	setTOS (int tos)

bool	setTOS (const char *tos, int defTos=Normal)

virtual int	getTOS ()

virtual bool	setBlocking (bool block=true)

virtual bool	setReuse (bool reuse=true, bool exclusive=false)

virtual bool	setLinger (int seconds=-1)

virtual bool	bind (struct sockaddr *addr, socklen_t addrlen)

bool	bind (const SocketAddr &addr)

virtual bool	listen (unsigned int backlog=0)

virtual Socket *	accept (struct sockaddr addr=0, socklen_t addrlen=0)

Socket *	accept (SocketAddr &addr)

SOCKET	acceptHandle (struct sockaddr addr=0, socklen_t addrlen=0)

bool	updateError ()

virtual bool	canSelect () const

virtual bool	connect (struct sockaddr *addr, socklen_t addrlen)

bool	connect (const SocketAddr &addr)

virtual bool	connectAsync (struct sockaddr addr, socklen_t addrlen, unsigned int toutUs, bool timeout=0)

bool	connectAsync (const SocketAddr &addr, unsigned int toutUs, bool *timeout=0)

virtual bool	shutdown (bool stopReads, bool stopWrites)

virtual bool	getSockName (struct sockaddr addr, socklen_t addrlen)

bool	getSockName (SocketAddr &addr)

virtual bool	getPeerName (struct sockaddr addr, socklen_t addrlen)

bool	getPeerName (SocketAddr &addr)

virtual int	sendTo (const void buffer, int length, const struct sockaddr addr, socklen_t adrlen, int flags=0)

int	sendTo (const void *buffer, int length, const SocketAddr &addr, int flags=0)

virtual int	send (const void *buffer, int length, int flags=0)

virtual int	writeData (const void *buffer, int length)

virtual int	recvFrom (void buffer, int length, struct sockaddr addr=0, socklen_t *adrlen=0, int flags=0)

int	recvFrom (void *buffer, int length, SocketAddr &addr, int flags=0)

virtual int	recv (void *buffer, int length, int flags=0)

virtual int	readData (void *buffer, int length)

virtual bool	select (bool readok, bool writeok, bool except, struct timeval timeout=0)

bool	select (bool readok, bool writeok, bool *except, int64_t timeout)

bool	installFilter (SocketFilter *filter)

void	removeFilter (SocketFilter *filter, bool delobj=false)

void	clearFilters ()

virtual void	timerTick (const Time &when)

Public Member Functions inherited from Stream
virtual	~Stream ()

int	error () const

int	writeData (const char *str)

int	writeData (const String &str)

int	writeData (const DataBlock &buf)

virtual int64_t	length ()

virtual int64_t	seek (SeekPos pos, int64_t offset=0)

int64_t	seek (int64_t offset)

Static Public Member Functions
static SOCKET	invalidHandle ()

static int	socketError ()

static const TokenDict *	tosValues ()

static bool	efficientSelect ()

static bool	canSelect (SOCKET handle)

static bool	createPair (Socket &sock1, Socket &sock2, int domain=AF_UNIX)

Static Public Member Functions inherited from Stream
static bool	allocPipe (Stream &reader, Stream &writer)

static bool	allocPair (Stream &str1, Stream &str2)

static bool	supportsPipes ()

static bool	supportsPairs ()

Protected Member Functions
void	copyError ()

bool	checkError (int retcode, bool strict=false)

bool	applyFilters (void buffer, int length, int flags, const struct sockaddr addr=0, socklen_t adrlen=0)

Protected Member Functions inherited from Stream
	Stream ()

void	clearError ()

Protected Attributes
SOCKET	m_handle

ObjList	m_filters

Protected Attributes inherited from Stream
int	m_error

Detailed Description

A generic socket class.

This class encapsulates a system dependent socket in a system independent abstraction

Member Enumeration Documentation

enum DSCP

DiffServ bits

enum TOS

Types of service

Constructor & Destructor Documentation

Socket ( )

Default constructor, creates an invalid socket

Socket ( SOCKET handle )

explicit

Constructor from an existing handle

Parameters

handle Operating system handle to an existing socket

Socket	(	int	domain,
		int	type,
		int	protocol = `0`
	)

Constructor that also creates the socket handle

Parameters

domain	Communication domain for the socket (protocol family)
type	Type specification of the socket
protocol	Specific protocol for the domain, 0 to use default

virtual ~Socket ( )

virtual

Destructor - closes the handle if still open

Member Function Documentation

virtual Socket* accept	(	struct sockaddr *	addr = `0`,
		socklen_t *	addrlen = `0`
	)

virtual

Create a new socket for an incoming connection attempt on a listening socket

Parameters

addr	Address to fill in with the address of the incoming connection
addrlen	Length of the address structure on input, length of address data on return

Returns: Open socket to the new connection or NULL on failure

Socket* accept ( SocketAddr & addr )

Create a new socket for an incoming connection attempt on a listening socket

Parameters

addr	Address to fill in with the address of the incoming connection

Returns: Open socket to the new connection or NULL on failure

SOCKET acceptHandle	(	struct sockaddr *	addr = `0`,
		socklen_t *	addrlen = `0`
	)

Create a new socket for an incoming connection attempt on a listening socket

Parameters

addr	Address to fill in with the address of the incoming connection
addrlen	Length of the address structure on input, length of address data on return

Returns: Operating system handle to the new connection or invalidHandle() on failure

bool applyFilters	(	void *	buffer,
		int	length,
		int	flags,
		const struct sockaddr *	addr = `0`,
		socklen_t	adrlen = `0`
	)

protected

Apply installed filters to a received block of data

Parameters

buffer	Buffer for received data
length	Length of the data in buffer
flags	Operating system specific bit flags of the operation
addr	Address of the incoming data, may be NULL
adrlen	Length of the valid data in address structure

Returns: True if one of the filters claimed the data

void attach ( SOCKET handle )

Attach an existing handle to the socket, closes any existing first

Parameters

handle Operating system handle to an existing socket

virtual bool bind	(	struct sockaddr *	addr,
		socklen_t	addrlen
	)

virtual

Associates the socket with a local address

Parameters

addr	Address to assign to this socket
addrlen	Length of the address structure

Returns: True if operation was successfull, false if an error occured

Referenced by Socket::bind().

bool bind ( const SocketAddr & addr )

inline

Associates the socket with a local address

Parameters

addr	Address to assign to this socket

Returns: True if operation was successfull, false if an error occured

References SocketAddr::address(), Socket::bind(), and SocketAddr::length().

virtual bool canRetry ( ) const

virtual

Check if the last error code indicates a retryable condition

Returns: True if error was temporary and operation should be retried

Reimplemented from Stream.

static bool canSelect ( SOCKET handle )

static

Check if a socket handle can be used in select

Parameters

handle The socket handle to check

Returns: True if the socket handle can be safely used in select

virtual bool canSelect ( ) const

virtual

Check if this socket object can be used in a select

Returns: True if this socket can be safely used in select

bool checkError	(	int	retcode,
		bool	strict = `false`
	)

protected

Copy the last error code from the operating system if an error occured, clear if not

Parameters

retcode	Operation return code to check, 0 for success
strict	True to consider errors only return codes of socketError()

Returns: True if operation succeeded (retcode == 0), false otherwise

void clearFilters ( )

Removes and destroys all packet filters

virtual bool connect	(	struct sockaddr *	addr,
		socklen_t	addrlen
	)

virtual

Connects the socket to a remote address

Parameters

addr	Address to connect to
addrlen	Length of the address structure

Returns: True if operation was successfull, false if an error occured

Referenced by Socket::connect().

bool connect ( const SocketAddr & addr )

inline

Connects the socket to a remote address

Parameters

addr	Socket address to connect to

Returns: True if operation was successfull, false if an error occured

References SocketAddr::address(), Socket::connect(), and SocketAddr::length().

virtual bool connectAsync	(	struct sockaddr *	addr,
		socklen_t	addrlen,
		unsigned int	toutUs,
		bool *	timeout = `0`
	)

virtual

Asynchronously connects the socket to a remote address. The socket must be selectable and in non-blocking operation mode

Parameters

addr	Address to connect to
addrlen	Length of the address structure
toutUs	Timeout interval in microseconds
timeout	Optional boolean flag to signal timeout

Returns: True on success

Referenced by Socket::connectAsync().

bool connectAsync	(	const SocketAddr &	addr,
		unsigned int	toutUs,
		bool *	timeout = `0`
	)

inline

Asynchronously connects the socket to a remote address. The socket must be selectable and in non-blocking operation mode

Parameters

addr	Socket address to connect to
toutUs	Timeout interval in microseconds
timeout	Optional boolean flag to signal timeout

Returns: True on success

References SocketAddr::address(), Socket::connectAsync(), and SocketAddr::length().

void copyError ( )

protected

Copy the last error code from the operating system

virtual bool create	(	int	domain,
		int	type,
		int	protocol = `0`
	)

virtual

Creates a new socket handle,

Parameters

domain	Communication domain for the socket (protocol family)
type	Type specification of the socket
protocol	Specific protocol for the domain, 0 to use default

Returns: True if socket was created, false if an error occured

static bool createPair	(	Socket &	sock1,
		Socket &	sock2,
		int	domain = `AF_UNIX`
	)

static

Create a pair of bidirectionally connected sockets

Parameters

sock1	Reference to first Socket to be paired
sock2	Reference to second Socket to be paired
domain	Communication domain for the sockets (protocol family)

Returns: True is the stream pair was created successfully

SOCKET detach ( )

Detaches the object from the socket handle

Returns: The handle previously owned by this object

static bool efficientSelect ( )

static

Check if select() is efficient on this platform and worth using frequently

Returns: True if select() is efficiently implemented

virtual bool getOption	(	int	level,
		int	name,
		void *	buffer,
		socklen_t *	length
	)

virtual

Get socket options

Parameters

level	Level of the option to set
name	Socket option for which the value is to be set
buffer	Pointer to a buffer to return the value for the requested option
length	Pointer to size of the supplied buffer, will be filled on return

Returns: True if operation was successfull, false if an error occured

virtual bool getParams	(	const String &	params,
		NamedList &	result
	)

inlinevirtual

Get specific socket parameters.

Parameters

params	Coma separated list of parameters to obtain
result	List of parameters to fill

Returns: True if operation was successful, false if an error occurred

virtual bool getPeerName	(	struct sockaddr *	addr,
		socklen_t *	addrlen
	)

virtual

Retrieve the address of the remote socket of a connection

Parameters

addr	Address to fill in with the address of the remote socket
addrlen	Length of the address structure on input, length of address data on return

Returns: True if operation was successfull, false if an error occured

bool getPeerName ( SocketAddr & addr )

Retrieve the address of the remote socket of a connection

Parameters

addr	Address to fill in with the address of the remote socket

Returns: True if operation was successfull, false if an error occured

virtual bool getSockName	(	struct sockaddr *	addr,
		socklen_t *	addrlen
	)

virtual

Retrieve the address of the local socket of a connection

Parameters

addr	Address to fill in with the address of the local socket
addrlen	Length of the address structure on input, length of address data on return

Returns: True if operation was successfull, false if an error occured

bool getSockName ( SocketAddr & addr )

Retrieve the address of the local socket of a connection

Parameters

addr	Address to fill in with the address of the local socket

Returns: True if operation was successfull, false if an error occured

virtual int getTOS ( )

virtual

Retrieve the TOS / DSCP on the IP level of this socket

Returns: TOS or DiffServ value, Normal if not supported or an error occured

SOCKET handle ( ) const

inline

Get the operating system handle to the socket

Returns: Socket handle

virtual bool inProgress ( ) const

virtual

Check if the last error code indicates a non blocking operation in progress

Returns: True if a non blocking operation is in progress

Reimplemented from Stream.

bool installFilter ( SocketFilter * filter )

Install a new packet filter in the socket

Parameters

filter Pointer to the packet filter to install

Returns: True if the filter was installed

static SOCKET invalidHandle ( )

static

Get the operating system specific handle value for an invalid socket

Returns: Handle value for an invalid socket

virtual bool listen ( unsigned int backlog = 0 )

virtual

Start listening for incoming connections on the socket

Parameters

backlog Maximum length of the queue of pending connections, 0 for system maximum

Returns: True if operation was successfull, false if an error occured

virtual int readData	(	void *	buffer,
		int	length
	)

virtual

Receive data from a connected stream socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer

Returns: Number of bytes transferred, socketError() if an error occurred

Implements Stream.

virtual int recv	(	void *	buffer,
		int	length,
		int	flags = `0`
	)

virtual

Receive a message from a connected socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer
flags	Operating system specific bit flags that change the behaviour

Returns: Number of bytes transferred, socketError() if an error occurred

virtual int recvFrom	(	void *	buffer,
		int	length,
		struct sockaddr *	addr = `0`,
		socklen_t *	adrlen = `0`,
		int	flags = `0`
	)

virtual

Receive a message from a connected or unconnected socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer
addr	Address to fill in with the address of the incoming data
adrlen	Length of the address structure on input, length of address data on return
flags	Operating system specific bit flags that change the behaviour

Returns: Number of bytes transferred, socketError() if an error occurred

int recvFrom	(	void *	buffer,
		int	length,
		SocketAddr &	addr,
		int	flags = `0`
	)

Receive a message from a connected or unconnected socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer
addr	Address to fill in with the address of the incoming data
flags	Operating system specific bit flags that change the behaviour

Returns: Number of bytes transferred, socketError() if an error occurred

void removeFilter	(	SocketFilter *	filter,
		bool	delobj = `false`
	)

Removes a packet filter and optionally destroys it

Parameters

filter	Pointer to the packet filter to remove from socket
delobj	Set to true to also delete the filter

virtual bool select	(	bool *	readok,
		bool *	writeok,
		bool *	except,
		struct timeval *	timeout = `0`
	)

virtual

Determines the availability to perform synchronous I/O of the socket

Parameters

readok	Address of a boolean variable to fill with readability status
writeok	Address of a boolean variable to fill with writeability status
except	Address of a boolean variable to fill with exceptions status
timeout	Maximum time until the method returns, NULL for blocking

Returns: True if operation was successfull, false if an error occured

bool select	(	bool *	readok,
		bool *	writeok,
		bool *	except,
		int64_t	timeout
	)

Determines the availability to perform synchronous I/O of the socket

Parameters

readok	Address of a boolean variable to fill with readability status
writeok	Address of a boolean variable to fill with writeability status
except	Address of a boolean variable to fill with exceptions status
timeout	Maximum time until the method returns, -1 for blocking

Returns: True if operation was successfull, false if an error occured

virtual int send	(	const void *	buffer,
		int	length,
		int	flags = `0`
	)

virtual

Send a message over a connected socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer
flags	Operating system specific bit flags that change the behaviour

Returns: Number of bytes transferred, socketError() if an error occurred

virtual int sendTo	(	const void *	buffer,
		int	length,
		const struct sockaddr *	addr,
		socklen_t	adrlen,
		int	flags = `0`
	)

virtual

Send a message over a connected or unconnected socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer
addr	Address to send the message to, if NULL will behave like send()
adrlen	Length of the address structure
flags	Operating system specific bit flags that change the behaviour

Returns: Number of bytes transferred, socketError() if an error occurred

Referenced by Socket::sendTo().

int sendTo	(	const void *	buffer,
		int	length,
		const SocketAddr &	addr,
		int	flags = `0`
	)

inline

Send a message over a connected or unconnected socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer
addr	Address to send the message to
flags	Operating system specific bit flags that change the behaviour

Returns: Number of bytes transferred, socketError() if an error occurred

References SocketAddr::address(), SocketAddr::length(), and Socket::sendTo().

virtual bool setBlocking ( bool block = true )

virtual

Set the blocking or non-blocking operation mode of the socket

Parameters

block True if I/O operations should block, false for non-blocking

Returns: True if operation was successfull, false if an error occured

Reimplemented from Stream.

bool setIpv6OnlyOption ( bool on )

inline

Set or reset socket IPv6 only option. This option will tell to an IPv6 socket to accept only IPv6 packets. IPv4 packets will be accepted if disabled. This method will fail for non PF_INET6 sockets

Parameters

on	True to set, false to reset it

Returns: True if operation was successfull, false if an error occured

References Socket::setOption().

virtual bool setLinger ( int seconds = -1 )

virtual

Set the way closing a socket is handled

Parameters

seconds How much to block waiting for socket to close, negative to no wait (close in background), zero to reset connection

Returns: True if operation was successfull, false if an error occured

virtual bool setOption	(	int	level,
		int	name,
		const void *	value = `0`,
		socklen_t	length = `0`
	)

virtual

Set socket options

Parameters

level	Level of the option to set
name	Socket option for which the value is to be set
value	Pointer to a buffer holding the value for the requested option
length	Size of the supplied buffer

Returns: True if operation was successfull, false if an error occured

Referenced by Socket::setIpv6OnlyOption().

virtual bool setParams ( const NamedList & params )

inlinevirtual

Set specific socket parameters.

Parameters

params List of parameters

virtual bool setReuse	(	bool	reuse = `true`,
		bool	exclusive = `false`
	)

virtual

Set the local address+port reuse flag of the socket. This method should be called before bind() or it will have no effect.

Parameters

reuse	True if other sockets may listen on same address+port
exclusive	Grant exclusive access to the address

Returns: True if operation was successfull, false if an error occured

virtual bool setTOS ( int tos )

virtual

Set the Type of Service or Differentiated Services Code Point on the IP level of this socket

Parameters

tos	New TOS or DiffServ bits

Returns: True if operation was successfull, false if an error occured

Referenced by Socket::setTOS().

bool setTOS	(	const char *	tos,
		int	defTos = `Normal`
	)

inline

Set the Type of Service or Differentiated Services Code Point on the IP level of this socket

Parameters

tos	Keyword describing new TOS or DSCP value
defTos	Default TOS or DiffServ value to set if the keyword is not recognized

Returns: True if operation was successfull, false if an error occured

References TelEngine::lookup(), Socket::setTOS(), and Socket::tosValues().

virtual bool shutdown	(	bool	stopReads,
		bool	stopWrites
	)

virtual

Shut down one or both directions of a full-duplex socket.

Parameters

stopReads	Request to shut down the read side of the socket
stopWrites	Request to shut down the write side of the socket

Returns: True if operation was successfull, false if an error occured

static int socketError ( )

static

Get the operating system specific return value of a failed operation

Returns: Return value of a failed socket operation

virtual bool terminate ( )

virtual

Closes the socket handle, terminates the connection

Returns: True if socket was (already) closed, false if an error occured

Implements Stream.

virtual void timerTick ( const Time & when )

virtual

Run whatever actions required on idle thread runs. The default implementation calls SocketFilter::timerTick() for all installed filters.

Parameters

when	Time when the idle run started

static const TokenDict* tosValues ( )

static

Retrieve the keyword lookup table for TOS / DSCP values

Returns: Pointer to keyword dictionary for TOS and DSCP

Referenced by Socket::setTOS().

bool updateError ( )

Update socket error from socket options. This method should be called when select() indicates a non blocking operation completed. Note: if false is returned, the socket error is the reason of getOption() failure

Returns: Return true on success

virtual bool valid ( ) const

virtual

Check if this socket is valid

Returns: True if the handle is valid, false if it's invalid

Implements Stream.

virtual int writeData	(	const void *	buffer,
		int	length
	)

virtual

Write data to a connected stream socket

Parameters

buffer	Buffer for data transfer
length	Length of the buffer

Returns: Number of bytes transferred, socketError() if an error occurred

Implements Stream.

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

yateclass.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation