isc::util::io::SocketSessionReceiver Class Reference

The receiver of socket sessions. More...

#include <socketsession.h>

Inheritance diagram for isc::util::io::SocketSessionReceiver:

Classes
struct	ReceiverImpl

Public Member Functions
	SocketSessionReceiver (int fd)
	The constructor. More...
	~SocketSessionReceiver ()
	The destructor. More...
SocketSession	pop ()
	Receive a socket session from the forwarder. More...

Detailed Description

The receiver of socket sessions.

An object of this class holds a UNIX domain socket for an established connection, receives socket sessions from the remote forwarder, and provides the session to the application in the form of a SocketSession object.

Note that this class is instantiated with an already connected socket; it's not a listening socket that is accepting connection requests from forwarders. It's application's responsibility to create the listening socket, listen on it and accept connections. Once the connection is established, the application would construct a SocketSessionReceiver object with the socket for the newly established connection. This behavior is based on the design decision that the application should decide when it performs (possibly) blocking operations (see Socket session utility for more details).

See the description of Socket session utility for other details of how the session forwarding works.

Definition at line 422 of file socketsession.h.

Constructor & Destructor Documentation

isc::util::io::SocketSessionReceiver::SocketSessionReceiver ( int  fd )

explicit

The constructor.

Exceptions

SocketSessionError	Any error on an operation that is performed on the given socket as part of initialization.
std::bad_alloc	Resource allocation failure

Parameters

fd	A UNIX domain socket for an established connection with a forwarder.

Definition at line 305 of file socketsession.cc.

isc::util::io::SocketSessionReceiver::~SocketSessionReceiver

(

)

The destructor.

The destructor does not close the socket given on construction. It's up to the application what to do with it (note that the application would have to maintain the socket itself for detecting the existence of a new socket session asynchronously).

Definition at line 310 of file socketsession.cc.

Member Function Documentation

SocketSession isc::util::io::SocketSessionReceiver::pop

(

)

Receive a socket session from the forwarder.

This method receives wire-format data (see Socket session utility) for a socket session on the UNIX domain socket, performs some validation on the data, and returns the session information in the form of a SocketSession object.

The returned SocketSession object is valid only until the next time this method is called or until the SocketSessionReceiver object is destroyed.

The caller is responsible for closing the received socket (whose file descriptor is accessible via SocketSession::getSocket()). If the caller copies the returned SocketSession object, it's also responsible for making sure the descriptor is closed at most once. On the other hand, the caller is not responsible for freeing the socket session data (accessible via SocketSession::getData()); the SocketSessionReceiver object will clean it up automatically.

It ensures the following:

• The address family is either AF_INET or AF_INET6
• The address family (sa_family) member of the local and remote end points must be equal to the family parameter
• The socket session data is not empty and does not exceed 65535 bytes. If the validation fails or an unexpected system error happens (including a connection close in the meddle of reception), it throws an SocketSessionError exception. When this happens, it's very unlikely that a subsequent call to this method succeeds, so in reality the application is expected to destruct it and close the socket in such a case.

Exceptions

SocketSessionError	Invalid data is received or a system error on socket operation happens.
std::bad_alloc	Resource allocation failure

Returns

A SocketSession object corresponding to the extracted socket session.

Definition at line 347 of file socketsession.cc.

References isc::util::io::SocketSessionReceiver::ReceiverImpl::data_buf_, isc::util::io::SocketSessionReceiver::ReceiverImpl::fd_, isc::util::io::FD_SYSTEM_ERROR, isc::util::io::SocketSessionReceiver::ReceiverImpl::header_buf_, isc_throw, isc::util::InputBuffer::readData(), isc::util::InputBuffer::readUint16(), isc::util::InputBuffer::readUint32(), isc::util::io::recv_fd(), isc::util::io::SocketSessionReceiver::ReceiverImpl::sa_local_, isc::util::io::SocketSessionReceiver::ReceiverImpl::sa_remote_, isc::util::io::SocketSessionReceiver::ReceiverImpl::ss_local_, isc::util::io::SocketSessionReceiver::ReceiverImpl::ss_remote_, and isc::Exception::what().

Here is the call graph for this function:

---

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

• socketsession.h
• socketsession.cc