---

SUEGenericDuplexSession Class Reference

Duplex session via a single file descriptor. More...

#include <sue_sess.hpp>

Inheritance diagram for SUEGenericDuplexSession:

[legend]Collaboration diagram for SUEGenericDuplexSession:

[legend]List of all members.

Public Methods
	SUEGenericDuplexSession (int a_timeout=0, const char *a_greeting=0)
	Constructor.
virtual	~SUEGenericDuplexSession ()
	Destructor.
void	SetTimeout (int sec, int usec=0)
	Set timeout.
void	Startup (SUEEventSelector *a_selector, int a_fd, const char *a_greeting=0)
	Start the session.
void	Shutdown ()
	Shut the session down.
void	GracefulShutdown ()
	graceful shutdown
virtual void	HandleNewInput ()=0
	Hook for handling new input.
virtual void	ShutdownHook ()
	Overridable shutdown hook.
virtual void	HandleSessionTimeout ()
	Hook for handling session timeout.
virtual void	HandleReadError ()
	Hook for handling read error.
virtual void	HandleWriteError ()
	Hook for handling write error.
virtual void	HandleRemoteClosing ()
	Hook for handling session end by remote.
Protected Methods
virtual void	FdHandle (bool a_r, bool a_w, bool a_ex)
	callback function for file descriptor events
virtual void	TimeoutHandle ()
	callback function for timeouts
virtual bool	WantRead () const
virtual bool	WantWrite () const
virtual bool	WantExcept () const
Protected Attributes
SUEEventSelector *	the_selector
	Pointer to the SUEEventSelector object used here.
SUEBuffer	inputbuffer
	Reading queue.
SUEBuffer	outputbuffer
	Writing queue.
bool	inputresetstimeout
	Does the received input reset timeout.
bool	outputresetstimeout
	Does the performed output reset timeout.

---

Detailed Description

Duplex session via a single file descriptor.

This class provides an abstract hope-to-be-generic duplex connection via a single file descriptor (e.g., a duplex socket). The class is capable of timing out the session.

All the input/output is made asynchronously and is hidden from the user. You just operate with two protected fields named inputbuffer and outputbuffer. They are both of type SUEBuffer. Chars read from the file descriptor are appended to the end of the inputbuffer. Chars in the outputbuffer are considered as chars to be sent to through the file descriptor.

You must create a child class of this and the child must override at least the HandleNewInput() and HandleRemoteClosing() methods. You might want to override ShutdownHook(), HandleSessionTimeout() and/or HandleReadError() as well.

Use Startup(), Shutdown() and GracefulShutdown() to control the session.

Note:

You can make your objects delete themselves once the session is terminated. In this case, override ShutdownHook() and put the operator delete this; there.

The other option is to close the session by deleting the object. It is possible because Shutdown() is always called from the destructor. But be sure you do NOT delete the object from within ShutdownHook() in this case!

Warning:

And once again, either you delete the object manually, or you let the object delete itself from ShutdownHook(), but not both.

---

Constructor & Destructor Documentation

SUEGenericDuplexSession::SUEGenericDuplexSession (  int    a_timeout = 0, const char *    a_greeting = 0 )

Constructor. Parameters: a_timeout  is the value of the timeout (in seconds) used to close idle sessions. 0 means no timeout. Use SetTimeout() to set timeouts of non-integer seconds. a_greeting  is the message to send to the client at the very start of the session.

virtual SUEGenericDuplexSession::~SUEGenericDuplexSession (    )  [virtual]

Destructor.

---

Member Function Documentation

virtual void SUEGenericDuplexSession::FdHandle (  bool    a_r, bool    a_w, bool    a_ex )  [protected, virtual]

callback function for file descriptor events This function overrides SUEFdHandler::FdHandle(). It then performs read(2) on the socket and then calls the appropriate method depending on the results. Note: Forget this function unless you'd like to reimplement the library. For regular modifying of your object's behaviour, use overriding of HandleNewInput(), HandleSessionTimeout(), HandleRemoteClosing() and HandleReadError(). Implements SUEFdHandler.

void SUEGenericDuplexSession::GracefulShutdown (    )

graceful shutdown Schedule shutdown of the session to the moment when output queue get empty.

virtual void SUEGenericDuplexSession::HandleNewInput (    )  [pure virtual]

Hook for handling new input. This function is called whenever new data is read from the session channel (that is, select(2) told us there is possibility to read, and read(2) got more than zero chars from the session's file descriptor). All the chars are appended to the inputbuffer before this function is called. Implemented in SUETcpClientSession, and SUETcpServerSession.

virtual void SUEGenericDuplexSession::HandleReadError (    )  [inline, virtual]

Hook for handling read error. This function is called when read(2) returns negative value. By default, it calls Shutdown(). Override this method if you need different behaviour (you do need it, don't you?)

virtual void SUEGenericDuplexSession::HandleRemoteClosing (    )  [inline, virtual]

Hook for handling session end by remote. This function is called by the library in case select(2) tells the FD may be read and then read(2) returns 0 bytes. For sockets, it means the remote end has just closed connection. Examples: hellobot.cpp.

virtual void SUEGenericDuplexSession::HandleSessionTimeout (    )  [inline, virtual]

Hook for handling session timeout. This function is called when the session is timed out. By default, it calls Shutdown(). Override this method if you need different behaviour (you do need it, don't you?) Examples: chat.cpp, and hellobot.cpp.

virtual void SUEGenericDuplexSession::HandleWriteError (    )  [inline, virtual]

Hook for handling write error. This function is called when write(2) returns negative value. By default, it calls Shutdown(). Override this method if you need different behaviour (you do need it, don't you?)

void SUEGenericDuplexSession::SetTimeout (  int    sec, int    usec = 0 )

Set timeout. Parameters: sec  is integer seconds usec  is additional microseconds Note: SetTimeout(0,0) will disable the timing-out feature. Setting timeout for an active (registered with the selector) session forces timeout reset.

void SUEGenericDuplexSession::Shutdown (    )

Shut the session down. Calling Shutdown() from within your handlers is the right way to end the session. This function unregisters all handlers at the selector and closes the file descriptor. After that, it calls ShutdownHook() method which can be overriden in a child class. Note: If the session is not started up yet or is already shutted down, Shutdown() silently exits. ShutdownHook() is not called in this case. This allows to call Shutdown() from the destructor of SUEGenericDuplexSession to make sure everything's cleaned up. Examples: hellobot.cpp.

virtual void SUEGenericDuplexSession::ShutdownHook (    )  [inline, virtual]

Overridable shutdown hook. Sometimes we need to notify someone the session's dead. This function is called by Shutdown() method after all the necessary steps of shutting down are done. By default it does nothing, but that can be overriden. You can even delete your object from within this method, it is safe unless you use deletion to initiate the shutdown. Note: If you assume deletion of the object is a regular method of killing your session, be sure to call Shutdown() from within your destructor. Examples: hellobot.cpp.

void SUEGenericDuplexSession::Startup (  SUEEventSelector *    a_selector, int    a_fd, const char *    a_greeting = 0 )

Start the session. This method sets the file descriptor and registers the handlers at the selector. Parameters: a_selector  is the pointer to your SUEEventSelector a_fd  is the file descriptor of your duplex connection a_greeting  if specified, this string is sent to the remote end right after the connection is established Reimplemented in SUEInetDuplexSession.

virtual void SUEGenericDuplexSession::TimeoutHandle (    )  [protected, virtual]

callback function for timeouts Note: Forget this function unless you'd like to reimplement the library. For regular modifying of your object's behaviour, override HandleSessionTimeout(). Implements SUETimeoutHandler.

virtual bool SUEGenericDuplexSession::WantExcept (    )  const [inline, protected, virtual]

In the current version, we don't expect nor handle exceptions Reimplemented from SUEFdHandler.

virtual bool SUEGenericDuplexSession::WantRead (    )  const [inline, protected, virtual]

We're always ready to read everything they sent us Reimplemented from SUEFdHandler.

virtual bool SUEGenericDuplexSession::WantWrite (    )  const [inline, protected, virtual]

Sometimes (when the output queue is not empty) we need to know when to write. Reimplemented from SUEFdHandler.

---

Member Data Documentation

SUEBuffer SUEGenericDuplexSession::inputbuffer [protected]

Reading queue.

bool SUEGenericDuplexSession::inputresetstimeout [protected]

Does the received input reset timeout.

SUEBuffer SUEGenericDuplexSession::outputbuffer [protected]

Writing queue.

bool SUEGenericDuplexSession::outputresetstimeout [protected]

Does the performed output reset timeout.

SUEEventSelector* SUEGenericDuplexSession::the_selector [protected]

Pointer to the SUEEventSelector object used here.

---

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

• sue_sess.hpp

---