Base class for Socket types with ownership of a FileDescriptor. More...

#include <Socket.hxx>

Inheritance diagram for cosmos::Socket:

Public Types
enum class	Direction : int { READ = SHUT_RD , WRITE = SHUT_WR , READ_WRITE = SHUT_RDWR }
	Type used in Socket::shutdown(). More...

using	AddressFilledIn = NamedBool<struct addr_filled_in_t, false>
	Boolean flag used in receiveFrom() to signify if a peer address could be provided.

Public Types inherited from cosmos::StreamIO
enum class	SeekType : int { SET = SEEK_SET , CUR = SEEK_CUR , END = SEEK_END , DATA = SEEK_DATA , HOLE = SEEK_HOLE }
	Different methods for changing the file read/write position. More...

Public Member Functions
auto	sockOptions ()

auto	sockOptions () const

void	getSockName (SocketAddress &addr)
	Returns the current address that the socket is bound to, if any.

void	shutdown (const Direction dir)
	Shutdown part or all of the connection on protocol level.

Public Member Functions inherited from cosmos::FDFile
	FDFile (const FileDescriptor fd, const AutoCloseFD auto_close)
	Wrap the given file descriptor applying the specified auto-close behaviour.

	FDFile (FDFile &&other) noexcept

FDFile &	operator= (FDFile &&other) noexcept

void	open (const FileDescriptor fd, const AutoCloseFD auto_close)
	Takes the already open file descriptor fd and operates on it.

void	close () override
	Close the current file object.

Public Member Functions inherited from cosmos::FileBase
	FileBase (const FileBase &)=delete

FileBase &	operator= (const FileBase &)=delete

bool	isOpen () const
	Returns whether currently a FileDescriptor is opened.

FileDescriptor	fd () const
	Allows access to the underlying fd with const semantics.

void	truncate (const off_t length)

Public Member Functions inherited from cosmos::StreamIO
	StreamIO (FileDescriptor &fd)

	StreamIO (const StreamIO &)=delete

StreamIO &	operator= (const StreamIO &)=delete

StreamIO &	operator= (StreamIO &&) noexcept

size_t	read (void *buf, size_t length)
	Read up to `length` bytes from the file into `buf`.

size_t	write (const void *buf, size_t length)
	Write up to `length` bytes from `buf` into the underlying file.

size_t	write (const std::string_view data)
	string_view wrapper around write(const void*, size_t).

void	readAll (void *buf, size_t length)
	Read all `length` bytes from the underlying file.

void	readAll (std::string &s, size_t length)
	Like readAll(void*, size_t) using an STL string.

void	writeAll (const void *buf, size_t length)
	Write all `length` bytes into the underlying file.

void	writeAll (const std::string_view data)
	string_view wrapper around writeAll(const void*, size_t).

bool	read (ReadIOVector &iovec)
	Read data from file into a vector of data regions.

bool	write (WriteIOVector &iovec)
	Write data to file from a vector of data regions.

void	readAll (ReadIOVector &iovec)
	Read into all data regions specified in `iovec`.

void	writeAll (WriteIOVector &iovec)
	Write all data regions specified in `iovec`.

off_t	seek (const SeekType type, off_t off)
	Seek to the given offset based on the given offset `type`.

off_t	seekFromStart (off_t off)
	Seek to the given offset relative to the start of the file.

off_t	seekFromCurrent (off_t off)
	Seek to the given offset relative to the current file position.

off_t	seekFromEnd (off_t off)
	Seek to the given offset relative to the end of the file.

Protected Member Functions
	Socket (const SocketFamily family, const SocketType type, const SocketFlags flags=SocketFlags{SocketFlag::CLOEXEC}, const SocketProtocol protocol=SocketProtocol::DEFAULT)
	Creates a new socket using the given properties.

	Socket (FileDescriptor fd, const AutoCloseFD auto_close)
	Creates a new socket from the given existing file descriptor.

void	bind (const SocketAddress &addr)
	Bind the socket to the given local address.

void	connect (const SocketAddress &addr)
	Establish a new connection using the given destination address.

