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 TALK_XMPP_CHATROOMMODULE_H_ 29 #define TALK_XMPP_CHATROOMMODULE_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(); 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, 91 const std::string& client_version, 92 const std::string& locale) = 0; 93 94 //! Requests that the user exit a chatroom 95 //! Async callback for this method is ChatroomExitedStatus 96 virtual XmppReturnStatus RequestExitChatroom() = 0; 97 98 //! Requests a status change 99 //! status is the standard XMPP status code 100 //! extended_status is the extended status when status is XMPP_PRESENCE_XA 101 virtual XmppReturnStatus RequestConnectionStatusChange( 102 XmppPresenceConnectionStatus connection_status) = 0; 103 104 //! Returns the number of members in the room 105 virtual size_t GetChatroomMemberCount() = 0; 106 107 //! Gets an enumerator for the members in the chatroom 108 //! The caller must delete the enumerator when the caller is finished with it. 109 //! The caller must also ensure that the lifetime of the enumerator is 110 //! scoped by the XmppChatRoomModule that created it. 111 virtual XmppReturnStatus CreateMemberEnumerator(XmppChatroomMemberEnumerator** enumerator) = 0; 112 113 //! Gets the subject of the chatroom 114 virtual const std::string subject() = 0; 115 116 //! Returns the current state of the user with respect to the chatroom 117 virtual XmppChatroomState state() = 0; 118 119 virtual XmppReturnStatus SendMessage(const XmlElement& message) = 0; 120 }; 121 122 //! Class for enumerating participatns 123 class XmppChatroomMemberEnumerator { 124 public: 125 virtual ~XmppChatroomMemberEnumerator() { } 126 //! Returns the member at the current position 127 //! Returns null if the enumerator is before the beginning 128 //! or after the end of the collection 129 virtual XmppChatroomMember* current() = 0; 130 131 //! Returns whether the enumerator is valid 132 //! This returns true if the collection has changed 133 //! since the enumerator was created 134 virtual bool IsValid() = 0; 135 136 //! Returns whether the enumerator is before the beginning 137 //! This is the initial state of the enumerator 138 virtual bool IsBeforeBeginning() = 0; 139 140 //! Returns whether the enumerator is after the end 141 virtual bool IsAfterEnd() = 0; 142 143 //! Advances the enumerator to the next position 144 //! Returns false is the enumerator is advanced 145 //! off the end of the collection 146 virtual bool Next() = 0; 147 148 //! Advances the enumerator to the previous position 149 //! Returns false is the enumerator is advanced 150 //! off the end of the collection 151 virtual bool Prev() = 0; 152 }; 153 154 155 //! Represents a single member in a chatroom 156 class XmppChatroomMember { 157 public: 158 virtual ~XmppChatroomMember() { } 159 160 //! The jid for the member in the chatroom 161 virtual const Jid member_jid() const = 0; 162 163 //! The full jid for the member 164 //! This is only available in non-anonymous rooms. 165 //! If the room is anonymous, this returns JID_EMPTY 166 virtual const Jid full_jid() const = 0; 167 168 //! Returns the backing presence for this member 169 virtual const XmppPresence* presence() const = 0; 170 171 //! The nickname for this member 172 virtual const std::string name() const = 0; 173 }; 174 175 //! Status codes for ChatroomEnteredStatus callback 176 enum XmppChatroomEnteredStatus 177 { 178 //! User successfully entered the room 179 XMPP_CHATROOM_ENTERED_SUCCESS = 0, 180 //! The nickname confliced with somebody already in the room 181 XMPP_CHATROOM_ENTERED_FAILURE_NICKNAME_CONFLICT = 1, 182 //! A password is required to enter the room 183 XMPP_CHATROOM_ENTERED_FAILURE_PASSWORD_REQUIRED = 2, 184 //! The specified password was incorrect 185 XMPP_CHATROOM_ENTERED_FAILURE_PASSWORD_INCORRECT = 3, 186 //! The user is not a member of a member-only room 187 XMPP_CHATROOM_ENTERED_FAILURE_NOT_A_MEMBER = 4, 188 //! The user cannot enter because the user has been banned 189 XMPP_CHATROOM_ENTERED_FAILURE_MEMBER_BANNED = 5, 190 //! The room has the maximum number of users already 191 XMPP_CHATROOM_ENTERED_FAILURE_MAX_USERS = 6, 192 //! The room has been locked by an administrator 193 XMPP_CHATROOM_ENTERED_FAILURE_ROOM_LOCKED = 7, 194 //! Someone in the room has blocked you 195 XMPP_CHATROOM_ENTERED_FAILURE_MEMBER_BLOCKED = 8, 196 //! You have blocked someone in the room 197 XMPP_CHATROOM_ENTERED_FAILURE_MEMBER_BLOCKING = 9, 198 //! Client is old. User must upgrade to a more recent version for 199 // hangouts to work. 200 XMPP_CHATROOM_ENTERED_FAILURE_OUTDATED_CLIENT = 10, 201 //! Some other reason 202 XMPP_CHATROOM_ENTERED_FAILURE_UNSPECIFIED = 2000, 203 }; 204 205 //! Status codes for ChatroomExitedStatus callback 206 enum XmppChatroomExitedStatus 207 { 208 //! The user requested to exit and did so 209 XMPP_CHATROOM_EXITED_REQUESTED = 0, 210 //! The user was banned from the room 211 XMPP_CHATROOM_EXITED_BANNED = 1, 212 //! The user has been kicked out of the room 213 XMPP_CHATROOM_EXITED_KICKED = 2, 214 //! The user has been removed from the room because the 215 //! user is no longer a member of a member-only room 216 //! or the room has changed to membership-only 217 XMPP_CHATROOM_EXITED_NOT_A_MEMBER = 3, 218 //! The system is shutting down 219 XMPP_CHATROOM_EXITED_SYSTEM_SHUTDOWN = 4, 220 //! For some other reason 221 XMPP_CHATROOM_EXITED_UNSPECIFIED = 5, 222 }; 223 224 //! The XmppChatroomHandler is the interface for callbacks from the 225 //! the chatroom 226 class XmppChatroomHandler { 227 public: 228 virtual ~XmppChatroomHandler() {} 229 230 //! Indicates the response to RequestEnterChatroom method 231 //! XMPP_CHATROOM_SUCCESS represents success. 232 //! Other status codes are for errors 233 virtual void ChatroomEnteredStatus(XmppChatroomModule* room, 234 const XmppPresence* presence, 235 XmppChatroomEnteredStatus status) = 0; 236 237 238 //! Indicates that the user has exited the chatroom, either due to 239 //! a call to RequestExitChatroom or for some other reason. 240 //! status indicates the reason the user exited 241 virtual void ChatroomExitedStatus(XmppChatroomModule* room, 242 XmppChatroomExitedStatus status) = 0; 243 244 //! Indicates a member entered the room. 245 //! It can be called before ChatroomEnteredStatus. 246 virtual void MemberEntered(XmppChatroomModule* room, 247 const XmppChatroomMember* entered_member) = 0; 248 249 //! Indicates that a member exited the room. 250 virtual void MemberExited(XmppChatroomModule* room, 251 const XmppChatroomMember* exited_member) = 0; 252 253 //! Indicates that the data for the member has changed 254 //! (such as the nickname or presence) 255 virtual void MemberChanged(XmppChatroomModule* room, 256 const XmppChatroomMember* changed_member) = 0; 257 258 //! Indicates a new message has been received 259 //! message is the message - 260 // $TODO - message should be changed 261 //! to a strongly-typed message class that contains info 262 //! such as the sender, message bodies, etc., 263 virtual void MessageReceived(XmppChatroomModule* room, 264 const XmlElement& message) = 0; 265 }; 266 267 268 } 269 270 #endif // TALK_XMPP_CHATROOMMODULE_H_ 271
