Socket module

The socket module contains all classes and free functions to manage network sockets. More...

Classes
class	UPnPsdk::CSocket_basic
	Get information from a raw network socket file descriptor. More...
class	UPnPsdk::CSocket
	Manage all aspects of a network socket. More...
class	UPnPsdk::CSocketErr
	Class for portable handling of network socket errors. More...
class	UPnPsdk::anonymous_namespace{global.cpp}::CWSAStartup
	Initialize and cleanup Microsoft Windows Sockets. More...

Functions
int	UPnPsdk::anonymous_namespace{socket.cpp}::getsockname (SOCKET a_sockfd, sockaddr *a_addr, socklen_t *a_addrlen)
	Wrapper for the ::getsockname() system function.
SOCKET	UPnPsdk::anonymous_namespace{socket.cpp}::get_sockfd (sa_family_t a_pf_family, int a_socktype)
	Get a socket file descriptor from the operating system.

Variables
const CWSAStartup	UPnPsdk::anonymous_namespace{global.cpp}::init_winsock
	This object initialize and cleanup the Microsoft Windows Socket subsystem.

Detailed Description

The socket module contains all classes and free functions to manage network sockets.

This module mainly consists of the CSocket class but also provides free functions to manage a socket. The problem is that socket handling isn't very good portable. There is different behavior on the supported platforms Unix, MacOS and Microsoft Windows. The CSocket class atempts to be consistent portable on all three platforms by using common behavior or by emulating missing functions on a platform.

Specification for CSocket

The class encapsulates and manages one raw socket file descriptor. The file descriptor of a valid socket object cannot be changed but the object with its immutable file descriptor can be moved and assigned to another socket object. Copying a socket object isn't supported because having two objects with the same file descriptor may be very error prone in particular with multithreading. Effort has been taken to do not cache any socket information outside the socket file descriptor. Nearly all socket informations are direct set and get to/from the operating system with the file descriptor. The socket file descriptor is always valid except on an empty socket object.

empty socket object

An empty socket object can be instantiated with the default constructor, e.g. CSocket sockObj;. It is a valid object and should be destructed. When moving a socket object, the left over source object is also empty. An empty socket object has an INVALID_SOCKET defined and no valid content. It throws an exception if using most of its Setter and Getter. Moving and assigning it is possible. You can test for an empty socket by looking for an INVALID_SOCKET, e.g.

CSocket sockObj; // or CSocket_basic sockObj;
if (static_cast<SOCKET>(sockObj) != INVALID_SOCKET) {
    in_port_t port = sockObj.get_port(); }

protocol family, address family

This SDK handles network connections IP Version - Independent so that a protocoll family (PF_INET6, PF_INET, PF_UNIX) or address family (AF_INET6, AF_INET, AF_UNIX) is never used on the SDKs Application Programming Interface. IP Version is managed by the operating system.

socket type

Only SOCK_STREAM and SOCK_DGRAM is supported. Any other type throws an exception.

options SO_REUSEADDR and SO_EXCLUSIVEADDRUSE

I don't set the option to immediately reuse an address and I always set the option SO_EXCLUSIVEADDRUSE on Microsoft Windows. For more details of this have a look at Socket option "reuse address".

References

• RFC 3493 - Basic Socket Interface Extensions for IPv6
• RFC 3542 - Advanced Sockets Application Program Interface (API) for IPv6

Function Documentation

getsockname()

int UPnPsdk::anonymous_namespace{socket.cpp}::getsockname	(	SOCKET	a_sockfd,
		sockaddr *	a_addr,
		socklen_t *	a_addrlen
	)

Wrapper for the ::getsockname() system function.

The system function ::getsockname() behaves different on different platforms in particular with error handling on Microsoft Windows. This function provides a portable version. The calling options are the same as documented for the system function.

Definition at line 37 of file socket.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_sockfd()

SOCKET UPnPsdk::anonymous_namespace{socket.cpp}::get_sockfd	(	sa_family_t	a_pf_family,
		int	a_socktype
	)

Get a socket file descriptor from the operating system.

Get a socket file descriptor and set its default options as specified.

Definition at line 82 of file socket.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

init_winsock

const CWSAStartup UPnPsdk::anonymous_namespace{global.cpp}::init_winsock

This object initialize and cleanup the Microsoft Windows Socket subsystem.

Definition at line 119 of file global.cpp.