void	listen (const size_t backlog)
	Enter into a passive listen state, allowing new connections.

FileDescriptor	accept (SocketAddress *addr)
	Accept a new connection on the socket.

size_t	send (const void *buf, size_t length, const MessageFlags flags=MessageFlags{})
	Send the given data over the socket, using specific send flags.

size_t	send (const std::string_view data, const MessageFlags flags=MessageFlags{})
	Variant of send() that takes a std::string_view container instead of a raw input buffer.

size_t	sendTo (const void *buf, size_t length, const SocketAddress &addr, const MessageFlags flags=MessageFlags{})
	Send a packet to a specific destination address.

size_t	sendTo (const std::string_view data, const SocketAddress &addr, const MessageFlags flags=MessageFlags{})
	Variant of sendTo() that takes a std::string_view container instead of a raw input buffer.

void	sendMessage (SendMessageHeader &header, const SocketAddress *addr=nullptr)
	Sends a message over the socket using extended SendMessageHeader data.

size_t	receive (void *buf, size_t length, const MessageFlags flags=MessageFlags{})
	Receive data from the socket, using specific receive flags.

std::pair< size_t, AddressFilledIn >	receiveFrom (void *buf, size_t length, SocketAddress &addr, const MessageFlags flags=MessageFlags{})
	Receive a packet, filling in the sender's address.

AddressFilledIn	receiveMessage (ReceiveMessageHeader &header, SocketAddress *addr=nullptr)
	Receives a message from the socket using extended ReceiveMessageHeader data.

Protected Member Functions inherited from cosmos::FileBase
	FileBase (const FileDescriptor fd=FileDescriptor{})

	FileBase (FileBase &&other) noexcept

FileBase &	operator= (FileBase &&other) noexcept

Additional Inherited Members
Protected Attributes inherited from cosmos::FDFile
AutoCloseFD	m_auto_close

Protected Attributes inherited from cosmos::FileBase
FileDescriptor	m_fd

Protected Attributes inherited from cosmos::StreamIO
FileDescriptor &	m_stream_fd

Detailed Description

Base class for Socket types with ownership of a FileDescriptor.

Specializations of Socket carry ownership of a socket FileDescriptor. The exact type of socket is defined by the specialization.

This type inherits the StreamIO interface for operating using regular streaming file I/O on the socket. Not all socket types support this (most notably listening sockets that are only used to accept new connections). These socket types mark the I/O APIs as protected in their implementation.

Furthermore this Socket base class implements a range of Socket specific operations and I/O functions, all of which are marked protected. Specializations of Socket need to make these functions accessible as far as they make sense for the concrete socket type.

This base class also provides access to the basic SocketOptions for the socket.

Definition at line 37 of file Socket.hxx.

Member Typedef Documentation

◆ AddressFilledIn

using cosmos::Socket::AddressFilledIn = NamedBool<struct addr_filled_in_t, false>

Boolean flag used in receiveFrom() to signify if a peer address could be provided.

Definition at line 50 of file Socket.hxx.

Member Enumeration Documentation

◆ Direction

enum class cosmos::Socket::Direction : int

strong

Type used in Socket::shutdown().

Definition at line 43 of file Socket.hxx.

                             : int {
                READ = SHUT_RD,
                WRITE = SHUT_WR,
                READ_WRITE = SHUT_RDWR
        };

Constructor & Destructor Documentation

◆ Socket() [1/2]

cosmos::Socket::Socket	(	const SocketFamily	family,
		const SocketType	type,
		const SocketFlags	flags = SocketFlags{SocketFlag::CLOEXEC},
		const SocketProtocol	protocol = SocketProtocol::DEFAULT )

protected

Creates a new socket using the given properties.

Definition at line 11 of file Socket.cxx.

                                               {
        auto fd = ::socket(
                        to_integral(family),
                        to_integral(type) | flags.raw(),
                        to_integral(protocol));
        m_fd.setFD(FileNum{fd});
 
        if (!m_fd.valid()) {
                cosmos_throw(ApiError("socket()"));
        }
}

◆ Socket() [2/2]

cosmos::Socket::Socket	(	FileDescriptor	fd,
		const AutoCloseFD	auto_close )

