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 protected

Socket(
    SocketImpl * pImpl
);

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

Destructor

~Socket virtual

virtual ~Socket();

Destroys the Socket and releases the SocketImpl.

Member Functions

address inline

SocketAddress address() const;

Returns the IP address and port number of the socket.

available inline

int available() const;

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

close inline

void close();

Closes the socket.

destroyBufVec static

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

static void error();

Throws an appropriate exception for the last error.

fromFileDescriptor static

static Socket fromFileDescriptor(
    int fd
);

getBlocking inline

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 inline

int getError() const;

Returns the socket error.

getKeepAlive inline

bool getKeepAlive() const;

Returns the value of the SO_KEEPALIVE socket option.

getLinger inline

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

Returns the value of the SO_LINGER socket option.

getNoDelay inline

bool getNoDelay() const;

Returns the value of the TCP_NODELAY socket option.

getOOBInline inline

bool getOOBInline() const;

Returns the value of the SO_OOBINLINE socket option.

getOption inline

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 inline

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 inline

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 inline

bool getReuseAddress() const;

Returns the value of the SO_REUSEADDR socket option.

getReusePort inline

bool getReusePort() const;

Returns the value of the SO_REUSEPORT socket option.

Returns false if the socket implementation does not support SO_REUSEPORT.

getSendBufferSize inline

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 inline

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 inline

SocketImpl * impl() const;

Returns the SocketImpl for this socket.

init inline

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 inline

bool isDatagram() const;

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

isNull inline

bool isNull() const;

Returns true if pointer to implementation is null.

isRaw inline

bool isRaw() const;

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

isStream inline

bool isStream() const;

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

lastError static

static int lastError();

Returns the last error code.

lastErrorDesc static

static std::string lastErrorDesc();

Returns the last error description.

makeBufVec static

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

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

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

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

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

operator != inline

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

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

operator < inline

bool operator < (
    const Socket & socket
) const;

Compares the SocketImpl pointers.

operator <= inline

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

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

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

operator > inline

bool operator > (
    const Socket & socket
) const;

Compares the SocketImpl pointers.

operator >= inline

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

Compares the SocketImpl pointers.

peerAddress inline

SocketAddress peerAddress() const;

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

poll inline

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 inline

bool secure() const;

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

select static

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

Deprecated. This function is deprecated and should no longer be used.

Determines the status of one or more sockets, using a call to select().

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.

This function is deprecated and may be removed in the future releases, please use PollSet class instead.

setBlocking inline

void setBlocking(
    bool flag
);

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

setKeepAlive inline

void setKeepAlive(
    bool flag
);

Sets the value of the SO_KEEPALIVE socket option.

setLinger inline

void setLinger(
    bool on,
    int seconds
);

Sets the value of the SO_LINGER socket option.

setNoDelay inline

void setNoDelay(
    bool flag
);

Sets the value of the TCP_NODELAY socket option.

setOOBInline inline

void setOOBInline(
    bool flag
);

Sets the value of the SO_OOBINLINE socket option.

setOption inline

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 inline

void setReceiveBufferSize(
    int size
);

Sets the size of the receive buffer.

setReceiveTimeout inline

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

Sets the send timeout for the socket.

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

setReuseAddress inline

void setReuseAddress(
    bool flag
);

Sets the value of the SO_REUSEADDR socket option.

setReusePort inline

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 inline

void setSendBufferSize(
    int size
);

Sets the size of the send buffer.

setSendTimeout inline

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

Sets the send timeout for the socket.

supportsIPv4 static inline

static bool supportsIPv4();

Returns true if the system supports IPv4.

supportsIPv6 static inline

static bool supportsIPv6();

Returns true if the system supports IPv6.

type inline

Type type() const;

Returns the socket type.

sockfd protected inline

int sockfd() const;

Returns the socket descriptor for this socket.