This file is indexed.

/usr/include/gloox/messagesession.h is in libgloox-dev 1.0.11-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
/*
  Copyright (c) 2005-2014 by Jakob Schroeter <js@camaya.net>
  This file is part of the gloox library. http://camaya.net/gloox

  This software is distributed under a license. The full license
  agreement can be found in the file LICENSE in this distribution.
  This software may not be copied, modified, sold or distributed
  other than expressed in the named license agreement.

  This software is distributed without any warranty.
*/


#ifndef MESSAGESESSION_H__
#define MESSAGESESSION_H__

#include "jid.h"
#include "gloox.h"

#include <string>
#include <list>

namespace gloox
{

  class ClientBase;
  class MessageFilter;
  class MessageHandler;
  class Message;

  /**
   * @brief An abstraction of a message session between any two entities.
   *
   * This is an alternative interface to unmanaged messaging. The original interface, using the simple
   * MessageHandler-derived interface, is based on an all-or-nothing approach. Once registered with
   * ClientBase, a handler receives all message stanzas sent to this client and has to do any filtering
   * on its own.
   *
   * MessageSession adds an abstraction to a chat conversation. A MessageSession is responsible for
   * communicating with exactly one (full) JID. It is extensible with so-called MessageFilters, which can
   * provide additional features such as Message Events, or Chat State Notifications.
   *
   * You can still use the old MessageHandler in parallel, but messages will not be relayed to both
   * the generic MessageHandler and a MessageSession established for the sender's JID. The MessageSession
   * takes precedence.
   *
   * Using MessageSessions has the following advantages over the plain old MessageHandler:
   * @li automatic creation of MessageSessions
   * @li filtering by JID
   * @li automatic handling of threading (i.e., XMPP message threads)
   * @li simpler sending of messages
   * @li support for MessageFilters.
   *
   * @b Usage:<br>
   * Derive an object from MessageSessionHandler and reimplement handleMessageSession() to store your
   * shiny new sessions somewhere, or to create a new chat window, or whatever. Register your
   * object with a ClientBase instance using registerMessageSessionHandler(). In code:
   * @code
   * void MyClass::myFunc()
   * {
   *   JID jid( "abc@example.org/gloox" );
   *   j = new Client( jid, "password" );
   *   [...]
   *   j->registerMessageSessionHandler( this, 0 );
   * }
   * @endcode
   * MyClass is a MessageSessionHandler here.
   *
   * In this example, MyClass needs to be MessageHandler, MessageEventHandler and
   * ChatStateHandler, too. The handlers are registered with the session to receive the
   * respective events.
   * @code
   * virtual void MyClass::handleMessageSession( MessageSession* session )
   * {
   *   // for this example only, we delete any earlier session
   *   if( m_session )
   *     j->disposeMessageSession( m_session );
   *   m_session = session;
   *   m_session->registerMessageHandler( this );
   *
   *   // the following is optional
   *   m_messageEventFilter = new MessageEventFilter( m_session );
   *   m_messageEventFilter->registerMessageEventHandler( this );
   *   m_chatStateFilter = new ChatStateFilter( m_session );
   *   m_chatStateFilter->registerChatStateHandler( this );
   * }
   * @endcode
   *
   * MessageEventHandler::handleMessageEvent() and ChatStateHandler::handleChatState() are called
   * for incoming Message Events and Chat States, respectively.
   * @code
   * virtual void MyClass::handleMessageEvent( const JID& from, MessageEventType event )
   * {
   *   // display contact's Message Event
   * }
   *
   * virtual void MyClass::handleChatState( const JID& from, ChatStateType state )
   * {
   *   // display contact's Chat State
   * }
   * @endcode
   *
   * To let the chat partner now that the user is typing a message or has closed the chat window, use
   * raiseMessageEvent() and setChatState(), respectively. For example:
   * @code
   * // user is typing a message
   * m_messageEventFilter->raiseMessageEvent( MessageEventComposing );
   *
   * // acknowledge receiving of a message
   * m_messageEventFilter->raiseMessageEvent( MessageEventDelivered );
   *
   * // user is not actively paying attention to the chat
   * m_chatStateFilter->setChatState( ChatStateInactive );
   *
   * // user has closed the chat window
   * m_chatStateFilter->setChatState( ChatStateGone );
   * @endcode
   *
   * To send a message to the chat partner of the session, use
   * @ref send( const std::string& message, const std::string& subject, const StanzaExtensionList& ).
   * You don't have to care about
   * receipient, thread id, etc., they are added automatically.
   *
   * @code
   * m_session->send( "Hello World!", "No Subject" );
   * @endcode
   *
   * To initiate a new chat session, all you have to do is create a new MessageSession and register
   * a MessageHandler with it:
   * @code
   * MessageSession* MyClass::newSession( const JID& to )
   * {
   *   MessageSession* session = new MessageSession( m_client, to );
   *   session->registerMessageHandler( this );
   *   return session;
   * }
   * @endcode
   *
   * @note You should never delete a MessageSession manually. Use ClientBase::disposeMessageSession()
   * instead.
   *
   * @author Jakob Schroeter <js@camaya.net>
   * @since 0.8
   */
  class GLOOX_API MessageSession
  {

    friend class MessageFilter;

    public:
      /**
       * Constructs a new MessageSession for the given JID.
       * It is recommended to supply a full JID, in other words, it should have a resource set.
       * No resource can lead to unexpected behavior. A thread ID is generated and sent along
       * with every message sent through this session.
       * @param parent The ClientBase to use for communication.
       * @param jid The remote contact's full JID. If you don't know the full JID (this is probably the
       * most common case) but still want replies from the full JID to be handled by this MessageSession,
       * set the @b wantUpgrade parameter to true (or leave it untouched).
       * @param wantUpgrade This flag indicates whether gloox should try to match an incoming message
       * from a full JID to this MessageSession. If unsure, use the default. You probably only want to use
       * a non-default value if this MessageSession is supposed to talk directly to a server or component
       * JID that has no resource. This 'upgrade' will only happen once.
       * @param types ORed list of Message::MessageType values this MessageSession shall receive.
       * Defaults to 0 which means any type is received.
       * @param honorTID Indicates whether thread IDs should be honored when matching incoming messages to MessageSessions.
       * The default (@b true) is usually fine.
       */
      MessageSession( ClientBase* parent, const JID& jid, bool wantUpgrade = true, int types = 0, bool honorTID = true );

      /**
       * Virtual destructor.
       *
       * @note You should never delete a MessageSession manually. Use ClientBase::disposeMessageSession()
       * instead.
       */
      virtual ~MessageSession();

      /**
       * Use this function to find out where this session points at.
       * @return The receipient's JID.
       */
      const JID& target() const { return m_target; }

      /**
       * By default, a thread ID is sent with every message to identify
       * messages belonging together.
       * @returns The thread ID for this session.
       */
      const std::string& threadID() const { return m_thread; }

      /**
       * Use this function to set the session's thread ID if e.g. a specific thread is
       * continued. It should not normally be needed to set the thread ID manually.
       * @param thread The new thread ID.
       */
      void setThreadID( const std::string& thread ) { m_thread = thread; }

      /**
       * Indicates whether thread IDs are honored when matching incoming
       * messages to MessageSessions.
       * @return Whether thread IDs are honored.
       */
      bool honorThreadID() const { return m_honorThreadID; }

      /**
       * Use this function to associate a MessageHandler with this MessageSession.
       * The MessageHandler will receive all messages sent from this MessageSession's
       * remote contact.
       * @param mh The MessageHandler to register.
       */
      void registerMessageHandler( MessageHandler* mh )
        { m_messageHandler = mh; }

      /**
       * This function clears the internal pointer to the MessageHandler and therefore
       * disables message delivery.
       */
      void removeMessageHandler()
        { m_messageHandler = 0; }

      /**
       * A convenience function to quickly send a message.
       * @param message The message to send.
       */
      virtual void send( const std::string& message );

      /**
       * A convenience function to quickly send a message (optionally with subject). This is
       * the preferred way to send a message from a MessageSession.
       * @param message The message to send.
       * @param subject The optional subject to send.
       * @param sel An optional list of StanzaExtensions. The extensions will be owned by the message-to-be-sent;
       * do not attempt to re-use or delete them.
       */
      virtual void send( const std::string& message, const std::string& subject,
                         const StanzaExtensionList& sel = StanzaExtensionList() );

      /**
       * Use this function to hook a new MessageFilter into a MessageSession.
       * The filter will be able to read and/or modify a message stanza's content.
       * @note The MessageSession will become the owner of the filter, it will be
       * deleted by MessageSession's destructor. To get rid of the filter before that,
       * use disposeMessageFilter().
       * @param mf The MessageFilter to add.
       */
      void registerMessageFilter( MessageFilter* mf )
        { m_messageFilterList.push_back( mf ); }

      /**
       * Use this function to remove a MessageFilter from the MessageSession.
       * @param mf The MessageFilter to remove.
       * @note To remove and delete the MessageFilter in one step use disposeMessageFilter().
       */
      void removeMessageFilter( MessageFilter* mf )
        { m_messageFilterList.remove( mf ); }

      /**
       * Use this function to remove and delete a MessageFilter from the MessageSession.
       * @param mf The MessageFilter to remove and delete.
       * @note To just remove (and not delete) the MessageFilter use removeMessageFilter().
       */
      void disposeMessageFilter( MessageFilter* mf );

      /**
       * Returns the message type this MessageSession wants to receive.
       * @return ORed list of Message::MessageType values this MessageSession wants to receive.
       */
      int types() const { return m_types; }

      /**
       * This function resets the session's target JID to its bare form such that
       * subsequently sent messages will be sent to that bare JID. The server will
       * determine the best resource to deliver to. Useful if the target
       * resource changed presence to e.g. away or offline. This does not automatically
       * set the wantResourceTracking option. If you need escalation, be sure to set
       * this option in the constructor.
       */
      void resetResource();

      /**
       * This function can be used to feed a message into the session. Ususally, only
       * ClientBase should call this function.
       * @param msg A Message to feed into the session.
       */
      virtual void handleMessage( Message& msg );

    protected:
      /**
       * A wrapper around ClientBase::send(). You should @b not use this function to send a
       * chat message because the Tag is not prepared accordingly (neither a thread ID is added nor is
       * the message ran through the message filters).
       * @param msg A Message to send.
       */
      virtual void send( const Message& msg );
      void decorate( Message& msg );

      ClientBase* m_parent;
      JID m_target;
      MessageHandler* m_messageHandler;

    private:
      void setResource( const std::string& resource );

      typedef std::list<MessageFilter*> MessageFilterList;
      MessageFilterList m_messageFilterList;

      std::string m_thread;
      int m_types;
      bool m_wantResourceTracking;
      bool m_hadMessages;
      bool m_honorThreadID;

  };

}

#endif // MESSAGESESSION_H__