← Back to branch summary

~ubuntu-branches/ubuntu/saucy/kopete/saucy-proposed

« back to all changes in this revision

Viewing changes to libkopete/kopetemessagehandler.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2013-06-21 02:22:39 UTC
  • Revision ID: package-import@ubuntu.com-20130621022239-63l3zc8p0nf26pt6
Tags: upstream-4.10.80
Import upstream version 4.10.80

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 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 * const 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 * const d;
 
218
};
 
219
 
 
220
}
 
221
 
 
222
#endif
 
223
 
 
224
// vim: set noet ts=4 sts=4 sw=4: