Manages a TCP/IP connection between two entities where one is a server and the other one is a client. More...

#include <TCPConnection.hpp>

Inherits enable_shared_from_this< TCPConnection >.

Public Types
typedef boost::shared_ptr< TCPConnection >	Ptr

typedef boost::shared_ptr< TCPConnection const >	ConstPtr

Public Member Functions
	~TCPConnection ()
	Destructor. Cleanly closes the socket. More...

boost::asio::ip::tcp::socket &	socket ()
	Gives a reference to the internal socket. More...

const boost::asio::ip::tcp::socket &	socket () const
	Gives a constant referemce to the internal socket. More...

template<typename HANDLER >
void	send (cf3::common::XML::SignalFrame &args, HANDLER callback_function)
	Sends a message to the remote entity. The message is sent asynchronously and the function returns directly, before the data is actually send. Once the sending is finished, the `callback_function` is called with error code. More...

template<typename HANDLER >
void	read (cf3::common::XML::SignalFrame &args, HANDLER callback_function)
	Initiates an asynchronous reading from the remote entity. The function returns directly. More...

void	disconnect ()
	Disconnects the socket from the remote entity. More...

void	set_error_handler (boost::weak_ptr< ErrorHandler > handler)

Static Public Member Functions
static Ptr	create (boost::asio::io_service &ios)
	Creates a `TCPConnection` instance. More...

Private Types
enum	{ HEADER_LENGTH = 8 }
	Nameless enum for header length. More...

Private Member Functions
template<typename HANDLER >
void	callback_header_read (cf3::common::XML::SignalFrame &args, const boost::system::error_code &error, boost::tuple< HANDLER > functions)
	Function called when a frame header has been read, successfully or not. This function allocates the frame data buffer depending on the header received. If reading has failed or header is not valid, the callback function is called with appropriate error code. More...

template<typename HANDLER >
void	callback_data_read (common::XML::SignalFrame &args, const boost::system::error_code &error, boost::tuple< HANDLER > functions)
	Function called when the frame data has been read. More...

	TCPConnection (boost::asio::io_service &io_service)
	Constructor. More...

void	prepare_write_buffers (common::XML::SignalFrame &args, std::vector< boost::asio::const_buffer > &buffers)
	Builds the data to be sent on the network. More...

void	process_header (boost::system::error_code &error)
	Processes a frame header. Tries to cast the header to an `unsigned` `int`. On success, allocates the data buffer to this size. More...

void	parse_frame_data (common::XML::SignalFrame &args, boost::system::error_code &error)
	Parses frame data from string to XML. More...

void	notify_error (const std::string &message) const
	Notifies an error if an error handler has been set. More...

Private Attributes
boost::asio::ip::tcp::socket	m_socket
	Network socket. More...

std::string	m_outgoing_data
	Buffer for outgoing data. More...

std::string	m_outgoing_header
	Buffer for outgoing header. More...

char	m_incoming_header [HEADER_LENGTH]
	Buffer the receiving header. More...

unsigned int	m_incoming_data_size
	Size of the receiving buffer. More...

char *	m_incoming_data

boost::weak_ptr< ErrorHandler >	m_error_handler
	Weak pointer to the error handler. More...

Detailed Description

Manages a TCP/IP connection between two entities where one is a server and the other one is a client.

This class is intented to be used in an asynchronous network architecture. Therefore, a Connection object cannot live outside of a shared pointer because a such object has to maintain asynchronous operations. One cannot predict when all of those operations will be completed; using a shared pointer garantees the connection stays alive until all operations are done. Use static function create() to create a Connection object.

A TCP/IP connection is based on an I/O service that handles the asynchronous operations and calls an appropriate function when one of those is completed.

Frames handled by this class have two main parts:

A size-fixed header (8 bytes): contains the size in bytes of the frame data.
Frame data: actual data that is sent, in XML format.

The header is completely tansparent to the calling code and is used as a safeguard to check that all data has arrived and allocate the correct buffer for the reading process.

This class can be used in both client and server applications. However, an additional step is needed on the server-side: open a network connection and start accepting new clients connections.

Most interesting method provided by this class are obviously read() and send(). Both take the same parameters:
a non-const reference to a SignalFrame object. read() uses it as a buffer to which read data will be written. For send(), it contains the data to send (the reference is non-const because SignalFrame::flush_maps() is called before converting the XML to string).
the callback function which will be called when asynchronous operations finishes (on succes or failure).

The callback function can be created using Boost.Bind. Developers are free on the choice of the paramaters to give to this callback function, but have to handle those parameters by themselves. However, both read and send methods require one placeholder of type boost::system::error_code to store the error code. The placeholder value is given by the network layer. Examples:
call read with a callback function that only takes the error code:
connection->read( m_read_buffer, // SignalFrame object. Has to live until the end of the read!

boost::bind( &MyClass::callback_read, // pointer to callback function

this, // object on which to call the function

boost::asio::placeholders::error ) // placeholder for error code

);

// definition of the callback function

void MyClass::callback_read( const boost::system::error_code error )

{

if ( error )

{

// operation failed: m_read_buffer was not modified

{

else

{

// operation succeeded: m_read_buffer contains the parsed XML data

{

}
call read with a callback function that takes the error code and a Connection shared pointer (i.e. a multi-client server application that wants to know which client is speaking):
connection->read( m_read_buffer, // SignalFrame object. Has to live until the end of the read!

boost::bind( &MyClass::callback_read, // pointer to callback function

this, // object on which to call the function

connection, // 1st parameter for the callback function

boost::asio::placeholders::error ) // placeholder for error code

);

// definition of the callback function

void MyClass::callback_read( Connection::Ptr conn, const boost::system::error_code error )

{

if ( error )

{

// operation failed: m_read_buffer was not modified

{

else

{

// operation succeeded: m_read_buffer contains the parse XML data

{

}

Similar codes can be applied to send function.

The internal socket can be retrieve by calling socket(). Developer can set an error handler by calling set_error_handler().

Warning: Due to template code, a lot of Boost headers are included by this file, which might increase the compilation time. Please consider only including this file in a limited number of CPP files (typically, one per application is sufficient).

See also: ErrorHandler

Author: Quentin Gasper

Definition at line 143 of file TCPConnection.hpp.

Member Typedef Documentation

typedef boost::shared_ptr<TCPConnection const> ConstPtr

Definition at line 150 of file TCPConnection.hpp.

typedef boost::shared_ptr<TCPConnection> Ptr

Definition at line 149 of file TCPConnection.hpp.

Member Enumeration Documentation

anonymous enum

private

Nameless enum for header length.

Enumerator
HEADER_LENGTH

Definition at line 336 of file TCPConnection.hpp.

Constructor & Destructor Documentation

~TCPConnection ( )

Destructor. Cleanly closes the socket.

Definition at line 50 of file TCPConnection.cpp.

TCPConnection ( boost::asio::io_service & io_service )

private

Constructor.

Parameters

io_service The I/O service the connection will be based on.

Definition at line 40 of file TCPConnection.cpp.

Member Function Documentation

void callback_data_read	(	common::XML::SignalFrame &	args,
		const boost::system::error_code &	error,
		boost::tuple< HANDLER >	functions
	)

inlineprivate

Function called when the frame data has been read.

Parameters

error	Describes the error that occured, if any.
conn	The connection
error	Error code, if any.
functions	Callback function

Definition at line 285 of file TCPConnection.hpp.

void callback_header_read	(	cf3::common::XML::SignalFrame &	args,
		const boost::system::error_code &	error,
		boost::tuple< HANDLER >	functions
	)

inlineprivate

Function called when a frame header has been read, successfully or not. This function allocates the frame data buffer depending on the header received. If reading has failed or header is not valid, the callback function is called with appropriate error code.

Parameters

error	Describes the error that occured, if any.
conn	The connection
error	Error code, if any.
functions	Callback function

Definition at line 244 of file TCPConnection.hpp.

TCPConnection::Ptr create ( boost::asio::io_service & ios )

static

Creates a TCPConnection instance.

Parameters

io_service The I/O service the new connection will be based on.

Returns: Returns the created instance as a boost share pointer.

Definition at line 33 of file TCPConnection.cpp.

void disconnect ( )

Disconnects the socket from the remote entity.

Definition at line 150 of file TCPConnection.cpp.

void notify_error ( const std::string & message ) const

private

Notifies an error if an error handler has been set.

Parameters

message Error message.

Definition at line 179 of file TCPConnection.cpp.

void parse_frame_data	(	common::XML::SignalFrame &	args,
		boost::system::error_code &	error
	)

private

Parses frame data from string to XML.

Parameters

args	Object where the parsed XML will be written.

Definition at line 121 of file TCPConnection.cpp.

void prepare_write_buffers	(	common::XML::SignalFrame &	args,
		std::vector< boost::asio::const_buffer > &	buffers
	)

private

Builds the data to be sent on the network.

Parameters

args	XML data. `flush_maps()` is called before converting to string.
buffer	Data buffer. First item is the header and second item is the frame data. Vector is cleared before first use.

Definition at line 58 of file TCPConnection.cpp.

void process_header ( boost::system::error_code & error )

private

Processes a frame header. Tries to cast the header to an unsigned int. On success, allocates the data buffer to this size.

Definition at line 82 of file TCPConnection.cpp.

void read	(	cf3::common::XML::SignalFrame &	args,
		HANDLER	callback_function
	)

inline

Initiates an asynchronous reading from the remote entity. The function returns directly.

Parameters

args	The buffer used to write recieved data.
callback_function	The callback function to call when asynchronous operation is finished. See this class description for further information about callback functions.

Warning: Calling code has to garantee that the object referenced by args remains alive until the end of the asynchronous operation.

Definition at line 209 of file TCPConnection.hpp.

void send	(	cf3::common::XML::SignalFrame &	args,
		HANDLER	callback_function
	)

inline

Sends a message to the remote entity. The message is sent asynchronously and the function returns directly, before the data is actually send. Once the sending is finished, the callback_function is called with error code.

Parameters

data	The XML data to send. Must be valid.
callback_function	The callback function to call when asynchronous operation is finished. See this class description for further information about callback functions.

Note

this methods calls flush_maps() on args
the XML data is converted to string and stored in an internal buffer. The calling can the freely reuse the object reference by args derectly after this method returns.

Definition at line 191 of file TCPConnection.hpp.

void set_error_handler ( boost::weak_ptr< ErrorHandler > handler )

Sets an error handler.

Parameters

handler Error handler to set. Can be expired.

Definition at line 172 of file TCPConnection.cpp.

boost::asio::ip::tcp::socket& socket ( )

inline

Gives a reference to the internal socket.

Returns: Returns a reference to the internal socket.

Definition at line 165 of file TCPConnection.hpp.

const boost::asio::ip::tcp::socket& socket ( ) const

inline

Gives a constant referemce to the internal socket.

Returns: Returns a constant reference to the internal socket.

Definition at line 172 of file TCPConnection.hpp.

Member Data Documentation

boost::weak_ptr<ErrorHandler> m_error_handler

private

Weak pointer to the error handler.

Definition at line 350 of file TCPConnection.hpp.

char* m_incoming_data

private

Receiving buffer.

Warning: This buffer does NOT end by '\0'. Its size is given by m_incoming_data_size.

Definition at line 347 of file TCPConnection.hpp.

unsigned int m_incoming_data_size

private

Size of the receiving buffer.

Definition at line 342 of file TCPConnection.hpp.

char m_incoming_header[HEADER_LENGTH]

private

Buffer the receiving header.

Definition at line 339 of file TCPConnection.hpp.

std::string m_outgoing_data

private

Buffer for outgoing data.

Definition at line 330 of file TCPConnection.hpp.

std::string m_outgoing_header

private

Buffer for outgoing header.

Definition at line 333 of file TCPConnection.hpp.

boost::asio::ip::tcp::socket m_socket

private

Network socket.

Definition at line 327 of file TCPConnection.hpp.

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

cf3/ui/network/TCPConnection.hpp
cf3/ui/network/TCPConnection.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation