MUCRoom Class Reference

This is an implementation of XEP-0045 (Multi-User Chat). More...

#include <mucroom.h>

Inheritance diagram for MUCRoom:

Inheritance graph
[legend]
Collaboration diagram for MUCRoom:

Collaboration graph
[legend]

List of all members.

Public Types

enum  HistoryRequestType {
  HistoryUnknown, HistoryMaxChars, HistoryMaxStanzas, HistorySeconds,
  HistorySince
}

Public Member Functions

 MUCRoom (ClientBase *parent, const JID &nick, MUCRoomHandler *mrh, MUCRoomConfigHandler *mrch=0)
virtual ~MUCRoom ()
void setPassword (const std::string &password)
const std::string name () const
const std::string service () const
const std::string nick () const
virtual void join ()
void leave (const std::string &msg="")
void send (const std::string &message)
void setSubject (const std::string &subject)
MUCRoomAffiliation affiliation () const
MUCRoomRole role () const
void setNick (const std::string &nick)
void setPresence (Presence presence, const std::string &msg="")
void invite (const JID &invitee, const std::string &reason, bool cont=false)
void getRoomInfo ()
void getRoomItems ()
void setPublish (bool publish, bool publishNick)
void registerMUCRoomHandler (MUCRoomHandler *mrl)
void removeMUCRoomHandler ()
void registerMUCRoomConfigHandler (MUCRoomConfigHandler *mrch)
void removeMUCRoomConfigHandler ()
void addHistory (const std::string &message, const JID &from, const std::string &stamp)
void setRequestHistory (int value, HistoryRequestType type)
void setRequestHistory (const std::string &since)
void requestVoice ()
void kick (const std::string &nick, const std::string &reason="")
void ban (const std::string &nick, const std::string &reason)
void grantVoice (const std::string &nick, const std::string &reason)
void revokeVoice (const std::string &nick, const std::string &reason)
void setRole (const std::string &nick, MUCRoomRole role, const std::string &reason="")
void setAffiliation (const std::string &nick, MUCRoomAffiliation affiliation, const std::string &reason)
void requestRoomConfig ()
void acknowledgeInstantRoom ()
void cancelRoomCreation ()
void destroy (const std::string &reason="", const JID *alternate=0, const std::string &password="")
void requestList (MUCOperation operation)
void storeList (const MUCListItemList items, MUCOperation operation)
int flags () const
virtual void handleDiscoInfoResult (Stanza *stanza, int context)
virtual void handleDiscoItemsResult (Stanza *stanza, int context)
virtual void handleDiscoError (Stanza *stanza, int context)
virtual void handlePresence (Stanza *stanza)
virtual void handleMessage (Stanza *stanza, MessageSession *session=0)
virtual bool handleIq (Stanza *)
virtual bool handleIqID (Stanza *stanza, int context)
virtual StringList handleDiscoNodeFeatures (const std::string &node)
virtual StringMap handleDiscoNodeIdentities (const std::string &node, std::string &name)
virtual DiscoNodeItemList handleDiscoNodeItems (const std::string &node="")

Static Public Member Functions

static StanzadeclineInvitation (const JID &room, const JID &invitor, const std::string &reason="")
static StanzacreateDataForm (const JID &room, const DataForm &df)


Detailed Description

This is an implementation of XEP-0045 (Multi-User Chat).

Usage is pretty simple:

Derrive an object from MUCRoomHandler and implement its virtuals:

 class MyClass : public MUCRoomHandler
 {
   ...
 };

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.

 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();
 }

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 gloox::MessageSession with the participant's full room JID (room@service/nick).

XEP version: 1.21

Author:
Jakob Schroeter <js@camaya.net>
Since:
0.9

Definition at line 83 of file mucroom.h.


Member Enumeration Documentation

Allowable history request types. To disable sending of history, use any value except HistoryUnknown and specify a zero-length time span (using setRequestHistory()).

Enumerator:
HistoryUnknown  It is up to the service to decide how much history to send. This is the default.
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)).

Definition at line 91 of file mucroom.h.


Constructor & Destructor Documentation

MUCRoom ( ClientBase parent,
const JID nick,
MUCRoomHandler mrh,
MUCRoomConfigHandler mrch = 0 
)

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.

Parameters:
parent The ClientBase object to use for the communication.
nick The room's name and service plus the desired nickname in the form room@service/nick.
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.
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().

Definition at line 25 of file mucroom.cpp.

~MUCRoom (  )  [virtual]

