Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 225 insertions, 0 deletions

diff --git a/kopete/libkopete/kopetemessagehandler.h b/kopete/libkopete/kopetemessagehandler.h
new file mode 100644
index 00000000..ba16184c
--- /dev/null
+++ b/kopete/libkopete/kopetemessagehandler.h
@@ -0,0 +1,225 @@
+/*
+    kopetemessagehandler.h - Kopete Message Filtering
+
+    Copyright (c) 2004      by Richard Smith         <kde@metafoo.co.uk>
+    Kopete    (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
+
+    *************************************************************************
+    *                                                                       *
+    * This library is free software; you can redistribute it and/or         *
+    * modify it under the terms of the GNU Lesser General Public            *
+    * License as published by the Free Software Foundation; either          *
+    * version 2 of the License, or (at your option) any later version.      *
+    *                                                                       *
+    *************************************************************************
+*/
+
+#ifndef KOPETEMESSAGEHANDLER_H
+#define KOPETEMESSAGEHANDLER_H
+
+#include <qobject.h>
+//#include <kdemacros.h>
+#include "kopete_export.h"
+
+//FIXME: Message::MessageDirection could be moved into namespace Kopete
+// to avoid this being included everywhere
+#include "kopetemessage.h"
+
+#include <qvaluelist.h>
+
+namespace Kopete
+{
+
+class MessageEvent;
+class ChatSession;
+
+/**
+ * @author Richard Smith       <kde@metafoo.co.uk>
+ *
+ * An object which sits between the protocol and the chat window which
+ * intercepts and processes messages on their way through.
+ *
+ * This class implements Handler role in the Chain of Responsibility pattern.
+ * The Client role will be filled by the Kopete::MessageHandlerChain class.
+ */
+class KOPETE_EXPORT MessageHandler : public QObject
+{
+	Q_OBJECT
+public:
+	MessageHandler();
+	virtual ~MessageHandler() = 0;
+
+	/**
+	 * @return the next handler in the chain
+	 */
+	MessageHandler *next();
+	// FIXME: remove?
+	void setNext( MessageHandler *next );
+
+	/**
+	 * @brief Gets the rich-text capabilities of this message handling object
+	 *
+	 * The default implementation returns next()->capabilities().
+	 */
+	virtual int capabilities();
+
+	/**
+	 * @brief Performs any processing necessary on the message
+	 *
+	 * @param event The message event to process. Should not be null.
+	 * 
+	 * Overriders of this handler @em must cause (possibly asynchronously)
+	 * one of the following to happen:
+	 *  - @p event->discard() to be called
+	 *  - @p event->continue() to be called
+	 *  - this base class implementation to be called (equivalent to event->continue() but faster)
+	 * 
+	 * The base class implementation passes the event on to the next
+	 * handler in the chain.
+	 * 
+	 * @note If you store @p event, be aware that it could be deleted at any time, and either
+	 *       connect to the its discarded(Kopete::MessageEvent*) signal or store it in a QGuardedPtr.
+	 */
+	virtual void handleMessage( MessageEvent *event );
+
+	/** @internal */
+	void handleMessageInternal( MessageEvent *event );
+private slots:
+	/**
+	 * @internal The message has been accepted. Pass it on to the next handler.
+	 */
+	void messageAccepted( Kopete::MessageEvent *event );
+
+private:
+	class Private;
+	Private *d;
+};
+
+/**
+ * @author Richard Smith       <kde@metafoo.co.uk>
+ *
+ * A factory for creating MessageHandlers. Instantiate a class derived from MessageHandlerFactory
+ * in order to make your MessageHandler be automatically added to the list of handlers used
+ * when constructing handler chains.
+ * 
+ * @note If you construct a handler for an Inbound chain, it may still be asked to process Outbound
+ * messages. This is because when a message is being sent it first passes through the Outbound
+ * chain to the protocol, then (when it has been delivered) it passes back through the Inbound
+ * chain to the chat window to be displayed.
+ */
+class KOPETE_EXPORT MessageHandlerFactory
+{
+public:
+	/**
+	 * Constructs a MessageHandlerFactory, and adds it to the list of factories considered when
+	 * creating a MessageHandlerChain for a ChatSession.
+	 * 
+	 * @note Since the factory is added to the list of possible factories before the object is
+	 * finished being constructed, it is not safe to call any function from a derived class's
+	 * constructor which may cause a MessageHandlerChain to be created.
+	 */
+	MessageHandlerFactory();
+	/**
+	 * Destroys the MessageHandlerFactory and removes it from the list of factories.
+	 */
+	virtual ~MessageHandlerFactory();
+	
+	typedef QValueList<MessageHandlerFactory*> FactoryList;
+	/**
+	 * @return the list of registered message handler factories
+	 */
+	static FactoryList messageHandlerFactories();
+	
+	/**
+	 * @brief Creates a message handler for a given manager in a given direction.
+	 * @param manager The manager whose message handler chain the message handler is for
+	 * @param direction The direction of the chain that is being created.
+	 * @return the @ref MessageHandler object to put in the chain, or 0 if none is needed.
+	 */
+	virtual MessageHandler *create( ChatSession *manager, Message::MessageDirection direction ) = 0;
+	
+	/**
+	 * Special stages usable with any message direction
+	 */
+	enum SpecialStage
+	{
+		StageDoNotCreate = -10000, ///< do not create a filter for this stage
+		StageStart = 0,            ///< start of processing
+		StageEnd = 10000           ///< end of processing
+	};
+	
+	/**
+	 * Processing stages for handlers in inbound message handler chains
+	 */
+	enum InboundStage
+	{
+		InStageStart = 0,        ///< message was just received
+		InStageToSent = 2000,    ///< convert from received format to sent format
+		InStageToDesired = 5000, ///< convert to how the user wants the message
+		InStageFormat = 7000,    ///< decorate the message without changing the content
+		InStageEnd = 10000       ///< message ready for display
+	};
+	
+	/**
+	 * Processing stages for handlers in outbound message handler chains
+	 */
+	enum OutboundStage
+	{
+		OutStageStart = 0,        ///< user just hit Send
+		OutStageParse = 2000,     ///< process commands
+		OutStageToDesired = 4000, ///< convert to how the user wanted to send
+		OutStageFormat = 6000,    ///< decorate the message without changing the content
+		OutStageToSent = 8000,    ///< convert to the format to send in
+		OutStageEnd = 10000       ///< message ready for sending
+	};
+	
+	/**
+	 * Processing stages for handlers in internal message handler chains
+	 */
+	enum InternalStage
+	{
+		IntStageStart = 0,  ///< some component just created the message
+		IntStageEnd = 10000 ///< message ready for display
+	};
+	
+	/**
+	 * Offsets within a processing stage. Using these values allows finer
+	 * control over where in a chain a message handler will be added. Add
+	 * one of these values to values from the various Stage enumerations
+	 * to form a filter position.
+	 */
+	enum Offset
+	{
+		OffsetBefore = -90,
+		OffsetVeryEarly = -60,
+		OffsetEarly = -30,
+		OffsetNormal = 0,
+		OffsetLate = 30,
+		OffsetVeryLate = 60,
+		OffsetAfter = 90
+	};
+	
+	/**
+	 * @brief Returns the position in the message handler chain to put this factory's handlers
+	 * @param manager The manager whose message handler chain the message handler is for
+	 * @param direction The direction of the chain that is being created.
+	 * @return a member of the InboundStage, OutboundStage or InternalStage enumeration, as
+	 *         appropriate, optionally combined with a member of the Offset enumeration.
+	 * @retval StageDoNotCreate No filter should be created for this chain.
+	 */
+	virtual int filterPosition( ChatSession *manager, Message::MessageDirection direction ) = 0;
+	
+private:
+	// noncopyable
+	MessageHandlerFactory(const MessageHandlerFactory &);
+	void operator=(const MessageHandlerFactory &);
+	
+	class Private;
+	Private *d;
+};
+
+}
+
+#endif
+
+// vim: set noet ts=4 sts=4 sw=4: