The Handle Hierarchy

---

Detailed Description

The senf::FileHandle class is the base of a hierarchy of socket handle classes (realized as templates). These classes provide an interface to the complete socket API. While going down the inheritance hierarchy, the interface will be more and more complete.

The most complete interface is provided by senf::ProtocolClientSocketHandle and senf::ProtocolServerSocketHandle. The template Arguments specifies the Protocol class of the underlying socket type. These are the only classes having public constructors and are therefore the only classes, which may be created by the library user. You will normally use these classes by naming a specific socket typedef (e.g. senf::TCPv4ClientSocketHandle).

However, to aid writing flexible and generic code, the socket library provides the senf::ClientSocketHandle and senf::ServerSocketHandle class templates. These templates implement a family of closely related classes based on the specification of the socket policy. This policy specification may be incomplete (see below). Instances of senf::ClientSocketHandle/senfServerSocketHandle can be assigned and converted to different ClientSocketHandle/ServerSocketHandle types as long as the policy specifications are compatible.

Attention:

It is very important, to (almost) always pass the socket handle by value. The socket handle is a very lightweight class and designed to be used like an ordinary built-in type. This is very important in combination with the policy interface.

Note:

The FileHandle hierarchy below the SocketHandle template is not meant to be user extensible. To add new socket types, you should introduce new protocol and/or policy classes, the SocketHandle classes should not be changed.

Classes
class	senf::ClientSocketHandle< SPolicy >
	Generic SocketHandle with client interface. More...
class	senf::FileHandle
	Basic file handle wrapper. More...
class	senf::ProtocolClientSocketHandle< SocketProtocol >
	Protocol specific socket handle (client interface). More...
class	senf::ProtocolServerSocketHandle< SocketProtocol >
	Protocol specific socket handle (server interface). More...
class	senf::ServerSocketHandle< SPolicy >
	Generic SocketHandle with server interface. More...
class	senf::SocketHandle< SPolicy >
	basic SocketHandle supporting protocol and policy abstraction More...
Functions
int	senf::FileHandle::retrieve_filehandle (FileHandle handle)
	Adapt FileHandle to senf::scheduler.
template<class SPolicy >
std::ostream &	senf::SocketHandle::operator<< (std::ostream &os, SocketHandle< SPolicy > handle)
	Write stream status dump to output stream.
template<class Target , class Source >
Target	senf::SocketHandle::static_socket_cast (Source handle)
	static socket (down-)cast
template<class Target , class Source >
Target	senf::SocketHandle::dynamic_socket_cast (Source handle)
	dynamic socket (down-)cast
template<class Target , class Source >
bool	senf::SocketHandle::check_socket_cast (Source handle)
	dynamically check cast validity

---

Function Documentation

template<class Target , class Source >

bool
check_socket_cast	(	Source	handle	)

dynamically check cast validity

This function will check, whether the given cast is valid. This is the same as checking, that dynamic_socket_cast does not throw.

This member is needed, since there is no 'null' SocketHandle (comparable to a null pointer) which could be returned by a non-throwing variant of dynamic_socket_cast.

template<class Target , class Source >

Target
dynamic_socket_cast	(	Source	handle	)

dynamic socket (down-)cast

This function is like dynamic_cast but for socket handles. It is a runtime typechecked version of static_socket_cast.

Exceptions:

std::bad_cast

You have tried to perform an invalid down- or crosscast.

template<class SPolicy >

std::ostream &
operator<<	(	std::ostream &	os,
		SocketHandle< SPolicy >	handle	)

Write stream status dump to output stream.

Write senf::SocketHandle::dumpState() to os

int
retrieve_filehandle	(	FileHandle	handle	)

Adapt FileHandle to senf::scheduler.

For internal use only.

This function will be called by the Scheduler to retrieve the file descriptor of the FileHandle.

template<class Target , class Source >

Target
static_socket_cast	(	Source	handle	)

static socket (down-)cast

This function is like static_cast but for socket handles. It allows to downcast any FileHandle to any SocketHandle (and its derived types). static_socket_cast will not check the validity of the cast, it will assume, that the cast is valid.

The function will however check, that the cast is possible. Casting between (at compile time) known incompatible types (like casting a SocketHandle with a communication policy of ConnectedCommunicationPolicy to a SocketHandle with UnconnectedCommunicationPolicy will fail at compile time).

Warning:

If the type you cast to is not really a compatible socket handle type you will get undefined behavior, probably your program will crash (You will get an assertion in debug builds).