diff options
Diffstat (limited to 'kopete/libkopete/kopetemessagehandler.h')
| -rw-r--r-- | kopete/libkopete/kopetemessagehandler.h | 225 |
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: |