class Socket

# class Socket | A generic socket class. More...
Full name | `TelEngine::Socket`
Definition | `#include <yateclass.h>`
Inherits | TelEngine::Stream [public ]
Inherited by | SctpSocket
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

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

- Socket ()
- explicit 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 ()
- inline 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)
- inline 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)
- inline bool setTOS (const char* tos, int defTos = Normal)
- 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)
- inline 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)
- inline bool connect (const SocketAddr& addr)
- virtual bool connectAsync (struct sockaddr* addr, socklen_t addrlen, unsigned int toutUs, bool* timeout = 0)
- inline 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)
- inline 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 Static Methods

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

#### Protected Methods

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

- SOCKET m_handle
- ObjList m_filters

## Detailed Description

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

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

Types of service

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, } | ### DSCP

DiffServ bits

Socket () | ### Socket

Default constructor, creates an invalid socket

explicit Socket (SOCKET handle) | ### Socket

Constructor from an existing handle

Parameters:

handle | Operating system handle to an existing socket

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

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

~Socket () | ### ~Socket

[virtual]

Destructor - closes the handle if still open

bool create (int domain, int type, int protocol = 0) | ### create

[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

bool terminate () | ### terminate

[virtual]

Closes the socket handle, terminates the connection

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

Reimplemented from Stream.

void attach (SOCKET handle) | ### attach

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

Parameters:

handle | Operating system handle to an existing socket

SOCKET detach () | ### detach

Detaches the object from the socket handle

Returns: The handle previously owned by this object

inline SOCKET handle () | ### handle

[const]

Get the operating system handle to the socket

Returns: Socket handle

bool canRetry () | ### 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 inProgress () | ### 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 valid () | ### valid

[const virtual]

Check if this socket is valid

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

Reimplemented from Stream.

SOCKET invalidHandle () | ### invalidHandle

[static]

Get the operating system specific handle value for an invalid socket

Returns: Handle value for an invalid socket

int socketError () | ### socketError

[static]

Get the operating system specific return value of a failed operation

Returns: Return value of a failed socket operation

const TokenDict* tosValues () | ### tosValues

[static]

Retrieve the keyword lookup table for TOS / DSCP values

Returns: Pointer to keyword dictionary for TOS and DSCP

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

[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

inline bool setIpv6OnlyOption (bool on) | ### setIpv6OnlyOption

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

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

[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

bool setParams (const NamedList& params) | ### setParams

[virtual]

Set specific socket parameters.

Parameters:

params | List of parameters

bool getParams (const String& params, NamedList& result) | ### getParams

[virtual]

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

bool setTOS (int tos) | ### setTOS

[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

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

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

bool setBlocking (bool block = true) | ### setBlocking

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

[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

bool setLinger (int seconds = -1) | ### setLinger

[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

bool bind (struct sockaddr* addr, socklen_t addrlen) | ### bind

[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

inline bool bind (const SocketAddr& addr) | ### bind

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

[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

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

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

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

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

bool efficientSelect () | ### efficientSelect

[static]

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

Returns: True if select() is efficiently implemented

bool canSelect (SOCKET handle) | ### canSelect

[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 canSelect () | ### 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 connect (struct sockaddr* addr, socklen_t addrlen) | ### connect

[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

inline bool connect (const SocketAddr& addr) | ### connect

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 connectAsync (struct sockaddr* addr, socklen_t addrlen, unsigned int toutUs, bool* timeout = 0) | ### connectAsync

[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

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

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

bool shutdown (bool stopReads, bool stopWrites) | ### shutdown

[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

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

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

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

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

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

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

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

[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

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

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

[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

int writeData (const void* buffer, int length) | ### writeData

[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

Reimplemented from Stream.

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

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

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

[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

int readData (void* buffer, int length) | ### readData

[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

Reimplemented from Stream.

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

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

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

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

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

Removes and destroys all packet filters

void timerTick (const Time& when) | ### timerTick

[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

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

[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 () | ### copyError

[protected]

Copy the last error code from the operating system

bool checkError (int retcode, bool strict = false) | ### checkError

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

[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

SOCKET m_handle | ### m_handle

[protected]

ObjList m_filters | ### m_filters

[protected]

Generated by: paulc on bussard on Fri May 8 12:37:22 2015, using kdoc 2.0a54.