Yate: Socket Class Reference

Yate

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Socket Class Reference

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