Virtual Destructor.

Definition at line 35 of file mucroom.cpp.


Member Function Documentation

void setPassword ( const std::string &  password  )  [inline]

Use this function to set a password to use when joining a (password protected) room.

Parameters:
password The password to use for this room.
Note:
This function does not password-protect a room.

Definition at line 130 of file mucroom.h.

const std::string name (  )  const [inline]

A convenience function that returns the room's name.

Returns:
The room's name.

Definition at line 136 of file mucroom.h.

const std::string service (  )  const [inline]

A convenience function that returns the name/address of the MUC service the room is running on (e.g., conference.jabber.org).

Returns:
The MUC service's name/address.

Definition at line 143 of file mucroom.h.

const std::string nick (  )  const [inline]

A convenience function that returns the user's nickname in the room.

Returns:
The user's nickname.

Definition at line 149 of file mucroom.h.

void join (  )  [virtual]

Join this room.

Reimplemented in UniqueMUCRoom.

Definition at line 49 of file mucroom.cpp.

void leave ( const std::string &  msg = ""  ) 

Leave this room.

Parameters:
msg An optional msg indicating the reason for leaving the room. Default: empty.

Definition at line 103 of file mucroom.cpp.

void send ( const std::string &  message  ) 

Sends a chat message to the room.

Parameters:
message The message to send.

Definition at line 148 of file mucroom.cpp.

void setSubject ( const std::string &  subject  ) 

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.

Parameters:
subject The new subject.

Definition at line 154 of file mucroom.cpp.

MUCRoomAffiliation affiliation (  )  const [inline]

Returns the user's current affiliation with this room.

Returns:
The user's current affiliation.

Definition at line 180 of file mucroom.h.

MUCRoomRole role (  )  const [inline]

Returns the user's current role in this room.

Returns:
The user's current role.

Definition at line 186 of file mucroom.h.

void setNick ( const std::string &  nick  ) 

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.

Parameters:
nick The user's new nickname.

Definition at line 160 of file mucroom.cpp.

void setPresence ( Presence  presence,
const std::string &  msg = "" 
)

Use this function to set the user's presence in this room. It is not possible to use PresenceUnavailable with this function.

Parameters:
presence The user's new presence.
msg An optional status message. Default: empty.

Definition at line 192 of file mucroom.cpp.

void invite ( const JID invitee,
const std::string &  reason,
bool  cont = false 
)

Use this function to invite another user to this room.

Parameters:
invitee The (bare) JID of the user to invite.
reason The user-supplied reason for the invitation.
cont Whether this invitation is part of a transformation of a one-to-one chat to a MUC. Default: false.

Definition at line 201 of file mucroom.cpp.

void getRoomInfo (  ) 

Use this function to request basic room info, possibly prior to joining it. Results are announced using the MUCRoomHandler.

Definition at line 174 of file mucroom.cpp.

void getRoomItems (  ) 

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.

Definition at line 183 of file mucroom.cpp.

void setPublish ( bool  publish,
bool  publishNick 
)

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 this room.

Parameters:
publish Whether to enable other entities to discover the user's presence in this room.
publishNick Whether to publish the nickname used in the room. This parameter is ignored if publish is false.

Definition at line 234 of file mucroom.cpp.

void registerMUCRoomHandler ( MUCRoomHandler mrl  )  [inline]

Use this function to register a (new) MUCRoomHandler with this room. There can be only one MUCRoomHandler per room at any one time.

Parameters:
mrl The MUCRoomHandler to register.

Definition at line 243 of file mucroom.h.

void removeMUCRoomHandler (  )  [inline]

Use this function to remove the registered MUCRoomHandler.

Definition at line 248 of file mucroom.h.

void registerMUCRoomConfigHandler ( MUCRoomConfigHandler mrch  )  [inline]

Use this function to register a (new) MUCRoomConfigHandler with this room. There can be only one MUCRoomConfigHandler per room at any one time.

Parameters:
mrch The MUCRoomConfigHandler to register.

Definition at line 255 of file mucroom.h.

void removeMUCRoomConfigHandler (  )  [inline]

Use this function to remove the registered MUCRoomConfigHandler.

Definition at line 260 of file mucroom.h.

void addHistory ( const std::string &  message,
const JID from,
const std::string &  stamp 
)

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.

Parameters:
message A reason for declining the invitation.
from The JID of the original author of this part of the history.
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.

Definition at line 248 of file mucroom.cpp.

void setRequestHistory ( int  value,
MUCRoom::HistoryRequestType  type 
)

Use this function to request room history. Set 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.

Parameters:
value Represents either the number of requested characters, the number of requested message stanzas, or the number seconds, depending on the value of type.
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.

Definition at line 265 of file mucroom.cpp.

void setRequestHistory ( const std::string &  since  ) 

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.

Parameters:
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.

Definition at line 272 of file mucroom.cpp.

Stanza * declineInvitation ( const JID room,
const JID invitor,
const std::string &  reason = "" 
) [static]

This static function allows to formally decline a MUC invitation received via the MUCInvitationListener.

Parameters:
room The JID of the room the invitation came from.
invitor The JID of the invitor.
reason An optional reason for the decline.

Definition at line 220 of file mucroom.cpp.

void requestVoice (  ) 

It is not possible for a visitor to speak in a moderated room. Use this function to request voice from the moderator.

Definition at line 288 of file mucroom.cpp.

void kick ( const std::string &  nick,
const std::string &  reason = "" 
)

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.
Parameters:
nick The nick of the user to be kicked.
reason An optional reason for the kick.

Definition at line 311 of file mucroom.cpp.

void ban ( const std::string &  nick,
const std::string &  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.
Parameters:
nick The nick of the user to be banned.
reason An optional reason for the ban.

Definition at line 326 of file mucroom.cpp.

void grantVoice ( const std::string &  nick,
const std::string &  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.
Parameters:
nick The nick of the user to be granted voice.
reason An optional reason for the grant.

Definition at line 316 of file mucroom.cpp.

Stanza * createDataForm ( const JID room,
const DataForm df 
) [static]

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.

Parameters:
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).
df The filled-in DataForm from the voice/registration request.

Definition at line 279 of file mucroom.cpp.

void revokeVoice ( const std::string &  nick,
const std::string &  reason 
)

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.
Parameters:
nick The nick of the user.
reason An optional reason for the revoke.

Definition at line 321 of file mucroom.cpp.

void setRole ( const std::string &  nick,
MUCRoomRole  role,
const std::string &  reason = "" 
)

Use this function to change the role of a user in the room. Usually, at least moderator privileges are required to succeed.

Parameters:
nick The nick of the user who's role shall be modfified.
role The user's new role in the room.
reason An optional reason for the role change.

Definition at line 331 of file mucroom.cpp.

void setAffiliation ( const std::string &  nick,
MUCRoomAffiliation  affiliation,
const std::string &  reason 
)

Use this function to change the affiliation of a user in the room. Usually, at least admin privileges are required to succeed.

Parameters:
nick The nick of the user who's affiliation shall be modfified.
affiliation The user's new affiliation in the room.
reason An optional reason for the affiliation change.

Definition at line 336 of file mucroom.cpp.

void requestRoomConfig (  ) 

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.

Definition at line 690 of file mucroom.cpp.

void acknowledgeInstantRoom (  ) 

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.

Definition at line 652 of file mucroom.cpp.

void cancelRoomCreation (  ) 

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.

Definition at line 671 of file mucroom.cpp.

void destroy ( const std::string &  reason = "",
const JID alternate = 0,
const std::string &  password = "" 
)

Use this function to destroy the room. All the occupants will be removed from the room.

Parameters:
reason An optional reason for the destruction.
alternate A pointer to a JID of an alternate venue (e.g., another MUC room). May be 0.
password An optional password for the alternate venue.
Usually owner privileges are required for this action to succeed.

Definition at line 124 of file mucroom.cpp.

void requestList ( MUCOperation  operation  ) 

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.
Parameters:
operation The following types of lists are available:
  • Voice List: List of people having voice in a moderated room. Use RequestVoiceList.
  • Members List: List of members of a room. Use RequestMemberList.
  • Ban List: List of people banned from the room. Use RequestBanList.
  • Moderator List: List of room moderators. Use RequestModeratorList.
  • Admin List: List of room admins. Use RequestAdminList.
  • Owner List: List of room owners. Use RequestOwnerList. Any other value of operation will be ignored.

Definition at line 412 of file mucroom.cpp.

void storeList ( const MUCListItemList  items,
MUCOperation  operation 
)

Use this function to store a (modified) list for the room.

Parameters:
items The list of items. Example:
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:
  • GuyOne, role participant -- this guy gets voice granted, he/she is now a participant.
  • 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.

Parameters:
operation See requestList() for a list of available list types. Any other value will be ignored.

Definition at line 453 of file mucroom.cpp.

int flags (  )  const [inline]

Returns the currently know room flags.

Returns:
ORed MUCRoomFlag's describing the current room configuration.

Definition at line 463 of file mucroom.h.

void handleDiscoInfoResult ( Stanza stanza,
int  context 
) [virtual]

Reimplement this function if you want to be notified about the result of an disco::info query.

Parameters:
stanza The full Stanza.
context A context identifier.
Todo:
Replace the stanza with decoded values.

Implements DiscoHandler.

Definition at line 949 of file mucroom.cpp.

void handleDiscoItemsResult ( Stanza stanza,
int  context 
) [virtual]

Reimplement this function if you want to be notified about the result of an disco::items query.

Parameters:
stanza The full Stanza.
context A context identifier.
Todo:
Replace the stanza with decoded values.

Implements DiscoHandler.

Definition at line 1017 of file mucroom.cpp.

void handleDiscoError ( Stanza stanza,
int  context 
) [virtual]

Reimplement this function to receive disco error notifications.

Parameters:
stanza The full Stanza.
context A context identifier.
Todo:
Replace the stanza with decoded values.

Implements DiscoHandler.

Definition at line 1048 of file mucroom.cpp.

void handlePresence ( Stanza stanza  )  [virtual]

Reimplement this function if you want to be updated on incoming presence notifications.

Parameters:
stanza The complete stanza.

Implements PresenceHandler.

Definition at line 516 of file mucroom.cpp.

void handleMessage ( Stanza stanza,
MessageSession session = 0 
) [virtual]

Reimplement this function if you want to be notified about incoming messages.

Parameters:
stanza The complete Stanza.
session If this MessageHandler is used with a MessageSession, this parameter holds a pointer to that MessageSession.

Implements MessageHandler.

Definition at line 727 of file mucroom.cpp.

virtual bool handleIq ( Stanza stanza  )  [inline, virtual]

Reimplement this function if you want to be notified about incoming IQs.

Parameters:
stanza The complete Stanza.
Returns:
Indicates whether a request of type 'get' or 'set' has been handled. This includes the obligatory 'result' answer. If you return false, a 'error' will be sent.

Implements IqHandler.

Definition at line 481 of file mucroom.h.

bool handleIqID ( Stanza stanza,
int  context 
) [virtual]

Reimplement this function if you want to be notified about incoming IQs with a specific value of the id attribute. You have to enable tracking of those IDs using Client::trackID(). This is usually useful for IDs that generate a positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.

Parameters:
stanza The complete Stanza.
context A value to restore context, stored with ClientBase::trackID().
Returns:
Indicates whether a request of type 'get' or 'set' has been handled. This includes the obligatory 'result' answer. If you return false, a 'error' will be sent.

Implements IqHandler.

Definition at line 816 of file mucroom.cpp.

StringList handleDiscoNodeFeatures ( const std::string &  node  )  [virtual]

In addition to handleDiscoNodeIdentities, this function is used to gather more information on a specific node. It is called when a disco::info query arrives with a node attribute that matches the one registered for this handler.

Parameters:
node The node this handler is supposed to handle.
Returns:
A list of features supported by this node.

Implements DiscoNodeHandler.

Definition at line 1069 of file mucroom.cpp.

StringMap handleDiscoNodeIdentities ( const std::string &  node,
std::string &  name 
) [virtual]

In addition to handleDiscoNodeFeatures, this function is used to gather more information on a specific node. It is called when a disco::info query arrives with a node attribute that matches the one registered for this handler.

Parameters:
node The node this handler is supposed to handle.
name This parameter is currently used as additional return value. Just fill in the name of the node.
Returns:
A map of identities for the given node. The first string is the category specifier, the second string is the type specifier.

Implements DiscoNodeHandler.

Definition at line 1074 of file mucroom.cpp.

DiscoNodeItemList handleDiscoNodeItems ( const std::string &  node = ""  )  [virtual]

This function is used to gather more information on a specific node. It is called when a disco::items query arrives with a node attribute that matches the one registered for this handler. If node is empty, items for the root node (no node) shall be returned.

Parameters:
node The node this handler is supposed to handle.
Returns:
A list of items supported by this node.

Implements DiscoNodeHandler.

Definition at line 1079 of file mucroom.cpp.


The documentation for this class was generated from the following files:

Generated on Sun Apr 27 11:08:25 2008 for gloox by  doxygen 1.5.5