henrike@webrtc.org | 269fb4b | 2014-10-28 22:20:11 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 2004 The WebRTC Project Authors. All rights reserved. |
| 3 | * |
| 4 | * Use of this source code is governed by a BSD-style license |
| 5 | * that can be found in the LICENSE file in the root of the source |
| 6 | * tree. An additional intellectual property rights grant can be found |
| 7 | * in the file PATENTS. All contributing project authors may |
| 8 | * be found in the AUTHORS file in the root of the source tree. |
| 9 | */ |
| 10 | |
| 11 | #ifndef WEBRTC_LIBJINGLE_XMPP_ROSTERMODULE_H_ |
| 12 | #define WEBRTC_LIBJINGLE_XMPP_ROSTERMODULE_H_ |
| 13 | |
| 14 | #include "webrtc/libjingle/xmpp/module.h" |
| 15 | |
| 16 | namespace buzz { |
| 17 | |
| 18 | class XmppRosterModule; |
| 19 | |
| 20 | // The main way you initialize and use the module would be like this: |
| 21 | // XmppRosterModule *roster_module = XmppRosterModule::Create(); |
| 22 | // roster_module->RegisterEngine(engine); |
| 23 | // roster_module->BroadcastPresence(); |
| 24 | // roster_module->RequestRosterUpdate(); |
| 25 | |
| 26 | //! This enum captures the valid values for the show attribute in a presence |
| 27 | //! stanza |
| 28 | enum XmppPresenceShow |
| 29 | { |
| 30 | XMPP_PRESENCE_CHAT = 0, |
| 31 | XMPP_PRESENCE_DEFAULT = 1, |
| 32 | XMPP_PRESENCE_AWAY = 2, |
| 33 | XMPP_PRESENCE_XA = 3, |
| 34 | XMPP_PRESENCE_DND = 4, |
| 35 | }; |
| 36 | |
| 37 | //! These are the valid subscription states in a roster contact. This |
| 38 | //! represents the combination of the subscription and ask attributes |
| 39 | enum XmppSubscriptionState |
| 40 | { |
| 41 | XMPP_SUBSCRIPTION_NONE = 0, |
| 42 | XMPP_SUBSCRIPTION_NONE_ASKED = 1, |
| 43 | XMPP_SUBSCRIPTION_TO = 2, |
| 44 | XMPP_SUBSCRIPTION_FROM = 3, |
| 45 | XMPP_SUBSCRIPTION_FROM_ASKED = 4, |
| 46 | XMPP_SUBSCRIPTION_BOTH = 5, |
| 47 | }; |
| 48 | |
| 49 | //! These represent the valid types of presence stanzas for managing |
| 50 | //! subscriptions |
| 51 | enum XmppSubscriptionRequestType |
| 52 | { |
| 53 | XMPP_REQUEST_SUBSCRIBE = 0, |
| 54 | XMPP_REQUEST_UNSUBSCRIBE = 1, |
| 55 | XMPP_REQUEST_SUBSCRIBED = 2, |
| 56 | XMPP_REQUEST_UNSUBSCRIBED = 3, |
| 57 | }; |
| 58 | |
| 59 | enum XmppPresenceAvailable { |
| 60 | XMPP_PRESENCE_UNAVAILABLE = 0, |
| 61 | XMPP_PRESENCE_AVAILABLE = 1, |
| 62 | XMPP_PRESENCE_ERROR = 2, |
| 63 | }; |
| 64 | |
| 65 | enum XmppPresenceConnectionStatus { |
| 66 | XMPP_CONNECTION_STATUS_UNKNOWN = 0, |
| 67 | // Status set by the server while the user is being rung. |
| 68 | XMPP_CONNECTION_STATUS_CONNECTING = 1, |
| 69 | // Status set by the client when the user has accepted the ring but before |
| 70 | // the client has joined the call. |
| 71 | XMPP_CONNECTION_STATUS_JOINING = 2, |
| 72 | // Status set by the client as part of joining the call. |
| 73 | XMPP_CONNECTION_STATUS_CONNECTED = 3, |
| 74 | XMPP_CONNECTION_STATUS_HANGUP = 4, |
| 75 | }; |
| 76 | |
| 77 | //! Presence Information |
| 78 | //! This class stores both presence information for outgoing presence and is |
| 79 | //! returned by methods in XmppRosterModule to represent recieved incoming |
| 80 | //! presence information. When this class is writeable (non-const) then each |
| 81 | //! update to any property will set the inner xml. Setting the raw_xml will |
| 82 | //! rederive all of the other properties. |
| 83 | class XmppPresence { |
| 84 | public: |
| 85 | virtual ~XmppPresence() {} |
| 86 | |
| 87 | //! Create a new Presence |
| 88 | //! This is typically only used when sending a directed presence |
| 89 | static XmppPresence* Create(); |
| 90 | |
| 91 | //! The Jid of for the presence information. |
| 92 | //! Typically this will be a full Jid with resource specified. |
| 93 | virtual const Jid jid() const = 0; |
| 94 | |
| 95 | //! Is the contact available? |
| 96 | virtual XmppPresenceAvailable available() const = 0; |
| 97 | |
| 98 | //! Sets if the user is available or not |
| 99 | virtual XmppReturnStatus set_available(XmppPresenceAvailable available) = 0; |
| 100 | |
| 101 | //! The show value of the presence info |
| 102 | virtual XmppPresenceShow presence_show() const = 0; |
| 103 | |
| 104 | //! Set the presence show value |
| 105 | virtual XmppReturnStatus set_presence_show(XmppPresenceShow show) = 0; |
| 106 | |
| 107 | //! The Priority of the presence info |
| 108 | virtual int priority() const = 0; |
| 109 | |
| 110 | //! Set the priority of the presence |
| 111 | virtual XmppReturnStatus set_priority(int priority) = 0; |
| 112 | |
| 113 | //! The plain text status of the presence info. |
| 114 | //! If there are multiple status because of language, this will either be a |
| 115 | //! status that is not tagged for language or the first available |
| 116 | virtual const std::string status() const = 0; |
| 117 | |
| 118 | //! Sets the status for the presence info. |
| 119 | //! If there is more than one status present already then this will remove |
| 120 | //! them all and replace it with one status element we no specified language |
| 121 | virtual XmppReturnStatus set_status(const std::string& status) = 0; |
| 122 | |
| 123 | //! The connection status |
| 124 | virtual XmppPresenceConnectionStatus connection_status() const = 0; |
| 125 | |
| 126 | //! The focus obfuscated GAIA id |
| 127 | virtual const std::string google_user_id() const = 0; |
| 128 | |
| 129 | //! The nickname in the presence |
| 130 | virtual const std::string nickname() const = 0; |
| 131 | |
| 132 | //! The raw xml of the presence update |
| 133 | virtual const XmlElement* raw_xml() const = 0; |
| 134 | |
| 135 | //! Sets the raw presence stanza for the presence update |
| 136 | //! This will cause all other data items in this structure to be rederived |
| 137 | virtual XmppReturnStatus set_raw_xml(const XmlElement * xml) = 0; |
| 138 | }; |
| 139 | |
| 140 | //! A contact as given by the server |
| 141 | class XmppRosterContact { |
| 142 | public: |
| 143 | virtual ~XmppRosterContact() {} |
| 144 | |
| 145 | //! Create a new roster contact |
| 146 | //! This is typically only used when doing a roster update/add |
| 147 | static XmppRosterContact* Create(); |
| 148 | |
| 149 | //! The jid for the contact. |
| 150 | //! Typically this will be a bare Jid. |
| 151 | virtual const Jid jid() const = 0; |
| 152 | |
| 153 | //! Sets the jid for the roster contact update |
| 154 | virtual XmppReturnStatus set_jid(const Jid& jid) = 0; |
| 155 | |
| 156 | //! The name (nickname) stored for this contact |
| 157 | virtual const std::string name() const = 0; |
| 158 | |
| 159 | //! Sets the name |
| 160 | virtual XmppReturnStatus set_name(const std::string& name) = 0; |
| 161 | |
| 162 | //! The Presence subscription state stored on the server for this contact |
| 163 | //! This is never settable and will be ignored when generating a roster |
| 164 | //! add/update request |
| 165 | virtual XmppSubscriptionState subscription_state() const = 0; |
| 166 | |
| 167 | //! The number of Groups applied to this contact |
| 168 | virtual size_t GetGroupCount() const = 0; |
| 169 | |
| 170 | //! Gets a Group applied to the contact based on index. |
| 171 | //! range |
| 172 | virtual const std::string GetGroup(size_t index) const = 0; |
| 173 | |
| 174 | //! Adds a group to this contact. |
| 175 | //! This will return a bad argument error if the group is already there. |
| 176 | virtual XmppReturnStatus AddGroup(const std::string& group) = 0; |
| 177 | |
| 178 | //! Removes a group from the contact. |
| 179 | //! This will return an error if the group cannot be found in the group list. |
| 180 | virtual XmppReturnStatus RemoveGroup(const std::string& group) = 0; |
| 181 | |
| 182 | //! The raw xml for this roster contact |
| 183 | virtual const XmlElement* raw_xml() const = 0; |
| 184 | |
| 185 | //! Sets the raw presence stanza for the contact update/add |
| 186 | //! This will cause all other data items in this structure to be rederived |
| 187 | virtual XmppReturnStatus set_raw_xml(const XmlElement * xml) = 0; |
| 188 | }; |
| 189 | |
| 190 | //! The XmppRosterHandler is an interface for callbacks from the module |
| 191 | class XmppRosterHandler { |
| 192 | public: |
| 193 | virtual ~XmppRosterHandler() {} |
| 194 | |
| 195 | //! A request for a subscription has come in. |
| 196 | //! Typically, the UI will ask the user if it is okay to let the requester |
| 197 | //! get presence notifications for the user. The response is send back |
| 198 | //! by calling ApproveSubscriber or CancelSubscriber. |
| 199 | virtual void SubscriptionRequest(XmppRosterModule* roster, |
| 200 | const Jid& requesting_jid, |
| 201 | XmppSubscriptionRequestType type, |
| 202 | const XmlElement* raw_xml) = 0; |
| 203 | |
| 204 | //! Some type of presence error has occured |
| 205 | virtual void SubscriptionError(XmppRosterModule* roster, |
| 206 | const Jid& from, |
| 207 | const XmlElement* raw_xml) = 0; |
| 208 | |
| 209 | virtual void RosterError(XmppRosterModule* roster, |
| 210 | const XmlElement* raw_xml) = 0; |
| 211 | |
| 212 | //! New presence information has come in |
| 213 | //! The user is notified with the presence object directly. This info is also |
| 214 | //! added to the store accessable from the engine. |
| 215 | virtual void IncomingPresenceChanged(XmppRosterModule* roster, |
| 216 | const XmppPresence* presence) = 0; |
| 217 | |
| 218 | //! A contact has changed |
| 219 | //! This indicates that the data for a contact may have changed. No |
| 220 | //! contacts have been added or removed. |
| 221 | virtual void ContactChanged(XmppRosterModule* roster, |
| 222 | const XmppRosterContact* old_contact, |
| 223 | size_t index) = 0; |
| 224 | |
| 225 | //! A set of contacts have been added |
| 226 | //! These contacts may have been added in response to the original roster |
| 227 | //! request or due to a "roster push" from the server. |
| 228 | virtual void ContactsAdded(XmppRosterModule* roster, |
| 229 | size_t index, size_t number) = 0; |
| 230 | |
| 231 | //! A contact has been removed |
| 232 | //! This contact has been removed form the list. |
| 233 | virtual void ContactRemoved(XmppRosterModule* roster, |
| 234 | const XmppRosterContact* removed_contact, |
| 235 | size_t index) = 0; |
| 236 | |
| 237 | }; |
| 238 | |
| 239 | //! An XmppModule for handle roster and presence functionality |
| 240 | class XmppRosterModule : public XmppModule { |
| 241 | public: |
| 242 | //! Creates a new XmppRosterModule |
| 243 | static XmppRosterModule * Create(); |
| 244 | virtual ~XmppRosterModule() {} |
| 245 | |
| 246 | //! Sets the roster handler (callbacks) for the module |
| 247 | virtual XmppReturnStatus set_roster_handler(XmppRosterHandler * handler) = 0; |
| 248 | |
| 249 | //! Gets the roster handler for the module |
| 250 | virtual XmppRosterHandler* roster_handler() = 0; |
| 251 | |
| 252 | // USER PRESENCE STATE ------------------------------------------------------- |
| 253 | |
| 254 | //! Gets the aggregate outgoing presence |
| 255 | //! This object is non-const and be edited directly. No update is sent |
| 256 | //! to the server until a Broadcast is sent |
| 257 | virtual XmppPresence* outgoing_presence() = 0; |
| 258 | |
| 259 | //! Broadcasts that the user is available. |
| 260 | //! Nothing with respect to presence is sent until this is called. |
| 261 | virtual XmppReturnStatus BroadcastPresence() = 0; |
| 262 | |
| 263 | //! Sends a directed presence to a Jid |
| 264 | //! Note that the client doesn't store where directed presence notifications |
| 265 | //! have been sent. The server can keep the appropriate state |
| 266 | virtual XmppReturnStatus SendDirectedPresence(const XmppPresence* presence, |
| 267 | const Jid& to_jid) = 0; |
| 268 | |
| 269 | // INCOMING PRESENCE STATUS -------------------------------------------------- |
| 270 | |
| 271 | //! Returns the number of incoming presence data recorded |
| 272 | virtual size_t GetIncomingPresenceCount() = 0; |
| 273 | |
| 274 | //! Returns an incoming presence datum based on index |
| 275 | virtual const XmppPresence* GetIncomingPresence(size_t index) = 0; |
| 276 | |
| 277 | //! Gets the number of presence data for a bare Jid |
| 278 | //! There may be a datum per resource |
| 279 | virtual size_t GetIncomingPresenceForJidCount(const Jid& jid) = 0; |
| 280 | |
| 281 | //! Returns a single presence data for a Jid based on index |
| 282 | virtual const XmppPresence* GetIncomingPresenceForJid(const Jid& jid, |
| 283 | size_t index) = 0; |
| 284 | |
| 285 | // ROSTER MANAGEMENT --------------------------------------------------------- |
| 286 | |
| 287 | //! Requests an update of the roster from the server |
| 288 | //! This must be called to initialize the client side cache of the roster |
| 289 | //! After this is sent the server should keep this module apprised of any |
| 290 | //! changes. |
| 291 | virtual XmppReturnStatus RequestRosterUpdate() = 0; |
| 292 | |
| 293 | //! Returns the number of contacts in the roster |
| 294 | virtual size_t GetRosterContactCount() = 0; |
| 295 | |
| 296 | //! Returns a contact by index |
| 297 | virtual const XmppRosterContact* GetRosterContact(size_t index) = 0; |
| 298 | |
| 299 | //! Finds a contact by Jid |
| 300 | virtual const XmppRosterContact* FindRosterContact(const Jid& jid) = 0; |
| 301 | |
| 302 | //! Send a request to the server to add a contact |
| 303 | //! Note that the contact won't show up in the roster until the server can |
| 304 | //! respond. This happens async when the socket is being serviced |
| 305 | virtual XmppReturnStatus RequestRosterChange( |
| 306 | const XmppRosterContact* contact) = 0; |
| 307 | |
| 308 | //! Request that the server remove a contact |
| 309 | //! The jabber protocol specifies that the server should also cancel any |
| 310 | //! subscriptions when this is done. Like adding, this contact won't be |
| 311 | //! removed until the server responds. |
| 312 | virtual XmppReturnStatus RequestRosterRemove(const Jid& jid) = 0; |
| 313 | |
| 314 | // SUBSCRIPTION MANAGEMENT --------------------------------------------------- |
| 315 | |
| 316 | //! Request a subscription to presence notifications form a Jid |
| 317 | virtual XmppReturnStatus RequestSubscription(const Jid& jid) = 0; |
| 318 | |
| 319 | //! Cancel a subscription to presence notifications from a Jid |
| 320 | virtual XmppReturnStatus CancelSubscription(const Jid& jid) = 0; |
| 321 | |
| 322 | //! Approve a request to deliver presence notifications to a jid |
| 323 | virtual XmppReturnStatus ApproveSubscriber(const Jid& jid) = 0; |
| 324 | |
| 325 | //! Deny or cancel presence notification deliver to a jid |
| 326 | virtual XmppReturnStatus CancelSubscriber(const Jid& jid) = 0; |
| 327 | }; |
| 328 | |
| 329 | } |
| 330 | |
| 331 | #endif // WEBRTC_LIBJINGLE_XMPP_ROSTERMODULE_H_ |