libt2n: (gerd) more documentation-polishing

[libt2n] / src / client_wrapper.hxx

diff --git a/src/client_wrapper.hxx b/src/client_wrapper.hxx
index ebc9e25..cb333db 100644 (file)
--- a/src/client_wrapper.hxx
+++ b/src/client_wrapper.hxx
@@ -36,6 +36,12 @@
 namespace libt2n
 {
 
+/** @brief provide access to client_connection singletons and call-handling function
+
+    This is an abstact base class for use with T2nSingletonWrapper. It provides access
+    to the singleton-client_connection and offers a handle-method which is used for
+    every call to a method on a t2n-server.
+*/
 class ConnectionWrapper
 {
     private:
@@ -57,8 +63,26 @@ class ConnectionWrapper
         virtual ~ConnectionWrapper()
             { }
 
+        /** @brief return active connection, create new one if not existing
+
+            Return a pointer to an active client_connection. Use detail-data
+            stored within the derived class to create a new connection if needed,
+            otherwise return an alredy active connection. The derived class has
+            to take care of destroying the connection when not needed anymore.
+        */
         virtual client_connection* get_connection()=0;
 
+        /** @brief this function is called on every execution of a method on a server
+
+            @param stubBase pointer to the command_client executing the call
+            @param f boost::function object containing the method to call and all parameters
+            @retval true if the call was successful and the original return-value of the called function can be used
+                    false if T2nSingletonWrapper has to create a return-value with the default-constructor
+
+            T2nSingletonWrapper will call this function on every execution of a server-side
+            method. This version will just call the function without any special treatment.
+            You can overload this function to implement different error handling strategies.
+        */
         virtual bool handle(command_client* stubBase, boost::function< void() > f)
         {
             f();
@@ -77,7 +101,7 @@ class ConnectionWrapper
         void set_hello_timeout_usec(long long _hello_timeout_usec)
             { hello_timeout_usec=_hello_timeout_usec; }
 
-        void set_logging(std::ostream *_logstream, log_level_values _log_level);
+        virtual void set_logging(std::ostream *_logstream, log_level_values _log_level);
 
         std::ostream* get_logstream(log_level_values level);
 };
@@ -139,6 +163,20 @@ class T2nSingletonWrapperMessages
         static const char* NotInitializedMessage;
 };
 
+/** @brief wrap calls to server-side-functions with different error-handling strategies
+
+    Template class to access a process-wide singleton server-connection and to wrap all
+    calls using this connection with an error-handling strategy (e.g. to reconnect when
+    the connection broke). The source looks very complicated due to heavy use of templates,
+    look at the 3rd codegen example to see how to use it.
+
+    @par Example
+    Calling remote methods is usually done via t2n_exec, this saves you from always
+    specifying which T2nSingletonWrapper-template to use when calling T2nSingletonWrapper::exec
+    @code
+    t2n_exec(&cmd_group_t2nexample_client::testfunc)("the answer is %d",42)
+    @endcode
+*/
 template< class Client >
 class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 {
@@ -148,6 +186,7 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
         static std::auto_ptr<T2nSingletonWrapper> SingletonObject;
         static std::auto_ptr<ConnectionWrapper> WrappedConnection;
 
+        /// @cond
         // create a prep-method for each possible number of parameters
 #define _GEN_ARG(z,n,d) Arg ## n arg ##n
 #define _GEN_PREP(z,n,d) \
@@ -169,6 +208,7 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
 #undef _GEN_PREP
 #undef _GEN_ARG
+        /// @endcond
 
         T2nSingletonWrapper(std::auto_ptr<Client> stub)
         {
@@ -210,6 +250,9 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
     public:
 
+        /** @brief tell the wrapper which connection to use
+            @param wrappedConnection the connection to establish when needed
+        */
         static void set_connection(std::auto_ptr<ConnectionWrapper> wrappedConnection)
         {
             WrappedConnection=wrappedConnection;
@@ -218,15 +261,19 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
             if (SingletonObject.get() != NULL)
                 SingletonObject.reset();
         }
+
+        /// return a pointer to the ConnectionWrapper currently in use
         static ConnectionWrapper* get_connection_wrapper(void)
             { return WrappedConnection.get(); }
 
+        /// manually establish the connection without actually executing a call
         static void ensure_singleton_there(void)
         {
             if (SingletonObject.get() == NULL)
                 init();
         }
 
+        /// @cond
         // create an exec-method for each possible number of parameters
 #define _GEN_PLACEHOLDER(z,n,d) BOOST_PP_CAT(_,BOOST_PP_ADD(n,1))
 #define _GEN_EXEC(z,n,d) \
@@ -251,9 +298,11 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
 #undef _GEN_EXEC
 #undef _GEN_PLACEHOLDER
+        /// @endcond
 
 };
 
+/// @cond
 // create an t2n_exec-method for each possible number of parameters
 #define _GEN_EXEC(z,n,d) \
         template< class Client, typename R  BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM_PARAMS(n,typename Arg) > \
@@ -269,6 +318,7 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 
 #undef _GEN_EXEC
 #undef _GEN_PLACEHOLDER
+/// @endcond
 
 }
 #endif