kopete/libkopete/kopetemessagehandler.h

   1 /*
   2     kopetemessagehandler.h - Kopete Message Filtering
   3
   4     Copyright (c) 2004      by Richard Smith         <kde@metafoo.co.uk>
   5     Kopete    (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
   6
   7     *************************************************************************
   8     *                                                                       *
   9     * This library is free software; you can redistribute it and/or         *
  10     * modify it under the terms of the GNU Lesser General Public            *
  11     * License as published by the Free Software Foundation; either          *
  12     * version 2 of the License, or (at your option) any later version.      *
  13     *                                                                       *
  14     *************************************************************************
  15 */
  16
  17 #ifndef KOPETEMESSAGEHANDLER_H
  18 #define KOPETEMESSAGEHANDLER_H
  19
  20 #include <QtCore/QObject>
  21 #include <QtCore/QLinkedList>
  22
  23 #include "kopete_export.h"
  24
  25 //FIXME: Message::MessageDirection could be moved into namespace Kopete
  26 // to avoid this being included everywhere
  27 #include "kopetemessage.h"
  28
  29 namespace Kopete
  30 {
  31
  32 class MessageEvent;
  33 class ChatSession;
  34
  35 /**
  36  * @author Richard Smith       <kde@metafoo.co.uk>
  37  *
  38  * An object which sits between the protocol and the chat window which
  39  * intercepts and processes messages on their way through.
  40  *
  41  * This class implements Handler role in the Chain of Responsibility pattern.
  42  * The Client role will be filled by the Kopete::MessageHandlerChain class.
  43  */
  44 class KOPETE_EXPORT MessageHandler : public QObject
  45 {
  46         Q_OBJECT
  47 public:
  48         MessageHandler();
  49         virtual ~MessageHandler() = 0;
  50
  51         /**
  52          * @return the next handler in the chain
  53          */
  54         MessageHandler *next();
  55         // FIXME: remove?
  56         void setNext( MessageHandler *next );
  57
  58         /**
  59          * @brief Gets the rich-text capabilities of this message handling object
  60          *
  61          * The default implementation returns next()->capabilities().
  62          */
  63         virtual int capabilities();
  64
  65         /**
  66          * @brief Performs any processing necessary on the message
  67          *
  68          * @param event The message event to process. Should not be null.
  69          *
  70          * Overriders of this handler @em must cause (possibly asynchronously)
  71          * one of the following to happen:
  72          *  - @p event->discard() to be called
  73          *  - @p event->continue() to be called
  74          *  - this base class implementation to be called (equivalent to event->continue() but faster)
  75          *
  76          * The base class implementation passes the event on to the next
  77          * handler in the chain.
  78          *
  79          * @note If you store @p event, be aware that it could be deleted at any time, and either
  80          *       connect to the its discarded(Kopete::MessageEvent*) signal or store it in a QPointer.
  81          */
  82         virtual void handleMessage( MessageEvent *event );
  83
  84         /** @internal */
  85         void handleMessageInternal( MessageEvent *event );
  86 private slots:
  87         /**
  88          * @internal The message has been accepted. Pass it on to the next handler.
  89          */
  90         void messageAccepted( Kopete::MessageEvent *event );
  91
  92 private:
  93         class Private;
  94         Private *d;
  95 };
  96
  97 /**
  98  * @author Richard Smith       <kde@metafoo.co.uk>
  99  *
 100  * A factory for creating MessageHandlers. Instantiate a class derived from MessageHandlerFactory
 101  * in order to make your MessageHandler be automatically added to the list of handlers used
 102  * when constructing handler chains.
 103  *
 104  * @note If you construct a handler for an Inbound chain, it may still be asked to process Outbound
 105  * messages. This is because when a message is being sent it first passes through the Outbound
 106  * chain to the protocol, then (when it has been delivered) it passes back through the Inbound
 107  * chain to the chat window to be displayed.
 108  */
 109 class KOPETE_EXPORT MessageHandlerFactory
 110 {
 111 public:
 112         /**
 113          * Constructs a MessageHandlerFactory, and adds it to the list of factories considered when
 114          * creating a MessageHandlerChain for a ChatSession.
 115          *
 116          * @note Since the factory is added to the list of possible factories before the object is
 117          * finished being constructed, it is not safe to call any function from a derived class's
 118          * constructor which may cause a MessageHandlerChain to be created.
 119          */
 120         MessageHandlerFactory();
 121         /**
 122          * Destroys the MessageHandlerFactory and removes it from the list of factories.
 123          */
 124         virtual ~MessageHandlerFactory();
 125
 126         typedef QLinkedList<MessageHandlerFactory*> FactoryList;
 127         /**
 128          * @return the list of registered message handler factories
 129          */
 130         static FactoryList messageHandlerFactories();
 131
 132         /**
 133          * @brief Creates a message handler for a given manager in a given direction.
 134          * @param manager The manager whose message handler chain the message handler is for
 135          * @param direction The direction of the chain that is being created.
 136          * @return the @ref MessageHandler object to put in the chain, or 0 if none is needed.
 137          */
 138         virtual MessageHandler *create( ChatSession *manager, Message::MessageDirection direction ) = 0;
 139
 140         /**
 141          * Special stages usable with any message direction
 142          */
 143         enum SpecialStage
 144         {
 145                 StageDoNotCreate = -10000, ///< do not create a filter for this stage
 146                 StageStart = 0,            ///< start of processing
 147                 StageEnd = 10000           ///< end of processing
 148         };
 149
 150         /**
 151          * Processing stages for handlers in inbound message handler chains
 152          */
 153         enum InboundStage
 154         {
 155                 InStageStart = 0,        ///< message was just received
 156                 InStageToSent = 2000,    ///< convert from received format to sent format
 157                 InStageToDesired = 5000, ///< convert to how the user wants the message
 158                 InStageFormat = 7000,    ///< decorate the message without changing the content
 159                 InStageEnd = 10000       ///< message ready for display
 160         };
 161
 162         /**
 163          * Processing stages for handlers in outbound message handler chains
 164          */
 165         enum OutboundStage
 166         {
 167                 OutStageStart = 0,        ///< user just hit Send
 168                 OutStageParse = 2000,     ///< process commands
 169                 OutStageToDesired = 4000, ///< convert to how the user wanted to send
 170                 OutStageFormat = 6000,    ///< decorate the message without changing the content
 171                 OutStageToSent = 8000,    ///< convert to the format to send in
 172                 OutStageEnd = 10000       ///< message ready for sending
 173         };
 174
 175         /**
 176          * Processing stages for handlers in internal message handler chains
 177          */
 178         enum InternalStage
 179         {
 180                 IntStageStart = 0,  ///< some component just created the message
 181                 IntStageEnd = 10000 ///< message ready for display
 182         };
 183
 184         /**
 185          * Offsets within a processing stage. Using these values allows finer
 186          * control over where in a chain a message handler will be added. Add
 187          * one of these values to values from the various Stage enumerations
 188          * to form a filter position.
 189          */
 190         enum Offset
 191         {
 192                 OffsetBefore = -90,
 193                 OffsetVeryEarly = -60,
 194                 OffsetEarly = -30,
 195                 OffsetNormal = 0,
 196                 OffsetLate = 30,
 197                 OffsetVeryLate = 60,
 198                 OffsetAfter = 90
 199         };
 200
 201         /**
 202          * @brief Returns the position in the message handler chain to put this factory's handlers
 203          * @param manager The manager whose message handler chain the message handler is for
 204          * @param direction The direction of the chain that is being created.
 205          * @return a member of the InboundStage, OutboundStage or InternalStage enumeration, as
 206          *         appropriate, optionally combined with a member of the Offset enumeration.
 207          * @retval StageDoNotCreate No filter should be created for this chain.
 208          */
 209         virtual int filterPosition( ChatSession *manager, Message::MessageDirection direction ) = 0;
 210
 211 private:
 212         // noncopyable
 213         MessageHandlerFactory(const MessageHandlerFactory &);
 214         void operator=(const MessageHandlerFactory &);
 215
 216         class Private;
 217         Private *d;
 218 };
 219
 220 }
 221
 222 #endif
 223
 224 // vim: set noet ts=4 sts=4 sw=4: