# Poco::Net

# class Socket

Library: Net
Package: Sockets
Header: Poco/Net/Socket.h

## Description

Socket is the common base class for StreamSocket, ServerSocket, DatagramSocket and other socket classes.

It provides operations common to all socket types.

## Inheritance

Known Derived Classes: DatagramSocket, DialogSocket, ICMPSocket, MulticastSocket, RawSocket, ServerSocket, StreamSocket, WebSocket, SecureServerSocket, SecureStreamSocket

## Member Summary

Member Functions: address, available, close, destroyBufVec, error, fromFileDescriptor, getBlocking, getError, getKeepAlive, getLinger, getNoDelay, getOOBInline, getOption, getReceiveBufferSize, getReceiveTimeout, getReuseAddress, getReusePort, getSendBufferSize, getSendTimeout, impl, init, isDatagram, isNull, isRaw, isStream, lastError, lastErrorDesc, makeBufVec, makeBuffer, operator !=, operator <, operator <=, operator =, operator ==, operator >, operator >=, peerAddress, poll, secure, select, setBlocking, setKeepAlive, setLinger, setNoDelay, setOOBInline, setOption, setReceiveBufferSize, setReceiveTimeout, setReuseAddress, setReusePort, setSendBufferSize, setSendTimeout, sockfd, supportsIPv4, supportsIPv6, type

## Types Aliases

### BufVec

using BufVec = SocketBufVec;

### SocketList

using SocketList = std::vector < Socket >;

### Type

using Type = SocketImpl::Type;

## Enumerations

### SelectMode

The mode argument to poll() and select().

SELECT_READ = 1

SELECT_WRITE = 2

SELECT_ERROR = 4

## Constructors

### Socket

Socket();

Creates an uninitialized socket.

### Socket

Socket(
const Socket & socket
);

Copy constructor.

Attaches the SocketImpl from the other socket and increments the reference count of the SocketImpl.

### Socket

Socket(
SocketImpl * pImpl
);

Creates the Socket and attaches the given SocketImpl. The socket takes ownership of the SocketImpl.

## Destructor

### ~Socket

virtual ~Socket();

Destroys the Socket and releases the SocketImpl.

## Member Functions

### address

SocketAddress address() const;

Returns the IP address and port number of the socket.

### available

int available() const;

Returns the number of bytes available that can be read without causing the socket to block.

### close

void close();

Closes the socket.

### destroyBufVec

static void destroyBufVec(
SocketBufVec & buf
);

Releases the memory pointed to by vector members and shrinks the vector to size 0. The vector must be created by makeBufVec(size_t, size_t).

### error

static void error();

Throws an appropriate exception for the last error.

### fromFileDescriptor

static Socket fromFileDescriptor(
int fd
);

### getBlocking

bool getBlocking() const;

Returns the blocking mode of the socket. This method will only work if the blocking modes of the socket are changed via the setBlocking method!

### getError

int getError() const;

Returns the socket error.

### getKeepAlive

bool getKeepAlive() const;

Returns the value of the SO_KEEPALIVE socket option.

### getLinger

void getLinger(
bool & on,
int & seconds
) const;

Returns the value of the SO_LINGER socket option.

### getNoDelay

bool getNoDelay() const;

Returns the value of the TCP_NODELAY socket option.

### getOOBInline

bool getOOBInline() const;

Returns the value of the SO_OOBINLINE socket option.

### getOption

void getOption(
int level,
int option,
int & value
) const;

Returns the value of the socket option specified by level and option.

### getOption

void getOption(
int level,
int option,
unsigned & value
) const;

Returns the value of the socket option specified by level and option.

### getOption

void getOption(
int level,
int option,
unsigned char & value
) const;

Returns the value of the socket option specified by level and option.

### getOption

void getOption(
int level,
int option,
Poco::Timespan & value
) const;

Returns the value of the socket option specified by level and option.

### getOption

void getOption(
int level,
int option,
IPAddress & value
) const;

Returns the value of the socket option specified by level and option.

### getReceiveBufferSize

int getReceiveBufferSize() const;

Returns the size of the receive buffer.

The returned value may be different than the value previously set with setReceiveBufferSize(), as the system is free to adjust the value.

### getReceiveTimeout

Poco::Timespan getReceiveTimeout() const;

Returns the receive timeout for the socket.

The returned timeout may be different than the timeout previously set with getReceiveTimeout(), as the system is free to adjust the value.

### getReuseAddress

bool getReuseAddress() const;

Returns the value of the SO_REUSEADDR socket option.

### getReusePort

bool getReusePort() const;

Returns the value of the SO_REUSEPORT socket option.

Returns false if the socket implementation does not support SO_REUSEPORT.

### getSendBufferSize

int getSendBufferSize() const;

Returns the size of the send buffer.

The returned value may be different than the value previously set with setSendBufferSize(), as the system is free to adjust the value.

### getSendTimeout

Poco::Timespan getSendTimeout() const;

Returns the send timeout for the socket.

The returned timeout may be different than the timeout previously set with setSendTimeout(), as the system is free to adjust the value.

### impl

SocketImpl * impl() const;

Returns the SocketImpl for this socket.

### init

void init(
int af
);

Creates the underlying system socket for the given address family.

Normally, this method should not be called directly, as socket creation will be handled automatically. There are a few situations where calling this method after creation of the Socket object makes sense. One example is setting a socket option before calling bind() on a ServerSocket.

### isDatagram

bool isDatagram() const;

Returns true if socket is a datagram socket, false otherwise.

### isNull

bool isNull() const;

Returns true if pointer to implementation is null.

### isRaw

bool isRaw() const;

Returns true if socket is a raw socket, false otherwise.

### isStream

bool isStream() const;

Returns true if socket is a stream socket, false otherwise.

### lastError

static int lastError();

Returns the last error code.

### lastErrorDesc

static std::string lastErrorDesc();

Returns the last error description.

### makeBufVec

static SocketBufVec makeBufVec(
std::size_t size,
std::size_t bufLen
);

Creates and returns a vector of requested size, with allocated buffers and lengths set accordingly. This utility function works well when all buffers are of same size.

### makeBufVec

static SocketBufVec makeBufVec(
const std::vector < char * > & vec
);

Creates and returns a vector of requested size, with buffers pointing to the supplied data (so, `vec` must remain available at the time of use) and lengths set accordingly. Notes:

- data length is determined using `strlen`, so this function is not meant to be used with binary data.

- if the returned buffer is used for read operations (ie. operations that write to the bufer), pointing to string literals will result in undefined behavior, in best case an I/O error and subsequent exception

### makeBufVec

static SocketBufVec makeBufVec(
const std::vector < std::string > & vec
);

Creates and returns a vector of requested size, with buffers pointing to the supplied data (so, `vec` must remain available at the time of use) and lengths set accordingly. Note:: this function is not suitable for creation of buffers used for writing (ie. reading from socket into buffers).

### makeBuffer

static SocketBuf makeBuffer(
void * buffer,
std::size_t length
);

Creates and returns buffer. Suitable for creating the appropriate buffer for the platform.

### operator !=

bool operator != (
const Socket & socket
) const;

Returns false if both sockets share the same SocketImpl, true otherwise.

### operator <

bool operator < (
const Socket & socket
) const;

Compares the SocketImpl pointers.

### operator <=

bool operator <= (
const Socket & socket
) const;

Compares the SocketImpl pointers.

### operator =

Socket & operator = (
const Socket & socket
);

Assignment operator.

Releases the socket's SocketImpl and attaches the SocketImpl from the other socket and increments the reference count of the SocketImpl.

### operator ==

bool operator == (
const Socket & socket
) const;

Returns true if both sockets share the same SocketImpl, false otherwise.

### operator >

bool operator > (
const Socket & socket
) const;

Compares the SocketImpl pointers.