inlineprotected

Creates a new socket from the given existing file descriptor.

Definition at line 86 of file Socket.hxx.

                                                                :
                        FDFile{fd, auto_close}
        {}

Member Function Documentation

◆ accept()

FileDescriptor cosmos::Socket::accept ( SocketAddress * addr )

protected

Accept a new connection on the socket.

This is only possible for connection mode socket types that have been put into the listen state via the listen() function.

The returned file descriptor refers to the new connection that has been accepted. The optional addr parameter will receive the address of the newly accepted connection.

This is only a lower level function that returns an unmanaged file descriptor. The implementation needs to take care that the file descriptor is not lost but encapsulated in an object that can manage its lifetime.

Definition at line 51 of file Socket.cxx.

                                                 {
        socklen_t addrlen = addr ? addr->maxSize() : 0;
        auto res = ::accept(to_integral(m_fd.raw()), addr ? addr->basePtr() : nullptr, addr ? &addrlen : nullptr);
 
        if (res == -1) {
                cosmos_throw (ApiError("accept()"));
        }
 
        if (addr) {
                addr->update(addrlen);
        }
 
        return FileDescriptor{FileNum{res}};
}

◆ bind()

void cosmos::Socket::bind ( const SocketAddress & addr )

protected

Bind the socket to the given local address.

This operation is used for connection oriented sockets to define the local address at which it will be listening for new connections.

For connectionless sockets this can be used to explicitly choose a local address for outgoing packets, and to receive packets at this address by default.

Definition at line 27 of file Socket.cxx.

                                           {
        if (::bind(to_integral(m_fd.raw()), addr.basePtr(), addr.size()) != 0) {
                cosmos_throw(ApiError("bind()"));
        }
}

◆ connect()

void cosmos::Socket::connect ( const SocketAddress & addr )

protected

Establish a new connection using the given destination address.

For connection oriented sockets this performs the protocol operations to establish a new connection to the given address.

For connectionless sockets this defines the default send destination and a filter for incoming packets.

Depending on the non-blocking mode of the socket the connection will either block and only return successfully if the connection has been established. Or, if non-blocking mode is enabled, the call will return immediately, and the result can be obtained via SocketOption::lastError() at a later time. The connect() behaviour can also be influenced by further socket specific options.

Definition at line 33 of file Socket.cxx.

                                              {
        if (::connect(to_integral(m_fd.raw()), addr.basePtr(), addr.size()) != 0) {
                cosmos_throw(ApiError("connect()"));
        }
}

◆ getSockName()

void cosmos::Socket::getSockName ( SocketAddress & addr )

Returns the current address that the socket is bound to, if any.

Definition at line 111 of file Socket.cxx.

                                            {
        socklen_t size = addr.maxSize();
        auto base = addr.basePtr();
        if (::getsockname(to_integral(m_fd.raw()), base, &size) != 0) {
                cosmos_throw(ApiError("getsockname()"));
        }
 
        if (SocketFamily{base->sa_family} != addr.family()) {
                addr.clear();
                cosmos_throw(RuntimeError("getsockname: wrong type of SocketAddress was passed"));
        }
 
        addr.update(size);
}

◆ listen()

void cosmos::Socket::listen ( const size_t backlog )

protected

Enter into a passive listen state, allowing new connections.

This is only possible for connection mode socket types, when you want to accept new connections. For client side sockets this is not necessary.

Parameters

[in] backlog The number of pending connections that may be queued in the kernel.

Definition at line 45 of file Socket.cxx.

                                        {
        if (::listen(to_integral(m_fd.raw()), backlog) != 0) {
                cosmos_throw (ApiError("listen()"));
        }
}

◆ receive()

size_t cosmos::Socket::receive	(	void *	buf,
		size_t	length,
		const MessageFlags	flags = MessageFlags{} )

protected

Receive data from the socket, using specific receive flags.

This is like a regular read() call but allows to specify socket specific MessageFlags to adjust various behaviour.

Definition at line 84 of file Socket.cxx.

                                                                         {
        const auto res = ::recv(to_integral(m_fd.raw()), buf, length, flags.raw());
        if (res < 0) {
                cosmos_throw(ApiError("recv()"));
        }
 
        return static_cast<size_t>(res);
}

◆ receiveFrom()

std::pair< size_t, Socket::AddressFilledIn > cosmos::Socket::receiveFrom	(	void *	buf,
		size_t	length,
		SocketAddress &	addr,
		const MessageFlags	flags = MessageFlags{} )

protected

Receive a packet, filling in the sender's address.

This call is like receive() but fills in the sender's address in addr, if possible. This generally doesn't make sense with connection mode socket types (where the peer is defined during connect() time). If the sender's address isn't available then addr is left unchanged.

The returned pair contains the number of bytes written to buf and a boolean type indicating whether addr was filled in or not.

Definition at line 94 of file Socket.cxx.

                                                                                           {
        socklen_t addrlen = addr.maxSize();
        const auto res = ::recvfrom(to_integral(m_fd.raw()), buf, length, flags.raw(), addr.basePtr(), &addrlen);
        if (res < 0) {
                cosmos_throw(ApiError("recvfrom()"));
        }
 
        const AddressFilledIn filled_in{addrlen != 0};
 
        // when no sender's address is available addrlen will be zero.
        if (filled_in) {
                addr.update(addrlen);
        }
 
        return {static_cast<size_t>(res), filled_in};
}

◆ receiveMessage()

Socket::AddressFilledIn cosmos::Socket::receiveMessage	(	ReceiveMessageHeader &	header,
		SocketAddress *	addr = nullptr )

protected

Receives a message from the socket using extended ReceiveMessageHeader data.

This variant of the receive family of functions allows the following advanced features compared to recvFrom():

receiving data into multiple scatter/gather memory locations using the ReadIOVector iovec member of header.
reception of additional ancillary data using ReceiveMessageHeader::setControlBufferSize().

If addr is passed then the source address of the message is placed in this SocketAddress structure, if one is available. Whether it was filled in is indicated by the return value.

The amount of received data is reflected in an updated iovec member of the header parameter. Partial receives are possible. If the control message buffer is setup in header then you need to check for received ancillary messages using the iterator interface of header. Control messages can have side effects when using them on UNIX domain sockets (file descriptors being allocated in the receiving process). Therefore accepting ancillary messages should not be taken lightly.

Definition at line 145 of file Socket.cxx.

                                                                                              {
        header.prepareReceive(addr);
 
        const auto res = ::recvmsg(
                        to_integral(m_fd.raw()),
                        header.rawHeader(),
                        header.ioFlags().raw());
 
        if (res < 0) {
                cosmos_throw(ApiError("recvmsg()"));
        }
 
        auto ret = Socket::AddressFilledIn{false};
 
        if (addr) {
                if (const auto namelen = header.rawHeader()->msg_namelen; namelen != 0) {
                        ret = Socket::AddressFilledIn{true};
                        addr->update(namelen);
                }
        }
 
        header.postReceive(res);
 
        return ret;
}

◆ send() [1/2]

size_t cosmos::Socket::send	(	const std::string_view	data,
		const MessageFlags	flags = MessageFlags{} )

inlineprotected

Variant of send() that takes a std::string_view container instead of a raw input buffer.

Definition at line 153 of file Socket.hxx.

                                                                                      {}) {
                return send(data.data(), data.size(), flags);
        }

◆ send() [2/2]

size_t cosmos::Socket::send	(	const void *	buf,
		size_t	length,
		const MessageFlags	flags = MessageFlags{} )

protected

Send the given data over the socket, using specific send flags.

This is like a regular write() call but allows to specify socket specific MessageFlags to adjust various behaviour.

Definition at line 66 of file Socket.cxx.

                                                                            {
        const auto res = ::send(to_integral(m_fd.raw()), buf, length, flags.raw());
        if (res < 0) {
                cosmos_throw(ApiError("send()"));
        }
 
        return static_cast<size_t>(res);
}

◆ sendMessage()

void cosmos::Socket::sendMessage	(	SendMessageHeader &	header,
		const SocketAddress *	addr = nullptr )

