#include <mucroom.h>

Inheritance diagram for MUCRoom:

Classes
class	MUC
	An abstraction of a MUC query. More...
class	MUCUser
	An abstraction of a MUC user query. More...

Public Types
enum	HistoryRequestType { HistoryMaxChars, HistoryMaxStanzas, HistorySeconds, HistorySince, HistoryUnknown }
enum	MUCUserOperation { OpNone, OpInviteTo, OpInviteFrom, OpDeclineTo, OpDeclineFrom }

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 (Presence::PresenceType type=Presence::Available, const std::string &status=EmptyString, int priority=0)
void	leave (const std::string &msg=EmptyString)
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::PresenceType presence, const std::string &msg=EmptyString)
void	invite (const JID &invitee, const std::string &reason, const std::string &thread=EmptyString)
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=EmptyString)
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=EmptyString)
void	setAffiliation (const std::string &nick, MUCRoomAffiliation affiliation, const std::string &reason)
void	requestRoomConfig ()
void	setRoomConfig (DataForm *form)
void	acknowledgeInstantRoom ()
void	cancelRoomCreation ()
void	destroy (const std::string &reason=EmptyString, const JID &alternate=JID(), const std::string &password=EmptyString)
void	requestList (MUCOperation operation)
void	storeList (const MUCListItemList items, MUCOperation operation)
int	flags () const
Public Member Functions inherited from IqHandler
virtual	~IqHandler ()
virtual bool	handleIq (const IQ &iq)=0
virtual void	handleIqID (const IQ &iq, int context)=0

Static Public Member Functions
static Message *	declineInvitation (const JID &room, const JID &invitor, const std::string &reason=EmptyString)
static Message *	createDataForm (const JID &room, const DataForm *df)

Protected Member Functions
void	setName (const std::string &name)
virtual bool	instantRoomHook () const

Additional Inherited Members
Private Member Functions inherited from DiscoHandler
virtual	~DiscoHandler ()
virtual void	handleDiscoInfo (const JID &from, const Disco::Info &info, int context)=0
virtual void	handleDiscoItems (const JID &from, const Disco::Items &items, int context)=0
virtual void	handleDiscoError (const JID &from, const Error *error, int context)=0
virtual bool	handleDiscoSet (const IQ &iq)
Private Member Functions inherited from PresenceHandler
virtual	~PresenceHandler ()
virtual void	handlePresence (const Presence &presence)=0
Private Member Functions inherited from MessageHandler
virtual	~MessageHandler ()
virtual void	handleMessage (const Message &msg, MessageSession *session=0)=0
Private Member Functions inherited from DiscoNodeHandler
virtual	~DiscoNodeHandler ()
virtual StringList	handleDiscoNodeFeatures (const JID &from, const std::string &node)=0
virtual Disco::IdentityList	handleDiscoNodeIdentities (const JID &from, const std::string &node)=0
virtual Disco::ItemList	handleDiscoNodeItems (const JID &from, const JID &to, const std::string &node=EmptyString)=0

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@ca.nosp@m.maya.nosp@m..net

Since: 0.9

Definition at line 85 of file mucroom.h.

Member Enumeration Documentation

enum HistoryRequestType

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

Enumerator:

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.

Definition at line 93 of file mucroom.h.

enum MUCUserOperation

Available operations.

Enumerator:

OpNone	No operation.
OpInviteTo	Invitation being sent to soemone.
OpInviteFrom	Invitation received from someone.
OpDeclineTo	Someone's invitation declined.
OpDeclineFrom	Someone declined an invitation.

Definition at line 110 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 616 of file mucroom.cpp.

~MUCRoom ( )

virtual

Virtual Destructor.

Definition at line 634 of file mucroom.cpp.

Member Function Documentation

void acknowledgeInstantRoom ( )

inline

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 665 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 773 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 427 of file mucroom.h.

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

inline

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 582 of file mucroom.h.

void cancelRoomCreation ( )

inline

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 672 of file mucroom.h.

Message * 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. The form object will be owned by the returned Message.

Definition at line 797 of file mucroom.cpp.

Message * declineInvitation	(	const JID &	room,
		const JID &	invitor,
		const std::string &	reason = `EmptyString`
	)

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.

Returns: A pointer to a Message. You will have to send (and possibly delete) this Message manually.

Definition at line 752 of file mucroom.cpp.

void destroy	(	const std::string &	reason = `EmptyString`,
		const JID &	alternate = `JID()`,
		const std::string &	password = `EmptyString`
	)

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 685 of file mucroom.cpp.

int flags ( ) const

inline

Returns the currently known room flags.

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

Definition at line 732 of file mucroom.h.

void getRoomInfo ( )

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

Definition at line 721 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 727 of file mucroom.cpp.

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

inline

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 594 of file mucroom.h.

virtual bool instantRoomHook ( ) const

inlineprotectedvirtual

Acknowledges instant room creation w/o a call to the MUCRoomConfigHandler.

Returns: Whether an instant room is being created.

Reimplemented in InstantMUCRoom.

Definition at line 778 of file mucroom.h.

void invite	(	const JID &	invitee,
		const std::string &	reason,
		const std::string &	thread = `EmptyString`
	)

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.
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).

Definition at line 742 of file mucroom.cpp.

void join	(	Presence::PresenceType	type = `Presence::Available`,
		const std::string &	status = `EmptyString`,
		int	priority = `0`
	)

virtual

Join this room.

Parameters

type	The presence to join with, defaults to Available.
status	The presence's optional status text.
priority	The presence's optional priority, defaults to 0. ClientBase will automatically include the default Presence extensions added using ClientBase::addPresenceExtension() .

Definition at line 652 of file mucroom.cpp.

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

inline

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 570 of file mucroom.h.

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

Leave this room.

Parameters

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

Definition at line 668 of file mucroom.cpp.

const std::string name ( ) const

inline

A convenience function that returns the room's name.

Returns: The room's name.

Definition at line 376 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 389 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 503 of file mucroom.h.

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 491 of file mucroom.h.

void removeMUCRoomConfigHandler ( )

inline

Use this function to remove the registered MUCRoomConfigHandler.

Definition at line 508 of file mucroom.h.

void removeMUCRoomHandler ( )

inline

Use this function to remove the registered MUCRoomHandler.

Definition at line 496 of file mucroom.h.

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 884 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.

Use setRoomConfig() to send the modified room config back.

Definition at line 992 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 804 of file mucroom.cpp.

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

inline

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 617 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 433 of file mucroom.h.

void send ( const std::string & message )

Sends a chat message to the room.

Parameters

message The message to send.

Definition at line 696 of file mucroom.cpp.

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 383 of file mucroom.h.

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 850 of file mucroom.cpp.

void setName ( const std::string & name )

inlineprotected

Sets the room's name.

Parameters

name	The room's name.

Definition at line 772 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 708 of file mucroom.cpp.

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 370 of file mucroom.h.

void setPresence	(	Presence::PresenceType	presence,
		const std::string &	msg = `EmptyString`
	)

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

Parameters

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

Definition at line 733 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 759 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 783 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 790 of file mucroom.cpp.

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

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 819 of file mucroom.cpp.

void setRoomConfig ( DataForm * form )

After requesting (using requestRoomConfig()) and editing/filling in the room's configuration, use this function to send it back to the server.

Parameters

form	The form to send. The function will delete the object pointed to.

Definition at line 1006 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 702 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 894 of file mucroom.cpp.

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation