3 * Copyright 2004--2005, Google Inc.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
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.
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.
28 #ifndef TALK_XMPP_ROSTERMODULE_H_
29 #define TALK_XMPP_ROSTERMODULE_H_
31 #include "webrtc/libjingle/xmpp/module.h"
35 class XmppRosterModule;
37 // The main way you initialize and use the module would be like this:
38 // XmppRosterModule *roster_module = XmppRosterModule::Create();
39 // roster_module->RegisterEngine(engine);
40 // roster_module->BroadcastPresence();
41 // roster_module->RequestRosterUpdate();
43 //! This enum captures the valid values for the show attribute in a presence
47 XMPP_PRESENCE_CHAT = 0,
48 XMPP_PRESENCE_DEFAULT = 1,
49 XMPP_PRESENCE_AWAY = 2,
51 XMPP_PRESENCE_DND = 4,
54 //! These are the valid subscription states in a roster contact. This
55 //! represents the combination of the subscription and ask attributes
56 enum XmppSubscriptionState
58 XMPP_SUBSCRIPTION_NONE = 0,
59 XMPP_SUBSCRIPTION_NONE_ASKED = 1,
60 XMPP_SUBSCRIPTION_TO = 2,
61 XMPP_SUBSCRIPTION_FROM = 3,
62 XMPP_SUBSCRIPTION_FROM_ASKED = 4,
63 XMPP_SUBSCRIPTION_BOTH = 5,
66 //! These represent the valid types of presence stanzas for managing
68 enum XmppSubscriptionRequestType
70 XMPP_REQUEST_SUBSCRIBE = 0,
71 XMPP_REQUEST_UNSUBSCRIBE = 1,
72 XMPP_REQUEST_SUBSCRIBED = 2,
73 XMPP_REQUEST_UNSUBSCRIBED = 3,
76 enum XmppPresenceAvailable {
77 XMPP_PRESENCE_UNAVAILABLE = 0,
78 XMPP_PRESENCE_AVAILABLE = 1,
79 XMPP_PRESENCE_ERROR = 2,
82 enum XmppPresenceConnectionStatus {
83 XMPP_CONNECTION_STATUS_UNKNOWN = 0,
84 // Status set by the server while the user is being rung.
85 XMPP_CONNECTION_STATUS_CONNECTING = 1,
86 // Status set by the client when the user has accepted the ring but before
87 // the client has joined the call.
88 XMPP_CONNECTION_STATUS_JOINING = 2,
89 // Status set by the client as part of joining the call.
90 XMPP_CONNECTION_STATUS_CONNECTED = 3,
91 XMPP_CONNECTION_STATUS_HANGUP = 4,
94 //! Presence Information
95 //! This class stores both presence information for outgoing presence and is
96 //! returned by methods in XmppRosterModule to represent recieved incoming
97 //! presence information. When this class is writeable (non-const) then each
98 //! update to any property will set the inner xml. Setting the raw_xml will
99 //! rederive all of the other properties.
102 virtual ~XmppPresence() {}
104 //! Create a new Presence
105 //! This is typically only used when sending a directed presence
106 static XmppPresence* Create();
108 //! The Jid of for the presence information.
109 //! Typically this will be a full Jid with resource specified.
110 virtual const Jid jid() const = 0;
112 //! Is the contact available?
113 virtual XmppPresenceAvailable available() const = 0;
115 //! Sets if the user is available or not
116 virtual XmppReturnStatus set_available(XmppPresenceAvailable available) = 0;
118 //! The show value of the presence info
119 virtual XmppPresenceShow presence_show() const = 0;
121 //! Set the presence show value
122 virtual XmppReturnStatus set_presence_show(XmppPresenceShow show) = 0;
124 //! The Priority of the presence info
125 virtual int priority() const = 0;
127 //! Set the priority of the presence
128 virtual XmppReturnStatus set_priority(int priority) = 0;
130 //! The plain text status of the presence info.
131 //! If there are multiple status because of language, this will either be a
132 //! status that is not tagged for language or the first available
133 virtual const std::string status() const = 0;
135 //! Sets the status for the presence info.
136 //! If there is more than one status present already then this will remove
137 //! them all and replace it with one status element we no specified language
138 virtual XmppReturnStatus set_status(const std::string& status) = 0;
140 //! The connection status
141 virtual XmppPresenceConnectionStatus connection_status() const = 0;
143 //! The focus obfuscated GAIA id
144 virtual const std::string google_user_id() const = 0;
146 //! The nickname in the presence
147 virtual const std::string nickname() const = 0;
149 //! The raw xml of the presence update
150 virtual const XmlElement* raw_xml() const = 0;
152 //! Sets the raw presence stanza for the presence update
153 //! This will cause all other data items in this structure to be rederived
154 virtual XmppReturnStatus set_raw_xml(const XmlElement * xml) = 0;
157 //! A contact as given by the server
158 class XmppRosterContact {
160 virtual ~XmppRosterContact() {}
162 //! Create a new roster contact
163 //! This is typically only used when doing a roster update/add
164 static XmppRosterContact* Create();
166 //! The jid for the contact.
167 //! Typically this will be a bare Jid.
168 virtual const Jid jid() const = 0;
170 //! Sets the jid for the roster contact update
171 virtual XmppReturnStatus set_jid(const Jid& jid) = 0;
173 //! The name (nickname) stored for this contact
174 virtual const std::string name() const = 0;
177 virtual XmppReturnStatus set_name(const std::string& name) = 0;
179 //! The Presence subscription state stored on the server for this contact
180 //! This is never settable and will be ignored when generating a roster
181 //! add/update request
182 virtual XmppSubscriptionState subscription_state() const = 0;
184 //! The number of Groups applied to this contact
185 virtual size_t GetGroupCount() const = 0;
187 //! Gets a Group applied to the contact based on index.
189 virtual const std::string GetGroup(size_t index) const = 0;
191 //! Adds a group to this contact.
192 //! This will return a bad argument error if the group is already there.
193 virtual XmppReturnStatus AddGroup(const std::string& group) = 0;
195 //! Removes a group from the contact.
196 //! This will return an error if the group cannot be found in the group list.
197 virtual XmppReturnStatus RemoveGroup(const std::string& group) = 0;
199 //! The raw xml for this roster contact
200 virtual const XmlElement* raw_xml() const = 0;
202 //! Sets the raw presence stanza for the contact update/add
203 //! This will cause all other data items in this structure to be rederived
204 virtual XmppReturnStatus set_raw_xml(const XmlElement * xml) = 0;
207 //! The XmppRosterHandler is an interface for callbacks from the module
208 class XmppRosterHandler {
210 virtual ~XmppRosterHandler() {}
212 //! A request for a subscription has come in.
213 //! Typically, the UI will ask the user if it is okay to let the requester
214 //! get presence notifications for the user. The response is send back
215 //! by calling ApproveSubscriber or CancelSubscriber.
216 virtual void SubscriptionRequest(XmppRosterModule* roster,
217 const Jid& requesting_jid,
218 XmppSubscriptionRequestType type,
219 const XmlElement* raw_xml) = 0;
221 //! Some type of presence error has occured
222 virtual void SubscriptionError(XmppRosterModule* roster,
224 const XmlElement* raw_xml) = 0;
226 virtual void RosterError(XmppRosterModule* roster,
227 const XmlElement* raw_xml) = 0;
229 //! New presence information has come in
230 //! The user is notified with the presence object directly. This info is also
231 //! added to the store accessable from the engine.
232 virtual void IncomingPresenceChanged(XmppRosterModule* roster,
233 const XmppPresence* presence) = 0;
235 //! A contact has changed
236 //! This indicates that the data for a contact may have changed. No
237 //! contacts have been added or removed.
238 virtual void ContactChanged(XmppRosterModule* roster,
239 const XmppRosterContact* old_contact,
242 //! A set of contacts have been added
243 //! These contacts may have been added in response to the original roster
244 //! request or due to a "roster push" from the server.
245 virtual void ContactsAdded(XmppRosterModule* roster,
246 size_t index, size_t number) = 0;
248 //! A contact has been removed
249 //! This contact has been removed form the list.
250 virtual void ContactRemoved(XmppRosterModule* roster,
251 const XmppRosterContact* removed_contact,
256 //! An XmppModule for handle roster and presence functionality
257 class XmppRosterModule : public XmppModule {
259 //! Creates a new XmppRosterModule
260 static XmppRosterModule * Create();
261 virtual ~XmppRosterModule() {}
263 //! Sets the roster handler (callbacks) for the module
264 virtual XmppReturnStatus set_roster_handler(XmppRosterHandler * handler) = 0;
266 //! Gets the roster handler for the module
267 virtual XmppRosterHandler* roster_handler() = 0;
269 // USER PRESENCE STATE -------------------------------------------------------
271 //! Gets the aggregate outgoing presence
272 //! This object is non-const and be edited directly. No update is sent
273 //! to the server until a Broadcast is sent
274 virtual XmppPresence* outgoing_presence() = 0;
276 //! Broadcasts that the user is available.
277 //! Nothing with respect to presence is sent until this is called.
278 virtual XmppReturnStatus BroadcastPresence() = 0;
280 //! Sends a directed presence to a Jid
281 //! Note that the client doesn't store where directed presence notifications
282 //! have been sent. The server can keep the appropriate state
283 virtual XmppReturnStatus SendDirectedPresence(const XmppPresence* presence,
284 const Jid& to_jid) = 0;
286 // INCOMING PRESENCE STATUS --------------------------------------------------
288 //! Returns the number of incoming presence data recorded
289 virtual size_t GetIncomingPresenceCount() = 0;
291 //! Returns an incoming presence datum based on index
292 virtual const XmppPresence* GetIncomingPresence(size_t index) = 0;
294 //! Gets the number of presence data for a bare Jid
295 //! There may be a datum per resource
296 virtual size_t GetIncomingPresenceForJidCount(const Jid& jid) = 0;
298 //! Returns a single presence data for a Jid based on index
299 virtual const XmppPresence* GetIncomingPresenceForJid(const Jid& jid,
302 // ROSTER MANAGEMENT ---------------------------------------------------------
304 //! Requests an update of the roster from the server
305 //! This must be called to initialize the client side cache of the roster
306 //! After this is sent the server should keep this module apprised of any
308 virtual XmppReturnStatus RequestRosterUpdate() = 0;
310 //! Returns the number of contacts in the roster
311 virtual size_t GetRosterContactCount() = 0;
313 //! Returns a contact by index
314 virtual const XmppRosterContact* GetRosterContact(size_t index) = 0;
316 //! Finds a contact by Jid
317 virtual const XmppRosterContact* FindRosterContact(const Jid& jid) = 0;
319 //! Send a request to the server to add a contact
320 //! Note that the contact won't show up in the roster until the server can
321 //! respond. This happens async when the socket is being serviced
322 virtual XmppReturnStatus RequestRosterChange(
323 const XmppRosterContact* contact) = 0;
325 //! Request that the server remove a contact
326 //! The jabber protocol specifies that the server should also cancel any
327 //! subscriptions when this is done. Like adding, this contact won't be
328 //! removed until the server responds.
329 virtual XmppReturnStatus RequestRosterRemove(const Jid& jid) = 0;
331 // SUBSCRIPTION MANAGEMENT ---------------------------------------------------
333 //! Request a subscription to presence notifications form a Jid
334 virtual XmppReturnStatus RequestSubscription(const Jid& jid) = 0;
336 //! Cancel a subscription to presence notifications from a Jid
337 virtual XmppReturnStatus CancelSubscription(const Jid& jid) = 0;
339 //! Approve a request to deliver presence notifications to a jid
340 virtual XmppReturnStatus ApproveSubscriber(const Jid& jid) = 0;
342 //! Deny or cancel presence notification deliver to a jid
343 virtual XmppReturnStatus CancelSubscriber(const Jid& jid) = 0;
348 #endif // TALK_XMPP_ROSTERMODULE_H_