#include <FrameEndpoint.h>

Inheritance diagram for FrameEndpoint:

Collaboration diagram for FrameEndpoint:

Public Member Functions
	FrameEndpoint (boost::asio::io_service &a_IOService, boost::asio::ip::tcp::socket &a_TcpSocket, uint8_t a_FrameTypeMask=0xFF)
	The constructor of FrameEndpoint objects. More...

	~FrameEndpoint ()
	The destructor of FrameEndpoint objects. More...

void	ResetFrameFactories (uint8_t a_FrameTypeMask=0xFF)
	Forget all provided frame factory callbacks. More...

void	RegisterFrameFactory (unsigned char a_FrameType, std::function< std::shared_ptr< Frame >(void)> a_FrameFactory)
	Register one subsequent frame factory callback. More...

bool	GetWasStarted () const
	A getter to query whether this frame endpoint entity was already started. More...

void	Start ()
	Start the frame endpoint entity. More...

void	Shutdown ()
	Tear a frame endpoint entity down. More...

void	Close ()
	Close the frame endpoint entity. More...

void	TriggerNextFrame ()
	Trigger delivery of the next incoming frame. More...

bool	SendFrame (const Frame &a_Frame, std::function< void()> a_OnSendDoneCallback=nullptr)
	Enqueue a frame for transmission. More...

void	SetOnFrameCallback (std::function< bool(std::shared_ptr< Frame >)> a_OnFrameCallback)
	Provide the callback method for handling of incoming frames. More...

void	SetOnClosedCallback (std::function< void()> a_OnClosedCallback)
	Provide the callback method for handling of connection aborts. More...

Detailed Description

Class FrameEndpoint.

This is a convenience class to take full control over a provided connected TCP socket in order to receive and transmit used-defined frames. The user has to provide callbacks to be notified on reception of incoming frames and to be notified if errors occur. Thus, this class offers a fully asynchronous interface.

Frame objects representing received frames are created internally. For this purpose, the user has to register frame factory callbacks. These frame factories are selected according to the received stream of bytes and offer a very easy interface to the user. Currently, this frame selection scheme requires that the type of frame can be determined by evaluation of the very first byte of a frame. If this is not possible, e.g., because multiple types of frames exist which differ in "later" bytes, this FrameEndpoint class is not suitable!

Definition at line 65 of file FrameEndpoint.h.

Constructor & Destructor Documentation

FrameEndpoint::FrameEndpoint	(	boost::asio::io_service &	a_IOService,
		boost::asio::ip::tcp::socket &	a_TcpSocket,
		uint8_t	a_FrameTypeMask = `0xFF`
	)

inline

The constructor of FrameEndpoint objects.

All internal members are initialized here. The ownership of the provided TCP socket is transferred, so the user MUST NOT perform any operations on it after registration.

Parameters

a_IOService	the boost IO service object
a_TcpSocket	the connected TCP socket
a_FrameTypeMask	the mask used while looking at the "first byte" of each frame to determine its type

Definition at line 76 of file FrameEndpoint.h.

FrameEndpoint::~FrameEndpoint ( )

inline

The destructor of FrameEndpoint objects.

On destruction, it is assured that the provided TCP socket is closed correctly. No subsequent callbacks are triggered.

Definition at line 93 of file FrameEndpoint.h.

Here is the call graph for this function:

Member Function Documentation

void FrameEndpoint::Close ( )

inline

Close the frame endpoint entity.

Invoking this method will instantly stop reception of incoming and transmission of outgoing frames. Frames pending in the send queue will be lost. No problems arise if this method is called multiple times. Consider calling Shutdown() instead.

Definition at line 181 of file FrameEndpoint.h.

Here is the caller graph for this function:

bool FrameEndpoint::GetWasStarted ( ) const

inline

A getter to query whether this frame endpoint entity was already started.

Return values

true	the frame endpoint is currently running
false	the frame endpoint is currently not running

Returns: Indicates whether this frame endpoint entity was already started

Definition at line 137 of file FrameEndpoint.h.

void FrameEndpoint::RegisterFrameFactory	(	unsigned char	a_FrameType,
		std::function< std::shared_ptr< Frame >(void)>	a_FrameFactory
	)

inline

Register one subsequent frame factory callback.

