This file is indexed.

/usr/include/gloox/mucroom.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
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
/*
  Copyright (c) 2006-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 MUCROOM_H__
#define MUCROOM_H__

#include "discohandler.h"
#include "disconodehandler.h"
#include "dataform.h"
#include "presencehandler.h"
#include "iqhandler.h"
#include "messagehandler.h"
#include "mucroomhandler.h"
#include "mucroomconfighandler.h"
#include "jid.h"
#include "stanzaextension.h"

#include <string>

namespace gloox
{

  class ClientBase;
  class MUCMessageSession;
  class Message;

  /**
   * @brief This is an implementation of @xep{0045} (Multi-User Chat).
   *
   * Usage is pretty simple:
   *
   * Derrive an object from MUCRoomHandler and implement its virtuals:
   * @code
   * class MyClass : public MUCRoomHandler
   * {
   *   ...
   * };
   * @endcode
   *
   * Then create a new MUCRoom object and pass it a valid ClientBase, the desired full room JID,
   * your MUCRoomHandler-derived object, and an optional MUCRoomConfigHandler-derived object.
   * @code
   * void MyOtherClass::joinRoom( const std::string& room, const std::string& service,
   *                              const std::string& nick )
   * {
   *   MyClass* myHandler = new MyClass(...);
   *   JID roomJID( room + "@" + service + "/" + nick );
   *   m_room = new MUCRoom( m_clientbase, roomJID, myHandler, 0 );
   *   m_room->join();
   * }
   * @endcode
   *
   * When joining the room was successful, the various MUCRoomHandler functions will start to
   * be called. If joining was not successful, MUCRoomHandler::handleMUCError() will be called,
   * giving a hint at the reason for the failure.
   *
   * To set up your own room, or to configure an existing room, you should also derive a
   * class from MUCRoomConfigHandler and register it with the MUCRoom (either by using it
   * with MUCRoom's constructor, or by calling registerMUCRoomConfigHandler()).
   *
   * To quickly create an instant room, see InstantMUCRoom.
   *
   * To quickly create an instant room to turn a one-to-one chat into a multi-user chat,
   * see UniqueMUCRoom.
   *
   * To send a private message to a room participant, use
   * @link MessageSession gloox::MessageSession @endlink with the participant's full room JID
   * (room\@service/nick).
   *
   * XEP version: 1.21
   * @author Jakob Schroeter <js@camaya.net>
   * @since 0.9
   */
  class GLOOX_API MUCRoom : private DiscoHandler, private PresenceHandler,
                            public IqHandler, private MessageHandler, private DiscoNodeHandler
  {
    public:
      /**
       * Allowable history request types. To disable sending of history, use any value except
       * HistoryUnknown and specify a zero-length time span (using setRequestHistory()).
       */
      enum HistoryRequestType
      {
        HistoryMaxChars,            /**< Limit the total number of characters in the history to "X"
                                     * (where the character count is the characters of the complete
                                     * XML stanzas, not only their XML character data). */
        HistoryMaxStanzas,          /**< Limit the total number of messages in the history to "X". */
        HistorySeconds,             /**< Send only the messages received in the last "X" seconds. */
        HistorySince,               /**< Send only the messages received since the datetime specified
                                     * (which MUST conform to the DateTime profile specified in Jabber
                                     * Date and Time Profiles (@xep{0082})). */
        HistoryUnknown              /**< It is up to the service to decide how much history to send.
                                     * This is the default. */
      };

      /**
       * Available operations.
       */
      enum MUCUserOperation
      {
        OpNone,                 /**< No operation. */
        OpInviteTo,             /**< Invitation being sent to soemone. */
        OpInviteFrom,           /**< Invitation received from someone. */
        OpDeclineTo,            /**< Someone's invitation declined. */
        OpDeclineFrom           /**< Someone declined an invitation. */
      };

      /**
       * @brief An abstraction of a MUC query.
       *
       * You should not need to use this class directly.
       *
       * @author Jakob Schroeter <js@camaya.net>
       * @since 1.0
       */
      class MUC : public StanzaExtension
      {
        public:
          /**
           * Creates a new MUC object.
           * @param password An optional room password.
           * @param historyType The type of room history to request.
           * @param historySince A string describing the amount of room history.
           * @param historyValue The amount of requested room history.
           */
          MUC( const std::string& password, HistoryRequestType historyType = HistoryUnknown,
               const std::string& historySince = EmptyString, int historyValue = 0 );

          /**
           * Constructs a new MUCUser object from the given Tag.
           * @param tag The Tag to parse.
           */
          MUC( const Tag* tag = 0 );

          /**
           * Virtual destructor.
           */
          virtual ~MUC();

          /**
           * Returns a pointer to the current password, or 0.
           * @return A pointer to the current password, or 0.
           */
          const std::string* password() const { return m_password; }

          /**
           * Returns a pointer to the description of the amount of room history requested.
           * @return A pointer to the description of the amount of room history requested.
           */
          const std::string* historySince() const { return m_historySince; }

          // reimplemented from StanzaExtension
          virtual const std::string& filterString() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* newInstance( const Tag* tag ) const
          {
            return new MUC( tag );
          }

          // reimplemented from StanzaExtension
          virtual Tag* tag() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* clone() const
          {
            MUC* m = new MUC();
            m->m_password = m_password ? new std::string( *m_password ) : 0;
            m->m_historySince = m_historySince ? new std::string( *m_historySince ) : 0;
            m->m_historyType = m_historyType;
            m->m_historyValue = m_historyValue;
            return m;
          }

        private:
          std::string* m_password;
          std::string* m_historySince;
          HistoryRequestType m_historyType;
          int m_historyValue;
      };

      /**
       * @brief An abstraction of a MUC user query.
       *
       * You should not need to use this class directly.
       *
       * @author Jakob Schroeter <js@camaya.net>
       * @since 1.0
       */
      class MUCUser : public StanzaExtension
      {
        public:
          /**
           * Constructor.
           * @param operation An operation to perform.
           * @param to The recipient.
           * @param reason The reason for the operation.
           * @param thread If this is an invitation, and if the invitation is part of
           * a transformation of a one-to-one chat to a MUC, include the one-to-one chat's
           * thread ID here. Defaults to the empty string (i.e. not a continuation).
           */
          MUCUser( MUCUserOperation operation, const std::string& to, const std::string& reason,
                   const std::string& thread = EmptyString );

          /**
           * Constructs a new MUCUser object from the given Tag.
           * @param tag The Tag to parse.
           */
          MUCUser( const Tag* tag = 0 );

          /**
           * Virtual destructor.
           */
          virtual ~MUCUser();

          /**
           * Returns the current room flags.
           * @return The current room flags.
           */
          int flags() const { return m_flags; }

          /**
           * Returns the user's current room affiliation.
           * @return The user's current room affiliation.
           */
          MUCRoomAffiliation affiliation() const { return m_affiliation; }

          /**
           * Returns the user's current room role.
           * @return The user's current room role.
           */
          MUCRoomRole role() const { return m_role; }

          /**
           *
           */
          const std::string* jid() const { return m_jid; }

          /**
           *
           */
          const std::string* actor() const { return m_actor; }

          /**
           *
           */
          const std::string* password() const { return m_password; }

          /**
           *
           */
          const std::string* thread() const { return m_thread; }

          /**
           *
           */
          const std::string* reason() const { return m_reason; }

          /**
           *
           */
          const std::string* newNick() const { return m_newNick; }

          /**
           * Returns an alternate venue, if set.
           * @return An alternate venue, if set.
           */
          const std::string* alternate() const { return m_alternate; }

          /**
           * Whether or not the 'continue' flag is set.
           * @return Whether or not the 'continue' flag is set.
           */
          bool continued() const { return m_continue; }

          /**
           * Returns the current operation.
           * @return The current operation.
           */
          MUCUserOperation operation() const { return m_operation; }

          // reimplemented from StanzaExtension
          virtual const std::string& filterString() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* newInstance( const Tag* tag ) const
          {
            return new MUCUser( tag );
          }

          // reimplemented from StanzaExtension
          virtual Tag* tag() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* clone() const
          {
            MUCUser* m = new MUCUser();
            m->m_affiliation = m_affiliation;
            m->m_role = m_role;
            m->m_jid = m_jid ? new std::string( *m_jid ) : 0;
            m->m_actor = m_actor ? new std::string( *m_actor ) : 0;
            m->m_thread = m_thread ? new std::string( *m_thread ) : 0;
            m->m_reason = m_reason ? new std::string( *m_reason ) : 0;
            m->m_newNick = m_newNick ? new std::string( *m_newNick ) : 0;
            m->m_password = m_password ? new std::string( *m_password ) : 0;
            m->m_alternate = m_alternate ? new std::string( *m_alternate ) : 0;
            m->m_operation = m_operation;
            m->m_flags = m_flags;
            m->m_del = m_del;
            m->m_continue = m_continue;
            return m;
          }

        private:
          static MUCRoomAffiliation getEnumAffiliation( const std::string& affiliation );
          static MUCRoomRole getEnumRole( const std::string& role );


          MUCRoomAffiliation m_affiliation;
          MUCRoomRole m_role;
          std::string* m_jid;
          std::string* m_actor;
          std::string* m_thread;
          std::string* m_reason;
          std::string* m_newNick;
          std::string* m_password;
          std::string* m_alternate;
          MUCUserOperation m_operation;
          int m_flags;
          bool m_del;
          bool m_continue;
      };

      /**
       * Creates a new abstraction of a Multi-User Chat room. The room is not joined automatically.
       * Use join() to join the room, use leave() to leave it.
       * @param parent The ClientBase object to use for the communication.
       * @param nick The room's name and service plus the desired nickname in the form
       * room\@service/nick.
       * @param mrh The MUCRoomHandler that will listen to room events. May be 0 and may be specified
       * later using registerMUCRoomHandler(). However, without one, MUC is no joy.
       * @param mrch The MUCRoomConfigHandler that will listen to room config result. Defaults to 0
       * initially. However, at the latest you need one when you create a new room which is not an
       * instant room. You can set a MUCRoomConfigHandler using registerMUCRoomConfigHandler().
       */
      MUCRoom( ClientBase* parent, const JID& nick, MUCRoomHandler* mrh, MUCRoomConfigHandler* mrch = 0 );

      /**
       * Virtual Destructor.
       */
      virtual ~MUCRoom();

      /**
       * Use this function to set a password to use when joining a (password protected)
       * room.
       * @param password The password to use for this room.
       * @note This function does not password-protect a room.
       */
      void setPassword( const std::string& password ) { m_password = password; }

      /**
       * A convenience function that returns the room's name.
       * @return The room's name.
       */
      const std::string name() const { return m_nick.username(); }

      /**
       * A convenience function that returns the name/address of the MUC service the room is running on
       * (e.g., conference.jabber.org).
       * @return The MUC service's name/address.
       */
      const std::string service() const { return m_nick.server(); }

      /**
       * A convenience function that returns the user's nickname in the room.
       * @return The user's nickname.
       */
      const std::string nick() const { return m_nick.resource(); }

      /**
       * Join this room.
       * @param type The presence to join with, defaults to Available.
       * @param status The presence's optional status text.
       * @param priority The presence's optional priority, defaults to 0.
       * ClientBase will automatically include the default Presence extensions added using
       * @link gloox::ClientBase::addPresenceExtension() ClientBase::addPresenceExtension() @endlink.
       */
      virtual void join( Presence::PresenceType type = Presence::Available,
                         const std::string& status = EmptyString,
                         int priority = 0 );

      /**
       * Leave this room.
       * @param msg An optional msg indicating the reason for leaving the room. Default: empty.
       */
      void leave( const std::string& msg = EmptyString );

      /**
       * Sends a chat message to the room.
       * @param message The message to send.
       */
      void send( const std::string& message );

      /**
       * Sets the subject of the room to the given string.
       * The MUC service may decline the request to set a new subject. You should
       * not assume the subject was set successfully util it is acknowledged via the MUCRoomHandler.
       * @param subject The new subject.
       */
      void setSubject( const std::string& subject );

      /**
       * Returns the user's current affiliation with this room.
       * @return The user's current affiliation.
       */
      MUCRoomAffiliation affiliation() const { return m_affiliation; }

      /**
       * Returns the user's current role in this room.
       * @return The user's current role.
       */
      MUCRoomRole role() const { return m_role; }

      /**
       * Use this function to change the user's nickname in the room.
       * The MUC service may decline the request to set a new nickname. You should not assume
       * the nick change was successful until it is acknowledged via the MUCRoomHandler.
       * @param nick The user's new nickname.
       */
      void setNick( const std::string& nick );

      /**
       * Use this function to set the user's presence in this room. It is not possible to
       * use Unavailable with this function.
       * @param presence The user's new presence.
       * @param msg An optional status message. Default: empty.
       */
      void setPresence( Presence::PresenceType presence, const std::string& msg = EmptyString );

      /**
       * Use this function to invite another user to this room.
       * @param invitee The (bare) JID of the user to invite.
       * @param reason The user-supplied reason for the invitation.
       * @param thread If this invitation is part of a transformation of a
       * one-to-one chat to a MUC, include the one-to-one chat's thread ID here. Defaults
       * to the empty string (i.e. not a continuation).
       */
      void invite( const JID& invitee, const std::string& reason, const std::string& thread = EmptyString );

      /**
       * Use this function to request basic room info, possibly prior to joining it.
       * Results are announced using the MUCRoomHandler.
       */
      void getRoomInfo();

      /**
       * Use this function to request information about the current room occupants,
       * possibly prior to joining it. The room ay be configured not to disclose such
       * information.
       * Results are announced using the MUCRoomHandler.
       */
      void getRoomItems();

      /**
       * The MUC spec enables other entities to discover via Service Discovery which rooms
       * an entity is in. By default, gloox does not publish such info for privacy reasons.
       * This function can be used to enable publishing the info for @b this room.
       * @param publish Whether to enable other entities to discover the user's presence in
       * @b this room.
       * @param publishNick Whether to publish the nickname used in the room. This parameter
       * is ignored if @c publish is @b false.
       */
      void setPublish( bool publish, bool publishNick );

      /**
       * Use this function to register a (new) MUCRoomHandler with this room. There can be only one
       * MUCRoomHandler per room at any one time.
       * @param mrl The MUCRoomHandler to register.
       */
      void registerMUCRoomHandler( MUCRoomHandler* mrl ) { m_roomHandler = mrl; }

      /**
       * Use this function to remove the registered MUCRoomHandler.
       */
      void removeMUCRoomHandler() { m_roomHandler = 0; }

      /**
       * Use this function to register a (new) MUCRoomConfigHandler with this room. There can
       * be only one MUCRoomConfigHandler per room at any one time.
       * @param mrch The MUCRoomConfigHandler to register.
       */
      void registerMUCRoomConfigHandler( MUCRoomConfigHandler* mrch ) { m_roomConfigHandler = mrch; }

      /**
       * Use this function to remove the registered MUCRoomConfigHandler.
       */
      void removeMUCRoomConfigHandler() { m_roomConfigHandler = 0; }

      /**
       * Use this function to add history to a (newly created) room. The use case from the MUC spec
       * is to add history to a room that was created in the process of a transformation of a
       * one-to-one chat to a multi-user chat.
       * @param message A reason for declining the invitation.
       * @param from The JID of the original author of this part of the history.
       * @param stamp The datetime of the original message in the format: 20061224T12:15:23Z
       * @note You should not attempt to use this function before
       * MUCRoomHandler::handleMUCParticipantPresence() was called for the first time.
       */
      void addHistory( const std::string& message, const JID& from, const std::string& stamp );

      /**
       * Use this function to request room history. Set @c value to zero to disable the room
       * history request. You should not use HistorySince type with this function.
       * History is sent only once after entering a room. You should use this function before joining.
       * @param value Represents either the number of requested characters, the number of requested
       * message stanzas, or the number seconds, depending on the value of @c type.
       * @param type
       * @note If this function is not used to request a specific amount of room history, it is up
       * to the MUC service to decide how much history to send.
       */
      void setRequestHistory( int value, HistoryRequestType type );

      /**
       * Use this function to request room history since specific datetime.
       * History is sent only once after entering a room. You should use this function before joining.
       * @param since A string representing a datetime conforming to the DateTime profile specified
       * in Jabber Date and Time Profiles (@xep{0082}).
       * @note If this function is not used to request a specific amount of room history, it is up
       * to the MUC service to decide how much history to send.
       */
      void setRequestHistory( const std::string& since );

      /**
       * This static function allows to formally decline a MUC
       * invitation received via the MUCInvitationListener.
       * @param room The JID of the room the invitation came from.
       * @param invitor The JID of the invitor.
       * @param reason An optional reason for the decline.
       * @return A pointer to a Message. You will have to send (and
       * possibly delete) this Message manually.
       */
      static Message* declineInvitation( const JID& room, const JID& invitor,
                                     const std::string& reason = EmptyString);

      /**
       * It is not possible for a visitor to speak in a moderated room. Use this function to request
       * voice from the moderator.
       */
      void requestVoice();

      /**
       * Use this function to kick a user from the room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, a role of 'moderator' is necessary.
       * @note This is a convenience function. It directly uses setRole() with a MUCRoomRole of RoleNone.
       * @param nick The nick of the user to be kicked.
       * @param reason An optional reason for the kick.
       */
      void kick( const std::string& nick, const std::string& reason = EmptyString )
        { setRole( nick, RoleNone, reason ); }

      /**
       * Use this function to ban a user from the room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, an affiliation of admin is necessary.
       * @note This is a convenience function. It directly uses setAffiliation() with a MUCRoomAffiliation
       * of RoleOutcast.
       * @param nick The nick of the user to be banned.
       * @param reason An optional reason for the ban.
       */
      void ban( const std::string& nick, const std::string& reason )
        { setAffiliation( nick, AffiliationOutcast, reason ); }

      /**
       * Use this function to grant voice to a user in a moderated room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, a role of 'moderator' is necessary.
       * @note This is a convenience function. It directly uses setRole() with a MUCRoomRole
       * of RoleParticipant.
       * @param nick The nick of the user to be granted voice.
       * @param reason An optional reason for the grant.
       */
      void grantVoice( const std::string& nick, const std::string& reason )
        { setRole( nick, RoleParticipant, reason ); }

      /**
       * Use this function to create a Tag that approves a voice request or registration request
       * delivered via MUCRoomConfigHandler::handleMUCVoiceRequest(). You will need to send this
       * Tag off manually using Client/ClientBase.
       * @param room The room's JID. This is needed because you can use this function outside of
       * room context (e.g, if the admin is not in the room).
       * @param df The filled-in DataForm from the voice/registration request. The form object
       * will be owned by the returned Message.
       */
      static Message* createDataForm( const JID& room, const DataForm* df );

      /**
       * Use this function to revoke voice from a user in a moderated room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, a role of 'moderator' is necessary.
       * @note This is a convenience function. It directly uses setRole() with a MUCRoomRole
       * of RoleVisitor.
       * @param nick The nick of the user.
       * @param reason An optional reason for the revoke.
       */
      void revokeVoice( const std::string& nick, const std::string& reason )
        { setRole( nick, RoleVisitor, reason ); }

      /**
       * Use this function to change the role of a user in the room.
       * Usually, at least moderator privileges are required to succeed.
       * @param nick The nick of the user who's role shall be modfified.
       * @param role The user's new role in the room.
       * @param reason An optional reason for the role change.
       */
      void setRole( const std::string& nick, MUCRoomRole role, const std::string& reason = EmptyString );

      /**
       * Use this function to change the affiliation of a user in the room.
       * Usually, at least admin privileges are required to succeed.
       * @param nick The nick of the user who's affiliation shall be modfified.
       * @param affiliation The user's new affiliation in the room.
       * @param reason An optional reason for the affiliation change.
       */
      void setAffiliation( const std::string& nick, MUCRoomAffiliation affiliation,
                           const std::string& reason );

      /**
       * Use this function to request the room's configuration form.
       * It can be used either after MUCRoomHandler::handleMUCRoomCreation() was called,
       * or at any later time.
       *
       * Usually owner privileges are required for this action to
       * succeed.
       *
       * Use setRoomConfig() to send the modified room config back.
       */
      void requestRoomConfig();

      /**
       * After requesting (using requestRoomConfig()) and
       * editing/filling in the room's configuration,
       * use this function to send it back to the server.
       * @param form The form to send. The function will delete the
       * object pointed to.
       */
      void setRoomConfig( DataForm* form );

      /**
       * Use this function to accept the room's default configuration. This function is useful
       * only after MUCRoomHandler::handleMUCRoomCreation() was called. This is a NOOP at
       * any other time.
       */
      void acknowledgeInstantRoom()
        { instantRoom( CreateInstantRoom ); }

      /**
       * Use this function to cancel the creation of a room. This function is useful only after
       * MUCRoomHandler::handleMUCRoomCreation() was called. This is a NOOP at any other time.
       */
      void cancelRoomCreation()
        { instantRoom( CancelRoomCreation ); }

      /**
       * Use this function to destroy the room. All the occupants will be removed from the room.
       * @param reason An optional reason for the destruction.
       * @param alternate A pointer to a JID of an alternate venue (e.g., another MUC room).
       * May be 0.
       * @param password An optional password for the alternate venue.
       *
       * Usually owner privileges are required for this action to succeed.
       */
      void destroy( const std::string& reason = EmptyString,
                    const JID& alternate = JID(), const std::string& password = EmptyString );

      /**
       * Use this function to request a particluar list of room occupants.
       * @note There must be a MUCRoomConfigHandler registered with this room for this
       * function to be executed.
       * @param operation The following types of lists are available:
       * @li Voice List: List of people having voice in a moderated room. Use RequestVoiceList.
       * @li Members List: List of members of a room. Use RequestMemberList.
       * @li Ban List: List of people banned from the room. Use RequestBanList.
       * @li Moderator List: List of room moderators. Use RequestModeratorList.
       * @li Admin List: List of room admins. Use RequestAdminList.
       * @li Owner List: List of room owners. Use RequestOwnerList.
       * Any other value of @c operation will be ignored.
       */
      void requestList( MUCOperation operation );

      /**
       * Use this function to store a (modified) list for the room.
       * @param items The list of items. Example:<br>
       * You want to set the Voice List. The privilege of Voice refers to the role of Participant.
       * Furthermore, you only store the delta of the original (Voice)List. (Optionally, you could
       * probably store the whole list, however, remeber to include those items that were modified,
       * too.)
       * You want to, say, add one occupant to the Voice List, and remove another one.
       * Therefore you store:
       * @li GuyOne, role participant -- this guy gets voice granted, he/she is now a participant.
       * @li GuyTwo, role visitor -- this guy gets voice revoked, he/she is now a mere visitor
       * (Visitor is the Role "below" Participant in the privileges hierarchy).
       *
       * For operations modifying Roles, you should specifiy only the new Role in the MUCListItem
       * structure, for those modifying Affiliations, you should only specify the new Affiliation,
       * respectively. The nickname is mandatory in the MUCListItem structure. Items without nickname
       * will be ignored.
       *
       * You may specify a reason for the role/affiliation change in the MUCListItem structure.
       * You should not specify a JID in the MUCListItem structure, it will be ignored.
       *
       * @param operation See requestList() for a list of available list types. Any other value will
       * be ignored.
       */
      void storeList( const MUCListItemList items, MUCOperation operation );

      /**
       * Returns the currently known room flags.
       * @return ORed MUCRoomFlag's describing the current room configuration.
       */
      int flags() const { return m_flags; }

      // reimplemented from DiscoHandler
      virtual void handleDiscoInfo( const JID& from, const Disco::Info& info, int context );

      // reimplemented from DiscoHandler
      // reimplemented from DiscoHandler
      virtual void handleDiscoItems( const JID& from, const Disco::Items& items, int context );

      // reimplemented from DiscoHandler
      virtual void handleDiscoError( const JID& from, const Error* error, int context );

      // reimplemented from PresenceHandler
      virtual void handlePresence( const Presence& presence );

      // reimplemented from MessageHandler
      virtual void handleMessage( const Message& msg, MessageSession* session = 0 );

      // reimplemented from IqHandler
      virtual bool handleIq( const IQ& iq ) { (void)iq; return false; }

      // reimplemented from IqHandler
      virtual void handleIqID( const IQ& iq, int context );

      // reimplemented from DiscoNodeHandler
      virtual StringList handleDiscoNodeFeatures( const JID& from, const std::string& node );

      // reimplemented from DiscoNodeHandler
      virtual Disco::IdentityList handleDiscoNodeIdentities( const JID& from,
                                                             const std::string& node );

      // reimplemented from DiscoNodeHandler
      virtual Disco::ItemList handleDiscoNodeItems( const JID& from, const JID& to,
                                                    const std::string& node = EmptyString );

    protected:
      /**
       * Sets the room's name.
       * @param name The room's name.
       */
      void setName( const std::string& name ) { m_nick.setUsername( name ); }

      /**
       * Acknowledges instant room creation w/o a call to the MUCRoomConfigHandler.
       * @return Whether an instant room is being created.
       */
      virtual bool instantRoomHook() const { return false; }

      ClientBase* m_parent;
      JID m_nick;

      bool m_joined;

    private:
#ifdef MUCROOM_TEST
    public:
#endif
      /**
       * @brief An abstraction of a MUC owner query.
       *
       * @author Jakob Schroeter <js@camaya.net>
       * @since 1.0
       */
      class MUCOwner : public StanzaExtension
      {
        public:

          /**
           * Describes available query types for the muc#owner namespace.
           */
          enum QueryType
          {
            TypeCreate,             /**< Create a room. */
            TypeRequestConfig,      /**< Request room config. */
            TypeSendConfig,         /**< Submit configuration form to MUC service. */
            TypeCancelConfig,       /**< Cancel room configuration. */
            TypeInstantRoom,        /**< Request an instant room */
            TypeDestroy,            /**< Destroy the room. */
            TypeIncomingTag         /**< The Query has been created from an incoming Tag. */
          };

          /**
           * Creates a new MUCOwner object for the given query, possibly including
           * the given DataForm.
           * @param type The intended query type.
           * @param form An optional pointer to a DataForm. Necessity depends on the query type.
           */
          MUCOwner( QueryType type, DataForm* form = 0 );

          /**
           * Creates a new query that destroys the current room.
           * @param alternate An optional alternate discussion venue.
           * @param reason An optional reason for the room destruction.
           * @param password An optional password for the new room.
           */
          MUCOwner( const JID& alternate = JID(), const std::string& reason = EmptyString,
                    const std::string& password = EmptyString);

          /**
           * Creates a new MUCOwner object from the given Tag.
           * @param tag A Tag to parse.
           */
          MUCOwner( const Tag* tag );

          /**
           * Virtual destructor.
           */
          virtual ~MUCOwner();

          /**
           * Returns a pointer to a DataForm, included in the MUCOwner object. May be 0.
           * @return A pointer to a configuration form.
           */
          const DataForm* form() const { return m_form; }

          // reimplemented from StanzaExtension
          const std::string& filterString() const;

          // reimplemented from StanzaExtension
          StanzaExtension* newInstance( const Tag* tag ) const
          {
            return new MUCOwner( tag );
          }

          // reimplemented from StanzaExtension
          Tag* tag() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* clone() const
          {
            MUCOwner* m = new MUCOwner();
            m->m_type = m_type;
            m->m_jid = m_jid;
            m->m_reason = m_reason;
            m->m_pwd = m_pwd;
            m->m_form = m_form ? new DataForm( *m_form ) : 0;
            return m;
          }

        private:
          QueryType m_type;
          JID m_jid;
          std::string m_reason;
          std::string m_pwd;
          DataForm* m_form;
      };

      /**
       * @brief An abstraction of a MUC admin query.
       *
       * @author Jakob Schroeter <js@camaya.net>
       * @since 1.0
       */
      class MUCAdmin : public StanzaExtension
      {
        public:
          /**
           * Creates a new object that can be used to change the role of a room participant.
           * @param role The participant's new role.
           * @param nick The participant's nick.
           * @param reason An optional reason for the role change.
           */
          MUCAdmin( MUCRoomRole role, const std::string& nick,
                    const std::string& reason = EmptyString );

          /**
           * Creates a new object that can be used to change the affiliation of a room participant.
           * @param affiliation The participant's new affiliation.
           * @param nick The participant's nick.
           * @param reason An optional reason for the role change.
           */
          MUCAdmin( MUCRoomAffiliation affiliation, const std::string& nick,
                    const std::string& reason = EmptyString );

          /**
           * Creates a new object that can be used to request or store a role/affiliation
           * list.
           * @param operation The MUCOperation to carry out. Only the Request* and Store*
           * operations are valid. Any other value will be ignored.
           * @param jids A list of bare JIDs. Only the JID member of the MUCListItem
           * structure should be set. The type of the list will be determined from the
           * @c operation parameter.
           */
          MUCAdmin( MUCOperation operation, const MUCListItemList& jids = MUCListItemList() );

          /**
           * Constructs a new MUCAdmin object from the given Tag.
           * @param tag The Tag to parse.
           */
          MUCAdmin( const Tag* tag = 0 );

          /**
           * Virtual destructor.
           */
          virtual ~MUCAdmin();

          /**
           * Returns the contained list of MUC items.
           * @return The contained list of MUC items.
           */
          const MUCListItemList& list() const { return m_list; }

          // reimplemented from StanzaExtension
          const std::string& filterString() const;

          // reimplemented from StanzaExtension
          StanzaExtension* newInstance( const Tag* tag ) const
          {
            return new MUCAdmin( tag );
          }

          // reimplemented from StanzaExtension
          Tag* tag() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* clone() const
          {
            return new MUCAdmin( *this );
          }

        private:
          MUCListItemList m_list;
          MUCRoomAffiliation m_affiliation;
          MUCRoomRole m_role;
      };

      void handleIqResult( const IQ& iq, int context );
      void handleIqError( const IQ& iq, int context );
      void setNonAnonymous();
      void setSemiAnonymous();
      void setFullyAnonymous();
      void acknowledgeRoomCreation();
      void instantRoom( int context );

      MUCRoomHandler* m_roomHandler;
      MUCRoomConfigHandler* m_roomConfigHandler;
      MUCMessageSession* m_session;

      typedef std::list<MUCRoomParticipant> ParticipantList;
      ParticipantList m_participants;

      std::string m_password;
      std::string m_newNick;

      MUCRoomAffiliation m_affiliation;
      MUCRoomRole m_role;

      HistoryRequestType m_historyType;

      std::string m_historySince;
      int m_historyValue;
      int m_flags;
      bool m_creationInProgress;
      bool m_configChanged;
      bool m_publishNick;
      bool m_publish;
      bool m_unique;

  };

}

#endif // MUCROOM_H__