1 /* 2 * libjingle 3 * Copyright 2004--2005, Google Inc. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, 9 * this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #ifndef _multiuserchatmodule_h_ 29 #define _multiuserchatmodule_h_ 30 31 #include "talk/xmpp/module.h" 32 #include "talk/xmpp/rostermodule.h" 33 34 namespace buzz { 35 36 // forward declarations 37 class XmppChatroomModule; 38 class XmppChatroomHandler; 39 class XmppChatroomMember; 40 class XmppChatroomMemberEnumerator; 41 42 enum XmppChatroomState { 43 XMPP_CHATROOM_STATE_NOT_IN_ROOM = 0, 44 XMPP_CHATROOM_STATE_REQUESTED_ENTER = 1, 45 XMPP_CHATROOM_STATE_IN_ROOM = 2, 46 XMPP_CHATROOM_STATE_REQUESTED_EXIT = 3, 47 }; 48 49 //! Module that encapsulates a chatroom. 50 class XmppChatroomModule : public XmppModule { 51 public: 52 53 //! Creates a new XmppChatroomModule 54 static XmppChatroomModule* Create(); ~XmppChatroomModule()55 virtual ~XmppChatroomModule() {} 56 57 //! Sets the chatroom handler (callbacks) for the chatroom 58 virtual XmppReturnStatus set_chatroom_handler(XmppChatroomHandler* handler) = 0; 59 60 //! Gets the chatroom handler for the module 61 virtual XmppChatroomHandler* chatroom_handler() = 0; 62 63 //! Sets the jid of the chatroom. 64 //! Has to be set before entering the chatroom and can't be changed 65 //! while in the chatroom 66 virtual XmppReturnStatus set_chatroom_jid(const Jid& chatroom_jid) = 0; 67 68 //! The jid for the chatroom 69 virtual const Jid& chatroom_jid() const = 0; 70 71 //! Sets the nickname of the member 72 //! Has to be set before entering the chatroom and can't be changed 73 //! while in the chatroom 74 virtual XmppReturnStatus set_nickname(const std::string& nickname) = 0; 75 76 //! The nickname of the member in the chatroom 77 virtual const std::string& nickname() const = 0; 78 79 //! Returns the jid of the member (this is the chatroom_jid plus the 80 //! nickname as the resource name) 81 virtual const Jid member_jid() const = 0; 82 83 //! Requests that the user enter a chatroom 84 //! The EnterChatroom callback will be called when the request is complete. 85 //! Password should be empty for a room that doesn't require a password 86 //! If the room doesn't exist, the server will create an "Instant Room" if the 87 //! server policy supports this action. 88 //! There will be different methods for creating/configuring a "Reserved Room" 89 //! Async callback for this method is ChatroomEnteredStatus 90 virtual XmppReturnStatus RequestEnterChatroom(const std::string& password) = 0; 91 92 //! Requests that the user exit a chatroom 93 //! Async callback for this method is ChatroomExitedStatus 94 virtual XmppReturnStatus RequestExitChatroom() = 0; 95 96 //! Requests a status change 97 //! status is the standard XMPP status code 98 //! extended_status is the extended status when status is XMPP_PRESENCE_XA 99 virtual XmppReturnStatus RequestStatusChange(XmppPresenceShow status, 100 const std::string& extended_status) = 0; 101 102 //! Returns the number of members in the room 103 virtual size_t GetChatroomMemberCount() = 0; 104 105 //! Gets an enumerator for the members in the chatroom 106 //! The caller must delete the enumerator when the caller is finished with it. 107 //! The caller must also ensure that the lifetime of the enumerator is 108 //! scoped by the XmppChatRoomModule that created it. 109 virtual XmppReturnStatus CreateMemberEnumerator(XmppChatroomMemberEnumerator** enumerator) = 0; 110 111 //! Gets the subject of the chatroom 112 virtual const std::string& subject() = 0; 113 114 //! Returns the current state of the user with respect to the chatroom 115 virtual XmppChatroomState state() = 0; 116 117 virtual XmppReturnStatus SendMessage(const XmlElement& message) = 0; 118 }; 119 120 //! Class for enumerating participatns 121 class XmppChatroomMemberEnumerator { 122 public: ~XmppChatroomMemberEnumerator()123 virtual ~XmppChatroomMemberEnumerator() { } 124 //! Returns the member at the current position 125 //! Returns null if the enumerator is before the beginning 126 //! or after the end of the collection 127 virtual XmppChatroomMember* current() = 0; 128 129 //! Returns whether the enumerator is valid 130 //! This returns true if the collection has changed 131 //! since the enumerator was created 132 virtual bool IsValid() = 0; 133 134 //! Returns whether the enumerator is before the beginning 135 //! This is the initial state of the enumerator 136 virtual bool IsBeforeBeginning() = 0; 137 138 //! Returns whether the enumerator is after the end 139 virtual bool IsAfterEnd() = 0; 140 141 //! Advances the enumerator to the next position 142 //! Returns false is the enumerator is advanced 143 //! off the end of the collection 144 virtual bool Next() = 0; 145 146 //! Advances the enumerator to the previous position 147 //! Returns false is the enumerator is advanced 148 //! off the end of the collection 149 virtual bool Prev() = 0; 150 }; 151 152 //! Represents a single member in a chatroom 153 class XmppChatroomMember { 154 public: ~XmppChatroomMember()155 virtual ~XmppChatroomMember() { } 156 157 //! The jid for the member in the chatroom 158 virtual const Jid member_jid() const = 0; 159 160 //! The full jid for the member 161 //! This is only available in non-anonymous rooms. 162 //! If the room is anonymous, this returns JID_EMPTY 163 virtual const Jid full_jid() const = 0; 164 165 //! Returns the backing presence for this member 166 virtual const XmppPresence* presence() const = 0; 167 168 //! The nickname for this member 169 virtual const std::string name() const = 0; 170 }; 171 172 //! Status codes for ChatroomEnteredStatus callback 173 enum XmppChatroomEnteredStatus 174 { 175 //! User successfully entered the room 176 XMPP_CHATROOM_ENTERED_SUCCESS = 0, 177 //! The nickname confliced with somebody already in the room 178 XMPP_CHATROOM_ENTERED_FAILURE_NICKNAME_CONFLICT = 1, 179 //! A password is required to enter the room 180 XMPP_CHATROOM_ENTERED_FAILURE_PASSWORD_REQUIRED = 2, 181 //! The specified password was incorrect 182 XMPP_CHATROOM_ENTERED_FAILURE_PASSWORD_INCORRECT = 3, 183 //! The user is not a member of a member-only room 184 XMPP_CHATROOM_ENTERED_FAILURE_NOT_A_MEMBER = 4, 185 //! The user cannot enter because the user has been banned 186 XMPP_CHATROOM_ENTERED_FAILURE_MEMBER_BANNED = 5, 187 //! The room has the maximum number of users already 188 XMPP_CHATROOM_ENTERED_FAILURE_MAX_USERS = 6, 189 //! The room has been locked by an administrator 190 XMPP_CHATROOM_ENTERED_FAILURE_ROOM_LOCKED = 7, 191 //! Some other reason 192 XMPP_CHATROOM_ENTERED_FAILURE_UNSPECIFIED = 2000, 193 }; 194 195 //! Status codes for ChatroomExitedStatus callback 196 enum XmppChatroomExitedStatus 197 { 198 //! The user requested to exit and did so 199 XMPP_CHATROOM_EXITED_REQUESTED = 0, 200 //! The user was banned from the room 201 XMPP_CHATROOM_EXITED_BANNED = 1, 202 //! The user has been kicked out of the room 203 XMPP_CHATROOM_EXITED_KICKED = 2, 204 //! The user has been removed from the room because the 205 //! user is no longer a member of a member-only room 206 //! or the room has changed to membership-only 207 XMPP_CHATROOM_EXITED_NOT_A_MEMBER = 3, 208 //! The system is shutting down 209 XMPP_CHATROOM_EXITED_SYSTEM_SHUTDOWN = 4, 210 //! For some other reason 211 XMPP_CHATROOM_EXITED_UNSPECIFIED = 5, 212 }; 213 214 //! The XmppChatroomHandler is the interface for callbacks from the 215 //! the chatroom 216 class XmppChatroomHandler { 217 public: ~XmppChatroomHandler()218 virtual ~XmppChatroomHandler() {} 219 220 //! Indicates the response to RequestEnterChatroom method 221 //! XMPP_CHATROOM_SUCCESS represents success. 222 //! Other status codes are for errors 223 virtual void ChatroomEnteredStatus(XmppChatroomModule* room, 224 XmppChatroomEnteredStatus status) = 0; 225 226 //! Indicates that the user has exited the chatroom, either due to 227 //! a call to RequestExitChatroom or for some other reason. 228 //! status indicates the reason the user exited 229 virtual void ChatroomExitedStatus(XmppChatroomModule* room, 230 XmppChatroomExitedStatus status) = 0; 231 232 //! Indicates a member entered the room. 233 virtual void MemberEntered(XmppChatroomModule* room, 234 const XmppChatroomMember* entered_member) = 0; 235 236 //! Indicates that a member exited the room. 237 virtual void MemberExited(XmppChatroomModule* room, 238 const XmppChatroomMember* exited_member) = 0; 239 240 //! Indicates that the data for the member has changed 241 //! (such as the nickname or presence) 242 virtual void MemberChanged(XmppChatroomModule* room, 243 size_t index) = 0; 244 245 //! Indicates a new message has been received 246 //! message is the message - 247 // $TODO - message should be changed 248 //! to a strongly-typed message class that contains info 249 //! such as the sender, message bodies, etc., 250 virtual void MessageReceived(XmppChatroomModule* room, 251 const XmlElement& message) = 0; 252 }; 253 254 } 255 256 #endif 257