# 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 { LowDelay = IPTOS_LOWDELAY, MaxThroughput = IPTOS_THROUGHPUT, MaxReliability = IPTOS_RELIABILITY, MinCost = IPTOS_MINCOST, }

#### 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)
- 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)
- 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 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 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 { LowDelay = IPTOS_LOWDELAY, MaxThroughput = IPTOS_THROUGHPUT, MaxReliability = IPTOS_RELIABILITY, MinCost = IPTOS_MINCOST, }

### TOS

Types of service

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

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

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 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 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 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 Dec 21 16:28:34 2012, using kdoc 2.0a54.