### operator >=

bool operator >= (
const Socket & socket
) const;

Compares the SocketImpl pointers.

### peerAddress

SocketAddress peerAddress() const;

Returns the IP address and port number of the peer socket.

### poll

bool poll(
const Poco::Timespan & timeout,
int mode
) const;

Determines the status of the socket, using a call to poll() or select().

The mode argument is constructed by combining the values of the SelectMode enumeration.

Returns true if the next operation corresponding to mode will not block, false otherwise.

### secure

bool secure() const;

Returns true if and only if the socket's connection is secure (using SSL or TLS).

### select

static int select(
SocketList & readList,
SocketList & writeList,
SocketList & exceptList,
const Poco::Timespan & timeout
);

Determines the status of one or more sockets.

Uses epoll (Linux, Windows, Android), poll (BSD), or select() as fallback on platforms where neither is available.

ReadList contains the list of sockets which should be checked for readability.

WriteList contains the list of sockets which should be checked for writeability.

ExceptList contains a list of sockets which should be checked for a pending error.

Returns the number of sockets ready.

After return,

- readList contains those sockets ready for reading,
- writeList contains those sockets ready for writing,
- exceptList contains those sockets with a pending error.

If the total number of sockets passed in readList, writeList and exceptList is zero, select() will return immediately and the return value will be 0.

If one of the sockets passed to select() is closed while select() runs, select will return immediately. However, the closed socket will not be included in any list. In this case, the return value may be greater than the sum of all sockets in all list.

On platforms without epoll or poll support, this function uses the select() system call and is deprecated - use PollSet instead.

### setBlocking

void setBlocking(
bool flag
);

Sets the socket in blocking mode if flag is true, disables blocking mode if flag is false.

### setKeepAlive

void setKeepAlive(
bool flag
);

Sets the value of the SO_KEEPALIVE socket option.

### setLinger

void setLinger(
bool on,
int seconds
);

Sets the value of the SO_LINGER socket option.

### setNoDelay

void setNoDelay(
bool flag
);

Sets the value of the TCP_NODELAY socket option.

### setOOBInline

void setOOBInline(
bool flag
);

Sets the value of the SO_OOBINLINE socket option.

### setOption

void setOption(
int level,
int option,
int value
);

Sets the socket option specified by level and option to the given integer value.

### setOption

void setOption(
int level,
int option,
unsigned value
);

Sets the socket option specified by level and option to the given integer value.

### setOption

void setOption(
int level,
int option,
unsigned char value
);

Sets the socket option specified by level and option to the given integer value.

### setOption

void setOption(
int level,
int option,
const Poco::Timespan & value
);

Sets the socket option specified by level and option to the given time value.

### setOption

void setOption(
int level,
int option,
const IPAddress & value
);

Sets the socket option specified by level and option to the given time value.

### setReceiveBufferSize

void setReceiveBufferSize(
int size
);

Sets the size of the receive buffer.

### setReceiveTimeout

void setReceiveTimeout(
const Poco::Timespan & timeout
);

Sets the receive timeout for the socket.

On systems that do not support SO_RCVTIMEO, a workaround using poll() is provided.

### setReuseAddress

void setReuseAddress(
bool flag
);

Sets the value of the SO_REUSEADDR socket option.

### setReusePort

void setReusePort(
bool flag
);

Sets the value of the SO_REUSEPORT socket option. Does nothing if the socket implementation does not support SO_REUSEPORT.

### setSendBufferSize

void setSendBufferSize(
int size
);

Sets the size of the send buffer.

### setSendTimeout

void setSendTimeout(
const Poco::Timespan & timeout
);

Sets the send timeout for the socket.

### supportsIPv4

static bool supportsIPv4();

Returns true if the system supports IPv4.

### supportsIPv6

static bool supportsIPv6();

Returns true if the system supports IPv6.

### type

Type type() const;

Returns the socket type.

### sockfd

int sockfd() const;

Returns the socket descriptor for this socket.