# Socket Class Reference

A generic socket class. More...

`#include <yateclass.h>`

Inheritance diagram for Socket:

List of all members.

## 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)
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 | 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

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

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.

void attach | ( | SOCKET | handle | ) |

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

Parameters:

  | handle | Operating system handle to an existing socket

SOCKET detach | ( |  | ) |

Detaches the object from the socket handle

Returns:
  The handle previously owned by this object

SOCKET handle | ( |  | ) | const`[inline]`

Get the operating system handle to the socket

Returns:
  Socket handle

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.

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.

static SOCKET invalidHandle | ( |  | ) | `[static]`

Get the operating system specific handle value for an invalid socket

Returns:
  Handle value for an invalid socket

static int socketError | ( |  | ) | `[static]`

Get the operating system specific return value of a failed operation

Returns:
  Return value of a failed socket operation

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 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 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

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 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 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 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

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

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* 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* 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

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

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

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

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

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

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 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 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

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

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

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

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.

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

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 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

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.

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

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 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

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

void clearFilters | ( |  | ) |

Removes and destroys all packet filters

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 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

void copyError | ( |  | ) | `[protected]`

Copy the last error code from the operating system

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

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

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

- yateclass.h