protected

Sends a message over the socket using extended SendMessageHeader data.

This variant of the send family of functions allows the following advanced features compared to sendTo():

sending data from multiple scatter/gather memory locations using the WriteIOVector iovec member of header.
passing additional ancillary data using the control_msg member of header.

If addr is passed then this specific target address is used for sending the data.

The amount of sent data is reflected in an updated iovec member of the header parameter. Partial sends are possible. If a control_msg is set in header and at least one succesful (even partial) sendMessage() call was performed, then the control message will have been processed completely. The control_msg member will be reset automaically in this case to avoid it being sent multiple times without intent.

Definition at line 126 of file Socket.cxx.

                                                                             {
        header.prepareSend(addr);
 
        const auto res = ::sendmsg(
                        to_integral(m_fd.raw()),
                        header.rawHeader(),
                        header.ioFlags().raw());
 
        if (res < 0) {
                cosmos_throw(ApiError("sendmsg()"));
        }
 
        // NOTE: if a control message is configured in the header, then even
        // on partial writes the control message will always be transmitted.
        // The result will contain the bytes of the control message, only the
        // actual message payload.
        header.postSend(res);
}

◆ sendTo() [1/2]

size_t cosmos::Socket::sendTo	(	const std::string_view	data,
		const SocketAddress &	addr,
		const MessageFlags	flags = MessageFlags{} )

inlineprotected

Variant of sendTo() that takes a std::string_view container instead of a raw input buffer.

Definition at line 171 of file Socket.hxx.

                                                               {}) {
                return sendTo(data.data(), data.size(), addr, flags);
        }

◆ sendTo() [2/2]

size_t cosmos::Socket::sendTo	(	const void *	buf,
		size_t	length,
		const SocketAddress &	addr,
		const MessageFlags	flags = MessageFlags{} )

protected

Send a packet to a specific destination address.

This call is like send() but takes a specific destination address to send the data to. This can be used e.g. with datagram sockets where one socket can be used to talk to multiple remote destinations.

This is not supported for connection mode socket types (since there is only one possible peer address defined during connect() time).

Definition at line 75 of file Socket.cxx.

                                                                                                         {
        const auto res = ::sendto(to_integral(m_fd.raw()), buf, length, flags.raw(), addr.basePtr(), addr.size());
        if (res < 0) {
                cosmos_throw(ApiError("sendto()"));
        }
 
        return static_cast<size_t>(res);
}

◆ shutdown()

void cosmos::Socket::shutdown ( const Direction dir )

Shutdown part or all of the connection on protocol level.

This is distinct from a close() operation in that it performs a graceful shutdown of a network connection. It can be limited to the receiving end, the sending end or affect both.

On Linux this can also be used to stop a blocking accept() call on a listening socket.

Definition at line 39 of file Socket.cxx.

                                         {
        if (::shutdown(to_integral(m_fd.raw()), to_integral(dir)) != 0) {
                cosmos_throw (ApiError("shutdown()"));
        }
}

◆ sockOptions() [1/2]

auto cosmos::Socket::sockOptions ( )

inline

Definition at line 54 of file Socket.hxx.

                           {
                return SocketOptions{m_fd};
        }

◆ sockOptions() [2/2]

auto cosmos::Socket::sockOptions ( ) const

inline

Definition at line 58 of file Socket.hxx.

                                 {
                return SocketOptions{m_fd};
        }

The documentation for this class was generated from the following files:

include/net/Socket.hxx
src/net/Socket.cxx

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ AddressFilledIn

Member Enumeration Documentation

◆ Direction

Constructor & Destructor Documentation

◆ Socket() [1/2]

◆ Socket() [2/2]

Member Function Documentation

◆ accept()

◆ bind()

◆ connect()

◆ getSockName()

◆ listen()

◆ receive()

◆ receiveFrom()

◆ receiveMessage()

◆ send() [1/2]

◆ send() [2/2]

◆ sendMessage()

◆ sendTo() [1/2]

◆ sendTo() [2/2]

◆ shutdown()

◆ sockOptions() [1/2]

◆ sockOptions() [2/2]