Socket Class Reference

A generic socket class. More...

#include <yateclass.h>

Inheritance diagram for Socket:

Public Types
enum	TOS { LowDelay = IPTOS_LOWDELAY, MaxThroughput = IPTOS_THROUGHPUT, MaxReliability = IPTOS_RELIABILITY, MinCost = IPTOS_MINCOST }
Public Member Functions
	Socket ()
	Socket (SOCKET handle)
	Socket (int domain, int type, int protocol=0)
virtual	~Socket ()
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	valid () const
bool	setOption (int level, int name, const void *value=0, socklen_t length=0)
bool	getOption (int level, int name, void buffer, socklen_t length)
bool	setTOS (int tos)
virtual bool	setBlocking (bool block=true)
bool	setReuse (bool reuse=true, bool exclusive=false)
bool	setLinger (int seconds=-1)
bool	bind (struct sockaddr *addr, socklen_t addrlen)
bool	bind (const SocketAddr &addr)
bool	listen (unsigned int backlog=0)
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	canSelect () const
Socket *	peelOff (unsigned int assoc)
SOCKET	peelOffHandle (unsigned int assoc)
bool	connect (struct sockaddr *addr, socklen_t addrlen)
bool	connect (const SocketAddr &addr)
bool	shutdown (bool stopReads, bool stopWrites)
bool	getSockName (struct sockaddr addr, socklen_t addrlen)
bool	getSockName (SocketAddr &addr)
bool	getPeerName (struct sockaddr addr, socklen_t addrlen)
bool	getPeerName (SocketAddr &addr)
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)
int	send (const void *buffer, int length, int flags=0)
virtual int	writeData (const void *buffer, int length)
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)
int	recv (void *buffer, int length, int flags=0)
virtual int	readData (void *buffer, int length)
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)
Static Public Member Functions
static SOCKET	invalidHandle ()
static int	socketError ()
static bool	canSelect (SOCKET handle)
static bool	createPair (Socket &sock1, Socket &sock2, int domain=AF_UNIX)
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 Attributes
SOCKET	m_handle
ObjList	m_filters

Detailed Description

A generic socket class.

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

Member Enumeration Documentation

enum TOS

Types of service

Constructor & Destructor Documentation

Socket ( )

Default constructor, creates an invalid socket

Socket ( SOCKET handle )

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

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* accept	(	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:: 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

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().

Referenced by Socket::bind().

bool bind	(	struct sockaddr *	addr,
		socklen_t	addrlen
	)

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

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.

bool canSelect ( ) const [inline]

Check if this socket object can be used in a select

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

References Socket::canSelect().

Referenced by Socket::canSelect().

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

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

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().

Referenced by Socket::connect().

bool connect	(	struct sockaddr *	addr,
		socklen_t	addrlen
	)

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

void copyError ( ) [protected]

Copy the last error code from the operating system

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

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

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

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

bool getPeerName ( SocketAddr & addr )

Retrive 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

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

Retrive 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 getSockName ( SocketAddr & addr )

Retrive 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

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

Retrive 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

SOCKET handle ( ) const [inline]

Get the operating system handle to the socket

Returns:: Socket handle

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

bool listen ( unsigned int backlog = 0 )

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

Socket* peelOff ( unsigned int assoc )

Create a new socket by peeling off an association from a SCTP socket

Parameters:

assoc

Identifier of the association to peel off

Returns:: Open socket to the association or NULL on failure

SOCKET peelOffHandle ( unsigned int assoc )

Create a new socket by peeling off an association from a SCTP socket

Parameters:

assoc

Identifier of the association to peel off

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

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.

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

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

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

int recvFrom	(	void *	buffer,
		int	length,
		struct sockaddr *	addr = `0`,
		socklen_t *	adrlen = `0`,
		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
	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

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

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

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

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

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

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

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().

Referenced by Socket::sendTo().

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

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

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 setLinger ( int seconds = -1 )

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

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

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

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

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

bool setTOS ( int tos )

Set the Type of Service on the IP level of this socket

Parameters:

tos

New TOS bits to set

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

bool shutdown	(	bool	stopReads,
		bool	stopWrites
	)

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

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

Socket Class Reference

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