karoo::rock_datagram_message_handler Class Reference

The rock system allows you to create an array of message handlers, using the rock::addHandler() method. More...

#include <rock.h>

Inheritance diagram for karoo::rock_datagram_message_handler:

List of all members.

Public Member Functions
	rock_datagram_message_handler (rock *parent)
rock_datagram_message *	createAckMessage (const rock_datagram_message *msg, uint64_t seq, int32_t port)
	Create a ROCK_ACK_MESSAGE reply.
void	sendAck (rock_datagram_message *reply)
	Send a ROCK_ACK_MESSAGE reply.
void	createAndSendAck (const rock_datagram_message *msg, uint64_t seq, int32_t port)
	Create and send a "normal" ROCK_ACK_MESSAGE reply.
rock_datagram_message *	createReplyMessage (const rock_datagram_message *msg, int32_t port, const text &name, uint32_t type)
	Create a reply message.
void	sendMessage (rock_datagram_message *msg)
	Send a message.
virtual bool	handle (uint32_t message_type, uint64_t seq, int32_t port, const text &name, rock_datagram_message *msg)=0
	This method is called indirectly from the datagram_message::run() method for each incoming datagram.
Protected Attributes
rock *	parent

---

Detailed Description

The rock system allows you to create an array of message handlers, using the rock::addHandler() method.

For each incoming datagram, each handler will be called in order, until one returns TRUE. The default handler always handles the basic rock messages such as ROCK_ACK_MESSAGE and ROCK_HELLO_MESSAGE, but you can extend the protocol by simply adding extra handlers.

---

Member Function Documentation

rock_datagram_message* karoo::rock_datagram_message_handler::createAckMessage	(	const rock_datagram_message *	msg,
		uint64_t	seq,
		int32_t	port
	)

Create a ROCK_ACK_MESSAGE reply.

Parameters:

	msg	the message that you are ACKing
	seq	the sequence number of the message
	port	the port number of the sender

Exceptions:

rock_exception_io

if there is a read error Call this method if you wish to append more than the normal ACK data to the end of the message. If this is the case, then you need to also send the message. e.g. /code rock_datagram_message* reply = createAckMessage(msg, seq, port); sendAck(reply); delete reply; /endcode

void karoo::rock_datagram_message_handler::createAndSendAck	(	const rock_datagram_message *	msg,
		uint64_t	seq,
		int32_t	port
	)

Create and send a "normal" ROCK_ACK_MESSAGE reply.

Its extremely important that you call this as soon as you have parsed the message, so that it gets sent to the peer as quickly as possible, to avoid unnecessary re-sends.

Parameters:

	msg	the message that you are ACKing
	seq	the sequence number of the message
	port	the port number of the sender

Exceptions:

rock_exception_io

if there is a read error

rock_datagram_message* karoo::rock_datagram_message_handler::createReplyMessage	(	const rock_datagram_message *	msg,
		int32_t	port,
		const text &	name,
		uint32_t	type
	)

Create a reply message.

Parameters:

	msg	the message that you are replying to
	port	the port number of the sender
	name	the name of the recipient rock

Exceptions:

rock_exception_io

if there is a read error

virtual bool karoo::rock_datagram_message_handler::handle	(	uint32_t	message_type,
		uint64_t	seq,
		int32_t	port,
		const text &	name,
		rock_datagram_message *	msg
	)			[pure virtual]

This method is called indirectly from the datagram_message::run() method for each incoming datagram.

The datagram_server calls the rock_datagram_factory::create_datagram_message() method to create a datagram_message object. This, being a rock_datagram_message, comes complete with an implementation of the datagram_message::run() method which simply calls rock::handle(). rock::handle() iterates its array of handlers, calling this method, until one handler returns TRUE. Note that the rock::handle() method reads the message_type, sequence number, and port number which puts the pos just after the port number. (Actually, in the case of a ROCK_ACK_MESSAGE, which does not have a port number, it reads just the type and the sequence... but the ROCK_ACK_MESSAGE is handled by the default handler, so application handlers won't receive it in any case.) The only thing it assumes about the protocol is that the message type, an unsigned 32 bit integer, is first in the message. Then there is a 64 bit unsigned integer sequence number, then the sender's port number as a signed 32 bit integer, then the sender rock's name, as a string. What follows is completely up to the implementation.

Parameters:

	message_type	the message type that was read from the message data
	seq	the message's sequence number.
	port	the port number of the sender.
	name	the sender rock's name.
	msg	the message object to be parsed and handled

Returns:

true if this message was handled, or false if this handler is not able to handle it. Note that it is extremely important that you send the ACK as soon as possible, to avoid having the sender resend the message again. E.g. /code case YOUR_MESSAGE_TYPE: { text name; msg->readS(name); parent->createAndSendAck(msg, seq, port); ... followed by your code to handle the message } /endcode

void karoo::rock_datagram_message_handler::sendAck

(

rock_datagram_message *

reply

)

Send a ROCK_ACK_MESSAGE reply.

Parameters:

reply

the ACK message Note it is your responsibility to then delete the reply object.

void karoo::rock_datagram_message_handler::sendMessage

(

rock_datagram_message *

msg

)

Send a message.

Parameters:

msg

the message This sends a message and makes certain that the parent rock's children have an update of the recipient rock's details.

---

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

• rock/rock.h