1 /* 2 Copyright (c) 2006-2019 by Jakob Schröter <js@camaya.net> 3 This file is part of the gloox library. http://camaya.net/gloox 4 5 This software is distributed under a license. The full license 6 agreement can be found in the file LICENSE in this distribution. 7 This software may not be copied, modified, sold or distributed 8 other than expressed in the named license agreement. 9 10 This software is distributed without any warranty. 11 */ 12 13 14 15 #ifndef MUCROOMHANDLER_H__ 16 #define MUCROOMHANDLER_H__ 17 18 #include "gloox.h" 19 #include "presence.h" 20 #include "disco.h" 21 22 #include <string> 23 24 namespace gloox 25 { 26 27 class JID; 28 class MUCRoom; 29 class Message; 30 class DataForm; 31 32 /** 33 * Describes a participant in a MUC room. 34 */ 35 struct MUCRoomParticipant 36 { 37 JID* nick; /**< Pointer to a JID holding the participant's full JID 38 * in the form @c room\@service/nick. <br> 39 * @note The MUC server @b may change the chosen nickname. 40 * If the @b self member of this struct is true, one should 41 * check the resource of this member if the actual nickname 42 * is important. */ 43 MUCRoomAffiliation affiliation; /**< The participant's affiliation with the room. */ 44 MUCRoomRole role; /**< The participant's role with the room. */ 45 JID* jid; /**< Pointer to the occupant's full JID in a non-anonymous room or 46 * in a semi-anonymous room if the user (of gloox) has a role of 47 * moderator. 48 * 0 if the MUC service doesn't provide the JID. */ 49 int flags; /**< ORed MUCUserFlag values. Indicate conditions like: user has 50 * been kicked or banned from the room. Also may indicate that 51 * this struct refers to this instance's user. 52 * (MUC servers send presence to all room occupants, including 53 * the originator of the presence.) */ 54 std::string reason; /**< If the presence change is the result of an action where the 55 * actor can provide a reason for the action, this reason is stored 56 * here. Examples: Kicking, banning, leaving the room. */ 57 JID* actor; /**< If the presence change is the result of an action of a room 58 * member, a pointer to the actor's JID is stored here, if the 59 * actor chose to disclose his or her identity. Examples: Kicking 60 * and banning. 61 * 0 if the identity is not disclosed. */ 62 std::string newNick; /**< In case of a nickname change, this holds the new nick, while the 63 * nick member holds the old room nick (in JID form). @c newNick is only 64 * set if @c flags contains @b UserNickChanged. If @c flags contains 65 * @b UserSelf as well, a foregoing nick change request (using 66 * MUCRoom::setNick()) can be considered acknowledged. In any case 67 * the user's presence sent with the nick change acknowledgement 68 * is of type @c unavailable. Another presence of type @c available 69 * (or whatever the user's presence was at the time of the nick change 70 * request) will follow (not necessarily immediately) coming from the 71 * user's new nickname. Empty if there is no nick change in progress. */ 72 std::string status; /**< If the presence packet contained a status message, it is stored 73 * here. */ 74 JID* alternate; /**< If @c flags contains UserRoomDestroyed, and if the user who 75 * destroyed the room specified an alternate room, this member holds 76 * a pointer to the alternate room's JID, else it is 0. */ 77 }; 78 79 /** 80 * @brief This interface enables inheriting classes to be notified about certain events in a MUC room. 81 * 82 * See MUCRoom for examples how to use this interface. 83 * 84 * @note This interface does not notify about room configuration related events. Use 85 * MUCRoomConfigHandler for that puprose. 86 * 87 * @author Jakob Schröter <js@camaya.net> 88 * @since 0.9 89 */ 90 class GLOOX_API MUCRoomHandler 91 { 92 public: 93 /** 94 * Virtual Destructor. 95 */ ~MUCRoomHandler()96 virtual ~MUCRoomHandler() {} 97 98 /** 99 * This function is called whenever a room occupant enters the room, changes presence 100 * inside the room, or leaves the room. 101 * @note The MUCRoomParticipant struct, including pointers to JIDs, will be cleaned up after 102 * this function returned. 103 * @param room The room. 104 * @param participant A struct describing the occupant's status and/or action. 105 * @param presence The occupant's full presence. 106 */ 107 virtual void handleMUCParticipantPresence( MUCRoom* room, const MUCRoomParticipant participant, 108 const Presence& presence ) = 0; 109 110 /** 111 * This function is called when a message arrives through the room. 112 * @note This may be a private message! If the message is private, and you want to answer 113 * it privately, you should create a new MessageSession to the user's full room nick and use 114 * that for any further private communication with the user. 115 * @param room The room the message came from. 116 * @param msg The entire Message. 117 * @param priv Indicates whether this is a private message. 118 * @note The sender's nick name can be obtained with this call: 119 * @code 120 * const std::string nick = msg.from().resource(); 121 * @endcode 122 * @note The message may contain an extension of type DelayedDelivery describing the 123 * date/time when the message was originally sent. The presence of such an extension 124 * usually indicates that the message is sent as part of the room history. This extension 125 * can be obtained with this call: 126 * @code 127 * const DelayedDelivery* dd = msg.when(); // may be 0 if no such extension exists 128 * @endcode 129 */ 130 virtual void handleMUCMessage( MUCRoom* room, const Message& msg, bool priv ) = 0; 131 132 /** 133 * This function is called if the room that was just joined didn't exist prior to the attempted 134 * join. Therfore the room was created by MUC service. To accept the default configuration of 135 * the room assigned by the MUC service, return @b true from this function. The room will be opened 136 * by the MUC service and available for other users to join. If you don't want to accept the default 137 * room configuration, return @b false from this function. The room will stay locked until it is 138 * either fully configured, created as an instant room, or creation is canceled. 139 * 140 * If you returned false from this function you should use one of the following options: 141 * @li use MUCRoom::cancelRoomCreation() to abort creation and delete the room, 142 * @li use MUCRoom::acknowledgeInstantRoom() to accept the room's default configuration, or 143 * @li use MUCRoom::requestRoomConfig() to request the room's configuration form. 144 * 145 * @param room The room. 146 * @return @b True to accept the default room configuration, @b false to keep the room locked 147 * until configured manually by the room owner. 148 */ 149 virtual bool handleMUCRoomCreation( MUCRoom* room ) = 0; 150 151 /** 152 * This function is called when the room subject has been changed. 153 * @param room The room. 154 * @param nick The nick of the occupant that changed the room subject. 155 * @note With some MUC services the nick may be empty when a room is first entered. 156 * @param subject The new room subject. 157 */ 158 virtual void handleMUCSubject( MUCRoom* room, const std::string& nick, 159 const std::string& subject ) = 0; 160 161 /** 162 * This function is called when the user invited somebody (e.g., by using MUCRoom::invite()) 163 * to the room, but the invitation was declined by that person. 164 * @param room The room. 165 * @param invitee The JID if the person that declined the invitation. 166 * @param reason An optional reason for declining the invitation. 167 */ 168 virtual void handleMUCInviteDecline( MUCRoom* room, const JID& invitee, 169 const std::string& reason ) = 0; 170 171 /** 172 * This function is called when an error occurs in the room or when entering the room. 173 * @note The following error conditions are specified for MUC: 174 * @li @b Not @b Authorized: Password required. 175 * @li @b Forbidden: Access denied, user is banned. 176 * @li @b Item @b Not @b Found: The room does not exist. 177 * @li @b Not @b Allowed: Room creation is restricted. 178 * @li @b Not @b Acceptable: Room nicks are locked down. 179 * @li @b Registration @b Required: User is not on the member list. 180 * @li @b Conflict: Desired room nickname is in use or registered by another user. 181 * @li @b Service @b Unavailable: Maximum number of users has been reached. 182 * 183 * Other errors might appear, depending on the service implementation. 184 * @param room The room. 185 * @param error The error. 186 */ 187 virtual void handleMUCError( MUCRoom* room, StanzaError error ) = 0; 188 189 /** 190 * This function usually (see below) is called in response to a call to MUCRoom::getRoomInfo(). 191 * @param room The room. 192 * @param features ORed MUCRoomFlag's. 193 * @param name The room's name as returned by Service Discovery. 194 * @param infoForm A DataForm containing extended room information. May be 0 if the service 195 * doesn't support extended room information. See Section 15.5 of @xep{0045} for defined 196 * field types. You should not delete the form. 197 * 198 * @note This function may be called without a prior call to MUCRoom::getRoomInfo(). This 199 * happens if the room config is changed, e.g. by a room admin. 200 */ 201 virtual void handleMUCInfo( MUCRoom* room, int features, const std::string& name, 202 const DataForm* infoForm ) = 0; 203 204 /** 205 * This function is called in response to a call to MUCRoom::getRoomItems(). 206 * @param room The room. 207 * @param items A map of room participants. The key is the name, the value is the occupant's 208 * room JID. The map may be empty if such info is private. 209 */ 210 virtual void handleMUCItems( MUCRoom* room, const Disco::ItemList& items ) = 0; 211 212 }; 213 214 } 215 216 #endif// MUCROOMHANDLER_H__ 217