/* lw-support/src/lib/Net/ServerCallback.h
 *
 *  (c)2005, Laurence Withers. Released under the GNU GPL. See file
 *  COPYING for more information / terms of license.
*/

namespace lw {



/*! \brief Base class for network server callback objects.

This is the callback objected to be used with IOListen when you want to
listen for incoming connections on a new server object. You simply need
to override the accept() function (and possibly the error() function);
everything else is ready to work with any object derived from the
NetServer class.

*/
class EventCallbackNetServer {
public:
    /// Destructor. Does nothing.
    virtual ~EventCallbackNetServer()
    { }



    /*! \brief Called when a new connection is accepted.

    \param client The new connection object.
    \retval true if you want to continue listening.
    \retval false if you want to stop listening.

    This function is called whenever the acceptance process for a new
    socket is complete. This needs to be overridden in derived classes
    to do something with \a client (such as add it to a global ready
    list).

    \note Any exceptions you throw from here will be ignored, and the
        callback will still be called in future for new connections.

    */
    virtual bool accept(IODevice* client) = 0;



    /*! \brief Called when an error is detected.

    \retval true if you want to continue listening.
    \retval false if you want to stop listening.

    This function is called whenever \c epoll detects an error with the
    server socket. The default behaviour is to ignore the error, but you
    might have some more complicated error processing to do if you so
    wish.

    \note Any exceptions you throw from here will be ignored, and the
        callback will still be called in future for further errors.

    \todo Presumably this gets called whenever epoll returns the
        EPOLLERR event; we should therefore find a way to retrieve the
        error from the socket's fd.

    */
    virtual bool error();
};



}