gloox
1.0.28
|
#include <mucroom.h>
Classes | |
class | MUC |
class | MUCUser |
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 | send (const std::string &message, const std::string &subject, const StanzaExtensionList &sel=StanzaExtensionList()) |
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 |
virtual void | handleDiscoInfo (const JID &from, const Disco::Info &info, int context) |
virtual void | handleDiscoItems (const JID &from, const Disco::Items &items, int context) |
virtual void | handleDiscoError (const JID &from, const Error *error, int context) |
virtual void | handlePresence (const Presence &presence) |
virtual void | handleMessage (const Message &msg, MessageSession *session=0) |
virtual bool | handleIq (const IQ &iq) |
virtual void | handleIqID (const IQ &iq, int context) |
virtual StringList | handleDiscoNodeFeatures (const JID &from, const std::string &node) |
virtual Disco::IdentityList | handleDiscoNodeIdentities (const JID &from, const std::string &node) |
virtual Disco::ItemList | handleDiscoNodeItems (const JID &from, const JID &to, const std::string &node=EmptyString) |
Public Member Functions inherited from IqHandler | |
virtual | ~IqHandler () |
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 |
This is an implementation of XEP-0045 (Multi-User Chat).
Usage is pretty simple:
Derrive an object from MUCRoomHandler and implement its virtuals:
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.
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
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. |
enum MUCUserOperation |
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.
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 619 of file mucroom.cpp.
|
virtual |
Virtual Destructor.
Definition at line 637 of file mucroom.cpp.
|
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.
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.
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 |
Definition at line 782 of file mucroom.cpp.
|
inline |
|
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.
nick | The nick of the user to be banned. |
reason | An optional reason for the ban. |
|
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.
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.
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 806 of file mucroom.cpp.
|
static |
This static function allows to formally decline a MUC invitation received via the MUCInvitationListener.
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 761 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.
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 688 of file mucroom.cpp.
|
inline |
void getRoomInfo | ( | ) |
Use this function to request basic room info, possibly prior to joining it. Results are announced using the MUCRoomHandler.
Definition at line 730 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 736 of file mucroom.cpp.
|
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.
nick | The nick of the user to be granted voice. |
reason | An optional reason for the grant. |
Reimplement this function to receive disco error notifications.
from | The sender of the error result. |
error | The Error. May be 0. |
context | A context identifier. |
Implements DiscoHandler.
Definition at line 1287 of file mucroom.cpp.
|
virtual |
Reimplement this function if you want to be notified about the result of an disco::info query.
from | The sender of the disco::info result. |
info | The Info. |
context | A context identifier. |
Implements DiscoHandler.
Definition at line 1213 of file mucroom.cpp.
|
virtual |
Reimplement this function if you want to be notified about the result of a disco::items query.
from | The sender of the disco::items result. |
items | The Items. |
context | A context identifier. |
Implements DiscoHandler.
Definition at line 1270 of file mucroom.cpp.
|
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.
from | The sender of the request. |
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
Definition at line 1305 of file mucroom.cpp.
|
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.
from | The sender of the request. |
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
Definition at line 1310 of file mucroom.cpp.
|
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.
from | The sender of the request. |
to | The receiving JID (useful for transports). |
node | The node this handler is supposed to handle. |
Implements DiscoNodeHandler.
Definition at line 1316 of file mucroom.cpp.
|
inlinevirtual |
Reimplement this function if you want to be notified about incoming IQs.
iq | The complete IQ stanza. |
Implements IqHandler.
|
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 empty positive reply, i.e. <iq type='result' id='reg'/> where a namespace filter wouldn't work.
iq | The complete IQ stanza. |
context | A value to restore context, stored with ClientBase::trackID(). |
Implements IqHandler.
Definition at line 1107 of file mucroom.cpp.
|
virtual |
Reimplement this function if you want to be notified about incoming messages.
msg | The complete Message. |
session | If this MessageHandler is used with a MessageSession, this parameter holds a pointer to that MessageSession. |
Implements MessageHandler.
Definition at line 1044 of file mucroom.cpp.
|
virtual |
Reimplement this function if you want to be updated on incoming presence notifications.
presence | The complete stanza. |
Implements PresenceHandler.
Definition at line 913 of file mucroom.cpp.
|
inlineprotectedvirtual |
Acknowledges instant room creation w/o a call to the MUCRoomConfigHandler.
Reimplemented in InstantMUCRoom.
void invite | ( | const JID & | invitee, |
const std::string & | reason, | ||
const std::string & | thread = EmptyString |
||
) |
Use this function to invite another user to this room.
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 751 of file mucroom.cpp.
|
virtual |
Join this room.
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 655 of file mucroom.cpp.
|
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.
nick | The nick of the user to be kicked. |
reason | An optional reason for the kick. |
void leave | ( | const std::string & | msg = EmptyString | ) |
Leave this room.
msg | An optional msg indicating the reason for leaving the room. Default: empty. |
Definition at line 671 of file mucroom.cpp.
|
inline |
|
inline |
|
inline |
Use this function to register a (new) MUCRoomConfigHandler with this room. There can be only one MUCRoomConfigHandler per room at any one time.
mrch | The MUCRoomConfigHandler to register. |
|
inline |
Use this function to register a (new) MUCRoomHandler with this room. There can be only one MUCRoomHandler per room at any one time.
mrl | The MUCRoomHandler to register. |
|
inline |
Use this function to remove the registered MUCRoomConfigHandler.
|
inline |
Use this function to remove the registered MUCRoomHandler.
void requestList | ( | MUCOperation | operation | ) |
Use this function to request a particluar list of room occupants.
operation | The following types of lists are available:
|
Definition at line 893 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 1001 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 813 of file mucroom.cpp.
|
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.
nick | The nick of the user. |
reason | An optional reason for the revoke. |
|
inline |
void send | ( | const std::string & | message | ) |
Sends a chat message to the room.
message | The message to send. |
Definition at line 699 of file mucroom.cpp.
void send | ( | const std::string & | message, |
const std::string & | subject, | ||
const StanzaExtensionList & | sel = StanzaExtensionList() |
||
) |
Sends a chat message to the room, including the given subject and list of StanzaExtensions.
message | The message's text/content |
subject | The message's subject |
sel | The list of StanzaExtensions to include. |
Definition at line 705 of file mucroom.cpp.
|
inline |
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.
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 859 of file mucroom.cpp.
|
inlineprotected |
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.
nick | The user's new nickname. |
Definition at line 717 of file mucroom.cpp.
|
inline |
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.
presence | The user's new presence. |
msg | An optional status message. Default: empty. |
Definition at line 742 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.
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 768 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.
since | A string representing a datetime conforming to the DateTime profile specified in Jabber Date and Time Profiles (XEP-0082). |
Definition at line 799 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.
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 |
Definition at line 792 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.
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 828 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.
form | The form to send. The function will delete the object pointed to. |
Definition at line 1015 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.
subject | The new subject. |
Definition at line 711 of file mucroom.cpp.
void storeList | ( | const MUCListItemList | items, |
MUCOperation | operation | ||
) |
Use this function to store a (modified) list for the room.
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:
|
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.
operation | See requestList() for a list of available list types. Any other value will be ignored. |
Definition at line 903 of file mucroom.cpp.