UPnPsdk::CSocket Class Reference

Manage all aspects of a network socket. More...

#include <socket.hpp>

Inheritance diagram for UPnPsdk::CSocket:

Collaboration diagram for UPnPsdk::CSocket:

Public Member Functions
	CSocket ()
	Default constructor for an empty socket object.
	CSocket (CSocket &&)
	Move constructor.
CSocket &	operator= (CSocket)
	Assignment operator.
virtual	~CSocket ()
	Destructor.
Setter
void	bind (const int a_socktype, const SSockaddr *const a_saddr=nullptr, const int a_flags=0)
	Bind socket to an ip address of a local network adapter.
void	listen ()
	Set socket to listen.
Getter
bool	is_listen () const
	Get status if the socket is listen to incomming network packets.
Public Member Functions inherited from UPnPsdk::CSocket_basic
	CSocket_basic ()
	Default constructor for an empty basic socket object with invalid socket file descriptor.
	CSocket_basic (SOCKET a_sfd)
	Constructor for the socket file descriptor. Before use, it must be load().
void	load ()
	Load the raw socket file descriptor specified with the constructor into the object.
	operator SOCKET () const
	Get raw socket file descriptor.
bool	local_saddr (SSockaddr *a_saddr=nullptr) const
	Get the local socket address the socket is bound to.
bool	remote_saddr (SSockaddr *a_saddr=nullptr) const
	Get the remote socket address the socket is connected to.
int	socktype () const
	Get the socket type.
int	sockerr () const
	Get the error that is given from the socket as option.
bool	is_reuse_addr () const
	Get status if reusing address is enabled.

Detailed Description

Manage all aspects of a network socket.

For general information have a look at socket_module.

Definition at line 320 of file socket.hpp.

Constructor & Destructor Documentation

CSocket() [1/2]

UPnPsdk::CSocket::CSocket

(

)

Default constructor for an empty socket object.

Definition at line 404 of file socket.cpp.

CSocket() [2/2]

UPnPsdk::CSocket::CSocket

(

CSocket &&

that

)

Move constructor.

This moves the socket object to a new instantiated socket object and also transfers ownership to the new object. That means the destination also manage and frees its resources now. After moving, the source object is still valid but empty with an INVALID_SOCKET. Using its methods will throw exceptions. But you can assign (operator=()) another socket object to it again.

// Usage e.g.:
CSocket sock1Obj;
try {
    sock1Obj.bind(SOCK_STREAM);
} catch(xcp) { // handle error }
CSocket sock2Obj{std::move(sock1Obj)};

Definition at line 407 of file socket.cpp.

~CSocket()

UPnPsdk::CSocket::~CSocket ( )

virtual

Destructor.

Definition at line 429 of file socket.cpp.

Member Function Documentation

operator=()

CSocket & UPnPsdk::CSocket::operator=

(

CSocket

that

)

Assignment operator.

This moves the socket object to another already existing socket object and also transfers ownership to it. That means the destination object also manage and frees its resources now. After moving, the source object is still valid but empty with an INVALID_SOCKET. Using its methods will throw exceptions.

// Usage e.g.:
CSocket sock1Obj;
try {
    sock1Obj.bind(SOCK_STREAM);
} catch(xcp) { // handle error }
CSocket sock2Obj;
sock2Obj = std::move(sock1Obj);

Definition at line 419 of file socket.cpp.

bind()

void UPnPsdk::CSocket::bind	(	const int	a_socktype,
		const SSockaddr *const	a_saddr = nullptr,
		const int	a_flags = 0
	)

Bind socket to an ip address of a local network adapter.

Usage e.g. to bind with default settings to an IP address of a local network adapter for use with connect, sendto, or sendmsg to send requests (typically control points). The address is selected by the operating system and considered to be the best choise.

CSocket sock1Obj;
try {
    sock1Obj.bind(SOCK_STREAM);
} catch(std::exception& ex) { handle_error(); }

Usage e.g. to bind with default settings for listening on local network adapters for incomming requests (typically UPnP devices).

CSocket sock2Obj;
try {
    sock2Obj.bind(SOCK_STREAM, nullptr, AI_PASSIVE);
} catch(std::exception& ex) { handle_error(); }

Usage e.g. to bind for listening on the link local address of a local network adapter.

SSockaddr saddr3;
saddr3 = "[fe80::fedc:cdef:0:1]";
CSocket sock3Obj;
try {
    sock3Obj.bind(SOCK_STREAM, &saddr3, AI_PASSIVE);
} catch(std::exception& ex) { handle_error(); }

Usage e.g. to bind to a global unicast address for use with connect, sendto, or sendmsg.

SSockaddr saddr4;
saddr4 = "[2001:db8::abc]:50001";
CSocket sock4Obj;
try {
    sock4Obj.bind(SOCK_STREAM, &saddr4);
} catch(std::exception& ex) { handle_error(); }

Usage e.g. to bind to "localhost", resp. to one of the loopback addresses of best choise.

SSockaddr saddr5; // Unspecified address selects a loopback address.
CSocket sock5Obj;
try {
    sock5Obj.bind(SOCK_STREAM, &saddr5);
} catch(std::exception& ex) { handle_error(); }

You can also use "localhost" with CAddrinfo, but that allocates memory and do a DNS lookup. You should prefer the previous example.

SSockaddr saddr6;
CSocket sock6Obj;
CAddrinfo ai("localhost");
try {
    ai.get_first();
    ai.local_saddr(&saddr6);
    sock6Obj.bind(SOCK_STREAM, &saddr6);
} catch(std::exception& ex) { handle_error(); }

This method uses internally the system function ::getaddrinfo() to provide possible socket addresses. If the AI_PASSIVE flag is specified with a_flags, and a_saddr is an unspecified socket address (netaddress ":0") , then the selected local socket addresses will be suitable for binding a socket that will accept connections. The selected local socket address will contain the "wildcard address" (INADDR_ANY for IPv4 addresses, IN6ADDR_ANY_INIT for IPv6 address). The wildcard address is used by applications (typically UPnP devices) that intend to accept connections on any of the host's network addresses. If a_saddr is specified, then the AI_PASSIVE flag is ignored.

If the AI_PASSIVE flag is not set, then the selected local socket addresses will be suitable for use with connect, sendto, or sendmsg (typically control points).

I internally always set IPV6_V6ONLY to false to use IPv6 mapped IPv4 addresses. This is default on Unix platforms when binding the address and cannot be modified after binding. MacOS does not modify IPV6_V6ONLY with binding. On Microsoft Windows IPV6_V6ONLY is set by default.

Parameters

[in]	a_socktype	This property must always be specified with SOCK_STREAM, or SOCK_DGRAM.
[in]	a_saddr	Optional: Pointer to a socket address the socket shall be bound to.
[in]	a_flags	Optional: this field specifies additional options, as described at getaddrinfo(3) — Linux manual page or at Microsoft Build — addrinfo structure. Multiple flags are specified by bitwise OR-ing them together. Example is: AI_PASSIVE | AI_NUMERICHOST | AI_NUMERICSERV

Definition at line 464 of file socket.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

listen()

void UPnPsdk::CSocket::listen

(

)

Set socket to listen.

On Linux there is a socket option SO_ACCEPTCONN that can be get with system function ::getsockopt(). This option shows if the socket is set to passive listen. But it is not portable. MacOS does not support it. So this flag has to be managed here. Look for details at How to get option on MacOS if a socket is set to listen?

Definition at line 552 of file socket.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

is_listen()

bool UPnPsdk::CSocket::is_listen

(

)

const

Get status if the socket is listen to incomming network packets.

Returns

• true  Socket is listen to incomming network packets
• false otherwise.

Exceptions

std::runtime_error

Failed to get socket option from unbind socket.

Definition at line 581 of file socket.cpp.

---

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

• UPnPsdk/include/UPnPsdk/socket.hpp
• UPnPsdk/src/net/socket.cpp