Default timeout handler. Fixed spelling.

doc/book/net.tex

@@ -685,7 +685,7 @@ information, please read the class documentation for
 
 
 % ============================================================================
-\section{Handling time-outs}
+\section{Handling timeouts}
 
 Unexpected errors can occur while messaging services are performing
 operations and waiting a response from the server (eg. server stops
@@ -705,18 +705,18 @@ class timeoutHandler : public object
 {
    /** Called to test if the time limit has been reached.
      *
-     * @return true if the time-out delay is elapsed
+     * @return true if the timeout delay is elapsed
      */
    virtual const bool isTimeOut() = 0;
 
-   /** Called to reset the time-out counter.
+   /** Called to reset the timeout counter.
      */
    virtual void resetTimeOut() = 0;
 
    /** Called when the time limit has been reached (when
      * isTimeOut() returned true).
      *
-     * @return true to continue (and reset the time-out)
+     * @return true to continue (and reset the timeout)
      * or false to cancel the current operation
      */
    virtual const bool handleTimeOut() = 0;
@@ -729,25 +729,35 @@ then {\vcode handleTimeout()} is called. If the {\vcode handleTimeout()}
 function returns {\vcode false}, the operation is cancelled and
 an {\vcode operation\_timed\_out} exception is thrown. Else, if
 {\vcode handleTimeout()} returns true, the operation continues and the
-time-out count is reset.
+timeout counter is reset.
 The function {\vcode resetTimeout()} is called each time data has
-been received from the server to reset time-out delay.
+been received from the server to reset the timeout delay.
 
-The following example shows how to implement a simple time-out handler:
+When using a service, a default timeout handler is set: if an operation
+is blocked for more than 30 seconds (ie. network link is down and no data
+was received since 30 seconds), an {\vcode operation\_timed\_out} exception
+is thrown.
 
-\begin{lstlisting}[caption={Implementing a simple time-out handler}]
+The following example shows how to implement a simple timeout handler:
+
+\begin{lstlisting}[caption={Implementing a simple timeout handler}]
 class myTimeoutHandler : public vmime::net::timeoutHandler
 {
 public:
 
+   myTimeoutHandler()
+   {
+      m_startTime = time(NULL);
+   }
+
    const bool isTimeOut()
    {
-      return (getTime() >= m_last + 30);  // 30 seconds time-out
+      return (time(NULL) >= m_startTime + 30);  // 30 seconds timeout
    }
 
    void resetTimeOut()
    {
-      m_last = getTime();
+      m_startTime = time(NULL);
    }
 
    const bool handleTimeOut()
@@ -764,19 +774,14 @@ public:
 
 private:
 
-   const unsigned int getTime() const
-   {
-      return vmime::platform::getHandler()->getUnixTime();
-   }
-
-   unsigned int m_last;
+   time_t m_startTime;
 };
 \end{lstlisting}
 
-To make the service use your time-out handler, you need to write a factory
+To make the service use your timeout handler, you need to write a factory
 class, to allow the service to create instances of the handler class. This
 is required because the service can use several connections to the server
-simultaneously, and each connection needs its own time-out handler.
+simultaneously, and each connection needs its own timeout handler.
 
 \begin{lstlisting}
 class myTimeoutHandlerFactory : public vmime::net::timeoutHandlerFactory
@@ -791,7 +796,7 @@ public:
 \end{lstlisting}
 
 Then, call the {\vcode setTimeoutHandlerFactory()} method on the service object
-to set the time-out handler factory to use during the session:
+to set the timeout handler factory to use during the session:
 
 \begin{lstlisting}
 theService->setTimeoutHandlerFactory(vmime::make_shared <myTimeoutHandlerFactory>());

src/vmime/net/defaultTimeoutHandler.cpp

@@ -0,0 +1,78 @@
+//
+// VMime library (http://www.vmime.org)
+// Copyright (C) 2002-2014 Vincent Richard <vincent@vmime.org>
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation; either version 3 of
+// the License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this program; if not, write to the Free Software Foundation, Inc.,
+// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+//
+// Linking this library statically or dynamically with other modules is making
+// a combined work based on this library.  Thus, the terms and conditions of
+// the GNU General Public License cover the whole combination.
+//
+
+#include "vmime/config.hpp"
+
+
+#if VMIME_HAVE_MESSAGING_FEATURES
+
+
+#include "vmime/net/defaultTimeoutHandler.hpp"
+
+
+namespace vmime {
+namespace net {
+
+
+defaultTimeoutHandler::defaultTimeoutHandler()
+{
+	m_startTime = time(NULL);
+}
+
+
+defaultTimeoutHandler::~defaultTimeoutHandler()
+{
+}
+
+
+bool defaultTimeoutHandler::isTimeOut()
+{
+	return time(NULL) - m_startTime >= 30;
+}
+
+
+void defaultTimeoutHandler::resetTimeOut()
+{
+	m_startTime = time(NULL);
+}
+
+
+bool defaultTimeoutHandler::handleTimeOut()
+{
+	return false;
+}
+
+
+
+
+shared_ptr <timeoutHandler> defaultTimeoutHandlerFactory::create()
+{
+	return make_shared <defaultTimeoutHandler>();
+}
+
+
+} // net
+} // vmime
+
+
+#endif // VMIME_HAVE_MESSAGING_FEATURES

src/vmime/net/defaultTimeoutHandler.hpp

@@ -0,0 +1,82 @@
+//
+// VMime library (http://www.vmime.org)
+// Copyright (C) 2002-2014 Vincent Richard <vincent@vmime.org>
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License as
+// published by the Free Software Foundation; either version 3 of
+// the License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this program; if not, write to the Free Software Foundation, Inc.,
+// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+//
+// Linking this library statically or dynamically with other modules is making
+// a combined work based on this library.  Thus, the terms and conditions of
+// the GNU General Public License cover the whole combination.
+//
+
+#ifndef VMIME_NET_DEFAULTTIMEOUTHANDLER_HPP_INCLUDED
+#define VMIME_NET_DEFAULTTIMEOUTHANDLER_HPP_INCLUDED
+
+
+#include "vmime/config.hpp"
+
+
+#if VMIME_HAVE_MESSAGING_FEATURES
+
+
+#include "vmime/net/timeoutHandler.hpp"
+
+#include <ctime>
+
+
+namespace vmime {
+namespace net {
+
+
+/** A default timeout handler for messaging services. The default action
+  * is to throw a exceptions::operation_timed_out exception when an
+  * operation is blocked for more than 30 seconds.
+  */
+
+class VMIME_EXPORT defaultTimeoutHandler : public timeoutHandler
+{
+public:
+
+	defaultTimeoutHandler();
+	~defaultTimeoutHandler();
+
+	bool isTimeOut();
+	void resetTimeOut();
+	bool handleTimeOut();
+
+private:
+
+	time_t m_startTime;
+};
+
+
+/** A class that creates default timeout handlers.
+  */
+
+class defaultTimeoutHandlerFactory : public timeoutHandlerFactory
+{
+public:
+
+	shared_ptr <timeoutHandler> create();
+};
+
+
+} // net
+} // vmime
+
+
+#endif // VMIME_HAVE_MESSAGING_FEATURES
+
+#endif // VMIME_NET_DEFAULTTIMEOUTHANDLER_HPP_INCLUDED

src/vmime/net/service.cpp

@@ -31,6 +31,8 @@
 
 #include "vmime/platform.hpp"
 
+#include "vmime/net/defaultTimeoutHandler.hpp"
+
 #if VMIME_HAVE_SASL_SUPPORT
 	#include "vmime/security/sasl/defaultSASLAuthenticator.hpp"
 #else
@@ -66,6 +68,8 @@ service::service(shared_ptr <session> sess, const serviceInfos& /* infos */,
 #endif // VMIME_HAVE_TLS_SUPPORT
 
 	m_socketFactory = platform::getHandler()->getSocketFactory();
+
+	m_toHandlerFactory = make_shared <defaultTimeoutHandlerFactory>();
 }
 
 

src/vmime/net/service.hpp

@@ -169,8 +169,8 @@ public:
 	shared_ptr <socketFactory> getSocketFactory();
 
 	/** Set the factory used to create timeoutHandler objects for
-	  * this service. By default, no timeout handler is used. Not all
-	  * services support timeout handling.
+	  * this service. By default, the defaultTimeoutHandler class
+	  * is used. Not all services support timeout handling.
 	  *
 	  * @param thf timeoutHandler factory
 	  */

src/vmime/net/timeoutHandler.hpp

@@ -38,7 +38,9 @@ namespace vmime {
 namespace net {
 
 
-/** A class to manage time-out in messaging services.
+/** A class to manage timeouts in messaging services. This can be used
+  * to stop operations that takes too much time to complete (ie. no data
+  * received from the server for a long time if the network link is down).
   */
 
 class VMIME_EXPORT timeoutHandler : public object
@@ -49,18 +51,18 @@ public:
 
 	/** Called to test if the time limit has been reached.
 	  *
-	  * @return true if the time-out delay is elapsed
+	  * @return true if the timeout delay is elapsed
 	  */
 	virtual bool isTimeOut() = 0;
 
-	/** Called to reset the time-out counter.
+	/** Called to reset the timeout counter.
 	  */
 	virtual void resetTimeOut() = 0;
 
 	/** Called when the time limit has been reached (when
 	  * isTimeOut() returned true).
 	  *
-	  * @return true to continue (and reset the time-out)
+	  * @return true to continue (and reset the timeout)
 	  * or false to cancel the current operation
 	  */
 	virtual bool handleTimeOut() = 0;