With each call of this method one subsequent frame factory is registered to the set of active frame factories. Each provided frame factory has to be tagged with a frame type byte. The frame type byte corresponds to the first byte of the serialized frame and must allow a distict mapping to the correct frame type and thus the correct frame factory.

Parameters

a_FrameType	the frame type together with the frame type mask must match to activate the respective frame factory callback
a_FrameFactory	the frame factory callback that is invoked if the frame type matches

Definition at line 123 of file FrameEndpoint.h.

void FrameEndpoint::ResetFrameFactories ( uint8_t a_FrameTypeMask = 0xFF )

inline

Forget all provided frame factory callbacks.

This method is used to clear the list of provided frame factory callbacks. After this, a new and completely different set of frame factory callbacks can be provided together with a changed frame type mask. This allows changing the user-defined protocol regarding a TCP socket for which a different protocol was specified earlier.

Parameters

a_FrameTypeMask the mask used while looking at the "first byte" of each frame to determine its type

Definition at line 108 of file FrameEndpoint.h.

bool FrameEndpoint::SendFrame	(	const Frame &	a_Frame,
		std::function< void()>	a_OnSendDoneCallback = `nullptr`
	)

inline

Enqueue a frame for transmission.

Use this method to enqueue a frame for transmission. The user can select between quasi-synchonous and asynchronous behavior. In the first case, one has to evaluate the return value to check whether a provided frame was accepted or denied due to a full transmission queue. For asynchronous behavior the user has to provide a callback method on a per-packet basis that is called after the frame was successfully transmitted. Currently this callback method is only called on success but never on error, e.g., if the socket is closed.

Parameters

a_Frame	the frame to send
a_OnSendDoneCallback	a callback to be invoked if this frame was sent

Return values

true	the frame was successfully enqueued
false	there was a problem enqueueing the frame

Returns: Indicates whether the frame was successfully enqueued for transmission

Definition at line 238 of file FrameEndpoint.h.

Here is the call graph for this function:

void FrameEndpoint::SetOnClosedCallback ( std::function< void()> a_OnClosedCallback )

inline

Provide the callback method for handling of connection aborts.

The user should provide one callback method to be able to handle error events such as a closed TCP socket.

Parameters

a_OnClosedCallback the callback method that is invoked on error or if the socket was closed

Definition at line 282 of file FrameEndpoint.h.

Here is the call graph for this function:

void FrameEndpoint::SetOnFrameCallback ( std::function< bool(std::shared_ptr< Frame >)> a_OnFrameCallback )

inline

Provide the callback method for handling of incoming frames.

The user should provide one callback method to be able to handle incoming frames. For each incoming frame the callback method is called once.

Parameters

a_OnFrameCallback the callback method that is invoked on reception of incoming frames

Definition at line 272 of file FrameEndpoint.h.

void FrameEndpoint::Shutdown ( )

inline

Tear a frame endpoint entity down.

This method should be called instead of Close() if you want to assure a proper teardown sequence of the provided TCP socket. This assures that all frames enqueued for transmission are delivered before the socket is closed. You SHOULD NOT call Close() anymore, as this is performed internally as soon as the send queue becomes empty. You SHOULD NOT send subsequent frames after calling this method as you'll get no feedback whether the respective frame will be transmitted or not.

Definition at line 172 of file FrameEndpoint.h.

void FrameEndpoint::Start ( )

inline

Start the frame endpoint entity.

The frame endpoint starts reading data from the socket and creates a stream of frame objects according to the provided frame factory callback methods. Frames enqued for transmission are delivered in sequence. Be sure that you DO NOT call this method twice, i.e., on a frame endpoint entity that is already running. This will trigger an assertion.

Definition at line 147 of file FrameEndpoint.h.

Here is the call graph for this function:

void FrameEndpoint::TriggerNextFrame ( )

inline

Trigger delivery of the next incoming frame.

Invoking this method triggers read and delivery of the next incoming frame. This allows an asynchronous processing of frames. For such an asynchronous mode of operation, the provided OnFrameCallback must return the value "false" in order to stop automatic delivery of subsequent frames. This provides unlimited time to consume a frame and stalls the TCP socket, but requires a later call to this method in order to continue receiving the next incoming frame.

Definition at line 200 of file FrameEndpoint.h.

Here is the caller graph for this function:

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

libs/framing/src/FrameEndpoint.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation