SC::SocketDescriptor Struct Reference

Low-level OS socket handle. More...

#include <Socket.h>

Inheritance diagram for SC::SocketDescriptor:

Public Member Functions
ResultSocket	create (SocketFlags::AddressFamily addressFamily, SocketFlags::SocketType socketType=SocketFlags::SocketStream, SocketFlags::ProtocolType protocol=SocketFlags::ProtocolTcp, SocketFlags::BlockingType blocking=SocketFlags::Blocking, SocketFlags::InheritableType inheritable=SocketFlags::NonInheritable)
	Creates a new SocketDescriptor Descriptor of given family, type, protocol.
ResultSocket	isInheritable (bool &value) const
	Check if socket is inheritable by child processes.
ResultSocket	setInheritable (bool value)
	Changes the inheritable flag for this socket.
ResultSocket	setBlocking (bool value)
	Changes the blocking flag for this socket (if IO reads / writes should be blocking or not)
ResultSocket	getAddressFamily (SocketFlags::AddressFamily &addressFamily) const
	Get the address family of this socket.
ResultSocket	shutdown (SocketFlags::ShutdownType shutdownType)
	Shuts down the socket for reading, writing, or both.
ResultSocket	setTcpNoDelay (bool tcpNoDelay)
	Disables Nagle's algorithm for low-latency communication.
ResultSocket	setBroadcast (bool enableBroadcast)
	Enables or disables broadcast on this socket (for UDP)
ResultSocket	joinMulticastGroup (const SocketIPAddress &multicastAddress, const SocketIPAddress &interfaceAddress)
	Joins an IPv4 or IPv6 multicast group on a specific interface.
ResultSocket	leaveMulticastGroup (const SocketIPAddress &multicastAddress, const SocketIPAddress &interfaceAddress)
	Leaves a previously joined IPv4 or IPv6 multicast group on a specific interface.
ResultSocket	setMulticastLoopback (SocketFlags::AddressFamily addressFamily, bool enableLoopback)
	Controls whether multicast traffic is sent back to the local host.
ResultSocket	setMulticastHops (SocketFlags::AddressFamily addressFamily, int hops)
	Specifies the default TTL or hop limit for outgoing multicast datagrams.
ResultSocket	setMulticastOutboundInterface (const SocketIPAddress &interfaceAddress)
	Specifies the default local network interface for outgoing multicast datagrams.
ResultSocket	sendTo (Span< const char > data, const SocketAddress &destination)
	Sends a datagram to the given destination address.
ResultSocket	sendTo (Span< const char > data, const SocketIPAddress &destination)
	IP-address compatibility overload for sendTo.
ResultSocket	receiveFrom (Span< char > buffer, Span< char > &receivedData, SocketAddress &sourceAddress)
	Receives a datagram, reporting its source address.
ResultSocket	receiveFrom (Span< char > buffer, Span< char > &receivedData, SocketIPAddress &sourceAddress)
	IP-address compatibility overload for receiveFrom.

Detailed Description

Low-level OS socket handle.

It also allow querying inheritability and changing it (and blocking mode)
Example (extracted from unit test):

    bool isInheritable;
 
    // We are testing only the inheritable because on windows there is no reliable
    // way of checking if a non-connected socket is in non-blocking mode
    SocketDescriptor socket;
    SC_TEST_EXPECT(socket.create(SocketFlags::AddressFamilyIPV4, SocketFlags::SocketStream, SocketFlags::ProtocolTcp,
                                 SocketFlags::NonBlocking, SocketFlags::NonInheritable));
    SC_TEST_EXPECT(socket.isValid());
    isInheritable = false;
    SC_TEST_EXPECT(socket.isInheritable(isInheritable));
    SC_TEST_EXPECT(not isInheritable);
    SC_TEST_EXPECT(socket.close());
 
    SC_TEST_EXPECT(socket.create(SocketFlags::AddressFamilyIPV4, SocketFlags::SocketStream, SocketFlags::ProtocolTcp,
                                 SocketFlags::Blocking, SocketFlags::NonInheritable));
    SC_TEST_EXPECT(socket.isValid());
    isInheritable = false;
    SC_TEST_EXPECT(socket.isInheritable(isInheritable));
    SC_TEST_EXPECT(not isInheritable);
    SC_TEST_EXPECT(socket.close());
 
    SC_TEST_EXPECT(socket.create(SocketFlags::AddressFamilyIPV4, SocketFlags::SocketStream, SocketFlags::ProtocolTcp,
                                 SocketFlags::Blocking, SocketFlags::Inheritable));
    SC_TEST_EXPECT(socket.isValid());
    isInheritable = false;
    SC_TEST_EXPECT(socket.isInheritable(isInheritable));
    SC_TEST_EXPECT(isInheritable);
 
    // Test TCP_NODELAY
    SC_TEST_EXPECT(socket.setTcpNoDelay(true));
    SC_TEST_EXPECT(socket.setTcpNoDelay(false));
 
    SC_TEST_EXPECT(socket.close());

Member Function Documentation

create()

ResultSocket SC::SocketDescriptor::create	(	SocketFlags::AddressFamily	addressFamily,
		SocketFlags::SocketType	socketType = SocketFlags::SocketStream,
		SocketFlags::ProtocolType	protocol = SocketFlags::ProtocolTcp,
		SocketFlags::BlockingType	blocking = SocketFlags::Blocking,
		SocketFlags::InheritableType	inheritable = SocketFlags::NonInheritable )

Creates a new SocketDescriptor Descriptor of given family, type, protocol.

Parameters

addressFamily	Address family (IPv4, IPv6, or Unix-domain)
socketType	SocketDescriptor type (Stream or Dgram)
protocol	Protocol (TCP, UDP, or the family/type default)
blocking	If the socket should be created in blocking mode
inheritable	If the socket should be inheritable by child processes

Returns

Valid Result if a socket with the requested options has been successfully created

getAddressFamily()

ResultSocket SC::SocketDescriptor::getAddressFamily

(

SocketFlags::AddressFamily &

addressFamily

)

const

Get the address family of this socket.

Parameters

[out]

addressFamily

The address family of this socket (if Result is valid)

Returns

Valid Result the address family for this socket has been queried successfully

isInheritable()

ResultSocket SC::SocketDescriptor::isInheritable

(

bool &

value

)

const

Check if socket is inheritable by child processes.

Parameters

[out]

value

if set to true indicates that this socket is inheritable by child processes

Returns

Valid Result if the inheritable status for this socket has been queried successfully

joinMulticastGroup()

ResultSocket SC::SocketDescriptor::joinMulticastGroup	(	const SocketIPAddress &	multicastAddress,
		const SocketIPAddress &	interfaceAddress )

Joins an IPv4 or IPv6 multicast group on a specific interface.

Parameters

multicastAddress	The multicast group address to join
interfaceAddress	The local interface address to join on

Returns

Valid Result if the socket has successfully joined the multicast group

leaveMulticastGroup()

ResultSocket SC::SocketDescriptor::leaveMulticastGroup	(	const SocketIPAddress &	multicastAddress,
		const SocketIPAddress &	interfaceAddress )

Leaves a previously joined IPv4 or IPv6 multicast group on a specific interface.

Parameters

multicastAddress	The multicast group address to leave
interfaceAddress	The local interface address to leave from

Returns

Valid Result if the socket has successfully left the multicast group

receiveFrom() [1/2]

ResultSocket SC::SocketDescriptor::receiveFrom	(	Span< char >	buffer,
		Span< char > &	receivedData,
		SocketAddress &	sourceAddress )

Receives a datagram, reporting its source address.

Parameters

[in,out]	buffer	Span of memory that will receive the datagram and may be modified on truncation
[out]	receivedData	A sub-Span of buffer containing the received bytes; unchanged on failure
[out]	sourceAddress	The source address; unchanged on failure

Returns

Valid Result if a complete datagram has been received successfully

Note

On non-blocking sockets, an unsuccessful Result is also returned when no datagram is immediately available

An oversized datagram is consumed and returns an unsuccessful Result. buffer may contain a truncated prefix

receiveFrom() [2/2]

ResultSocket SC::SocketDescriptor::receiveFrom	(	Span< char >	buffer,
		Span< char > &	receivedData,
		SocketIPAddress &	sourceAddress )

IP-address compatibility overload for receiveFrom.

sendTo() [1/2]

ResultSocket SC::SocketDescriptor::sendTo	(	Span< const char >	data,
		const SocketAddress &	destination )

Sends a datagram to the given destination address.

Parameters

data	Bytes to send as a single datagram; the whole span must be sent for success
destination	The destination address of the datagram

Returns

Valid Result if the whole datagram has been sent successfully

Note

On non-blocking sockets, an unsuccessful Result is also returned when the operation would block

sendTo() [2/2]

ResultSocket SC::SocketDescriptor::sendTo	(	Span< const char >	data,
		const SocketIPAddress &	destination )

IP-address compatibility overload for sendTo.

setBlocking()

ResultSocket SC::SocketDescriptor::setBlocking

(

bool

value

)

Changes the blocking flag for this socket (if IO reads / writes should be blocking or not)

Parameters

value

true if this socket should be made blocking, false for non-blocking

Returns

Valid Result if it has been possible changing the blocking status of this socket

setBroadcast()

ResultSocket SC::SocketDescriptor::setBroadcast

(

bool

enableBroadcast

)

Enables or disables broadcast on this socket (for UDP)

Parameters

enableBroadcast

true to enable broadcast (set SO_BROADCAST), false to disable

Returns

Valid Result if the SO_BROADCAST option has been set successfully

setInheritable()

ResultSocket SC::SocketDescriptor::setInheritable

(

bool

value

)

Changes the inheritable flag for this socket.

Parameters

value

true if this socket should be made inheritable, false for non-inheritable

Returns

Valid Result if it has been possible changing the inheritable status of this socket

setMulticastHops()

ResultSocket SC::SocketDescriptor::setMulticastHops	(	SocketFlags::AddressFamily	addressFamily,
		int	hops )

Specifies the default TTL or hop limit for outgoing multicast datagrams.

Parameters

addressFamily	Address family of the socket
hops	The hop limit (0-255)

Returns

Valid Result if the multicast hop limit has been set successfully

setMulticastLoopback()

ResultSocket SC::SocketDescriptor::setMulticastLoopback	(	SocketFlags::AddressFamily	addressFamily,
		bool	enableLoopback )

Controls whether multicast traffic is sent back to the local host.

Parameters

addressFamily	Address family of the socket
enableLoopback	true to enable multicast loopback, false to disable

Returns

Valid Result if the multicast loopback option has been set successfully

setMulticastOutboundInterface()

ResultSocket SC::SocketDescriptor::setMulticastOutboundInterface

(

const SocketIPAddress &

interfaceAddress

)

Specifies the default local network interface for outgoing multicast datagrams.

Parameters

interfaceAddress

The local interface address

Returns

Valid Result if the multicast outgoing interface has been set successfully

setTcpNoDelay()

ResultSocket SC::SocketDescriptor::setTcpNoDelay

(

bool

tcpNoDelay

)

Disables Nagle's algorithm for low-latency communication.

Parameters

tcpNoDelay

true to disable Nagle's algorithm (set TCP_NODELAY), false to enable it

Returns

Valid Result if the TCP_NODELAY option has been set successfully

shutdown()

ResultSocket SC::SocketDescriptor::shutdown

(

SocketFlags::ShutdownType

shutdownType

)

Shuts down the socket for reading, writing, or both.

Parameters

shutdownType

The type of shutdown to perform

Returns

Valid Result if the socket has been successfully shut down

---

The documentation for this struct was generated from the following file:

• Socket.h