libt2n: (gerd) more documentation-polishing

[libt2n] / src / server.hxx

diff --git a/src/server.hxx b/src/server.hxx
index 7e496d9..684cee8 100644 (file)
--- a/src/server.hxx
+++ b/src/server.hxx
@@ -22,6 +22,10 @@
 #include <iostream>
 #include <string>
 #include <map>
+#include <vector>
+#include <list>
+
+#include <boost/function.hpp>
 
 #include "connection.hxx"
 #include "types.hxx"
@@ -32,44 +36,50 @@ namespace libt2n
 class server;
 
 /**
-    Basic connection class
+    @brief connection on a server
+
+    on a server every connection to a client is represented as server_connection.
+    a server_connection is abstract, derived classes like socket_server_connection are used.
 */
 class server_connection : public connection
 {
+    friend class server;
+
     private:
         int timeout;
         int last_action_time;
         unsigned int connection_id;
 
-    protected:
-        server_connection(int _timeout)
-            : connection()
-        {
-            set_timeout(_timeout);
-            reset_timeout();
-            connection_id=0;
-            my_server=0;
-        }
+        void set_server(server* _my_server)
+            { my_server=_my_server; }
+
+        void set_id(unsigned int _connection_id)
+            { connection_id=_connection_id; }
 
+    protected:
         server *my_server;
 
+        server_connection(int _timeout);
+
+        std::ostream* get_logstream(log_level_values level);
+
     public:
         void check_timeout();
         void reset_timeout();
         void set_timeout(int _timeout)
             { timeout=_timeout; }
 
-        void set_server(server* _my_server)
-            { my_server=_my_server; }
-
-        void set_id(unsigned int _connection_id)
-            { connection_id=_connection_id; }
+        /// get the id of this connection within the server object
         unsigned int get_id()
             { return connection_id; }
+
+        void add_callback(callback_event_type event, const boost::function<void ()>& func);
 };
 
 /**
-    Basic server class
+    @brief server base class
+
+    constitutes a server. is abstract, use derived classes like socket_server.
 */
 class server
 {
@@ -78,48 +88,63 @@ class server
         log_level_values log_level;
         std::ostream *logstream;
 
+        /// vector initialized for all callback-types, all elements in each list will be called
+        std::vector<std::list<boost::function<void (unsigned int)> > > callbacks;
+
         unsigned int next_id;
 
     protected:
         std::map<unsigned int, server_connection*> connections;
 
-        server()
-        {
-            set_default_timeout(30);
-            set_logging(NULL,none);
-            next_id=1;
-        }
+        server();
+
+        virtual bool fill_connection_buffers(void)=0;
 
         int add_connection(server_connection* newconn);
 
+        void do_callbacks(callback_event_type event, unsigned int conn_id);
+
     public:
         virtual ~server();
 
+        /// set the default timeout for new client connections
         void set_default_timeout(int _default_timeout)
             { default_timeout=_default_timeout; }
+
+        /// get the current default timeout for client connections
         int get_default_timeout(void)
             { return default_timeout; }
 
-        void set_logging(std::ostream *_logstream, log_level_values _log_level)
-        {
-            log_level=_log_level;
-            logstream=_logstream;
-        }
+        void set_logging(std::ostream *_logstream, log_level_values _log_level);
 
         server_connection* get_connection(unsigned int conn_id);
 
-        virtual void fill_buffer(long long usec_timeout=-1)=0;
+        void add_callback(callback_event_type event, const boost::function<void (unsigned int)>& func);
+
+        /** @brief look for new data and store it in the local buffer
+            @param usec_timeout wait until new data is found, max timeout usecs.
+                  -1: wait endless
+                   0: return instantly
+            @param usec_timeout_remaining if non-NULL the function will write the
+                  not used time to the given target
+            @retval true if new data was found (does not mean that the received data 
+                    is a complete packet though)
+        */
+        virtual bool fill_buffer(long long usec_timeout=-1, long long* usec_timeout_remaining=NULL)=0;
+
         void cleanup();
 
+        /** @brief get a complete data packet from any client. The packet is removed from the
+                   connection buffer.
+            @param[out] data the data package
+            @retval true if packet found
+        */
         bool get_packet(std::string& data)
             { unsigned int x; return get_packet(data,x); }
-        bool get_packet(std::string& data, unsigned int& conn_id);
 
-        virtual void fill_connection_buffers(void)=0;
+        bool get_packet(std::string& data, unsigned int& conn_id);
 
-        void log(log_level_values level, const std::string& message)
-            { log(level,message.c_str()); }
-        void log(log_level_values level, const char* message);
+        std::ostream* get_logstream(log_level_values level);
 };
 
 }