Added example and in-code documentation for time out handler.

examples/example6.cpp

@@ -290,6 +290,53 @@ static std::ostream& operator<<(std::ostream& os, const vmime::exception& e)
 }
 
 
+/** Time out handler.
+  * Used to stop the current operation after too much time, or if the user
+  * requested cancellation.
+  */
+class timeoutHandler : public vmime::net::timeoutHandler
+{
+public:
+
+	bool isTimeOut()
+	{
+		// This is a cancellation point: return true if you want to cancel
+		// the current operation. If you return true, handleTimeOut() will
+		// be called just after this, and before actually cancelling the
+		// operation
+		return false;
+	}
+
+	void resetTimeOut()
+	{
+		// Called at the beginning of an operation (eg. connecting,
+		// a read() or a write() on a socket...)
+	}
+
+	bool handleTimeOut()
+	{
+		// If isTimeOut() returned true, this function will be called. This
+		// allows you to interact with the user, ie. display a prompt to
+		// know whether he wants to cancel the operation.
+
+		// If you return true here, the operation will be actually cancelled.
+		// If not, the time out is reset and the operation continues.
+		return true;
+	}
+};
+
+
+class timeoutHandlerFactory : public vmime::net::timeoutHandlerFactory
+{
+public:
+
+	vmime::shared_ptr <vmime::net::timeoutHandler> create()
+	{
+		return vmime::make_shared <timeoutHandler>();
+	}
+};
+
+
 /** Print the MIME structure of a message on the standard output.
   *
   * @param s structure object
@@ -406,6 +453,9 @@ static void sendMessage()
 		// Enable TLS support if available
 		tr->setProperty("connection.tls", true);
 
+		// Set the time out handler
+		tr->setTimeoutHandlerFactory(vmime::make_shared <timeoutHandlerFactory>());
+
 		// Set the object responsible for verifying certificates, in the
 		// case a secured connection is used (TLS/SSL)
 		tr->setCertificateVerifier
@@ -520,6 +570,9 @@ static void connectStore()
 		// Enable TLS support if available
 		st->setProperty("connection.tls", true);
 
+		// Set the time out handler
+		st->setTimeoutHandlerFactory(vmime::make_shared <timeoutHandlerFactory>());
+
 		// Set the object responsible for verifying certificates, in the
 		// case a secured connection is used (TLS/SSL)
 		st->setCertificateVerifier