2
* sxemanager.h - Whiteboard manager
3
* Copyright (C) 2006 Joonas Govenius
5
* This program is free software; you can redistribute it and/or
6
* modify it under the terms of the GNU General Public License
7
* as published by the Free Software Foundation; either version 2
8
* of the License, or (at your option) any later version.
10
* This program is distributed in the hope that it will be useful,
11
* but WITHOUT ANY WARRANTY; without even the implied warranty of
12
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
* GNU General Public License for more details.
15
* You should have received a copy of the GNU General Public License
16
* along with this library; if not, write to the Free Software
17
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
26
#include "sxesession.h"
36
/*! \brief The manager for SXE sessions and negotiations.
37
* This class listens to incoming messages and picks up any that contain an
38
* SxdE element. If the element belongs to an already established session,
39
* the element is passed to the session. If the element is a negotiation element,
40
* the manager handles it. Accepting invitations is determined based on callback
41
* functions provided to the class.
43
* The manager also provides a possibillity for the local client to start
44
* a new session negotiation with the desired contact.
46
* One instance per PsiAccount should be created.
50
class SxeManager : public QObject
54
/*! \brief A simple struct used to keep track of the detected SXE sessions.*/
55
struct DetectedSession {
61
/*! \brief A simple class to keep track of the state of a session negotiation process.*/
64
enum Role {Participant, Joiner};
65
enum State {NotStarted, InvitationSent, ConnectionRequested, InvitationAccepted, DocumentBegan, /*DocumentEnded,*/ HistoryOffered, HistoryAccepted, Finished, Aborted};
67
/*! \brief Describes our role in the negotiation.*/
69
/*! \brief Describes the current state of the negotiation.*/
71
/*! \brief The identifier for the session.*/
73
/*! \brief The JID that will be used for delivering the sxe messages once session is established.*/
75
/*! \brief The JID where negotiation messages are sent.*/
77
/*! \brief The user's own JID used in the session.*/
79
/*! \brief Set if the target is a groupchat.*/
81
/*! \brief The document to be sent as the initial document during the negotiation.
82
* This is only relevant when Role == Participant.
84
QDomDocument initialDoc;
85
/*! \brief A list of features proposed for the session.*/
86
QList<QString> features;
87
/*! \brief The session created for this negotiation.*/
88
QPointer<SxeSession> session;
92
/*! \brief Constructor.
93
* Creates a new manager for the specified Client and PsiAccount
95
SxeManager(XMPP::Client* client, PsiAccount* pa);
96
/*! \brief Return a list of pointers to sessions to the specified contact.
97
* If no such session exits, returns 0.
99
QList< QPointer<SxeSession> > findSession(const Jid &target);
100
/*! \brief Return a pointer to the specified session.
101
* If such session doesn't exits, returns 0.
103
QPointer<SxeSession> findSession(const QString &session);
104
/*! \brief Add a callback for invitations.*/
105
void addInvitationCallback(bool (*callback)(const Jid &peer, const QList<QString> &features));
106
/*! \brief Starts a new session negotiation to the specified contact with given list of features.*/
107
void startNewSession(const Jid &target, const Jid &ownJid, bool groupChat, const QDomDocument &initialDoc, QList<QString> features = QList<QString>());
108
/*! \brief Join an existing session.*/
109
void joinSession(const Jid &target, const Jid &ownJid, bool groupChat, const QString &session);
112
/*! \brief Emitted when \a session has been established.*/
113
void sessionNegotiated(SxeSession* session);
114
/*! \brief Emitted when \a an invitation to \a jid was declined and joining an alternative session \a session was suggested.*/
115
void alternativeSession(const Jid &jid, const QString &session);
118
/*! \brief Process a message that contains a negotiation element.
119
* Returns a pointer to the new session if negotiation finished.
121
QPointer<SxeSession> processNegotiationMessage(const Message &message);
122
/*! \brief Process a negotiation element as a Participant.
123
Appends the appropriate responses to \a response.
124
Returns false iff the negotiation object was deleted. */
125
bool processNegotiationAsParticipant(const QDomNode &negotiationElement, SxeNegotiation* negotiation, QDomNode response);
126
/*! \brief Process a negotiation element as a Joiner.
127
Appends the appropriate responses to \a response.
128
Returns false iff the negotiation object was deleted. */
129
bool processNegotiationAsJoiner(const QDomNode &negotiationElement, SxeNegotiation* negotiation, QDomNode response, const Message &message);
130
/*! \brief Returns a pointer to a new session instance.*/
131
QPointer<SxeSession> createSxeSession(const Jid &target, QString session, const Jid &ownJid, bool groupChat, const QList<QString> &features);
132
/*! \brief Aborts the negotiation of \a session started with \a peer.*/
133
void abortNegotiation(QString session, const Jid &peer, bool groupChat);
134
/*! \brief Aborts the negotiation with the peer and deletes the session.*/
135
void abortNegotiation(SxeNegotiation* negotiation);
136
/*! \brief Records the session that the message refers to as a DetectedSession if no entry for the session exists yet.*/
137
void recordDetectedSession(const Message &message);
138
/*! \brief Returns a pointer to a new negotiation instance based on \a message.*/
139
SxeNegotiation* createNegotiation(const Message &message);
140
/*! \brief Returns a pointer to a new negotiation instance.*/
141
SxeNegotiation* createNegotiation(SxeNegotiation::Role role, SxeNegotiation::State state, const QString &sessionId, const Jid &target, const Jid &ownJid, bool groupChat);
142
/*! \brief Returns a pointer to an existing negotiation object of \a session with \a jid.*/
143
SxeNegotiation* findNegotiation(const Jid &jid, const QString &session);
144
/*! \brief Remove the negotiation object of \a session with \a jid.*/
145
void removeNegotiation(SxeNegotiation* negotiation);
148
/*! \brief A pointer to the Client to listen to.*/
149
XMPP::Client* client_;
150
/*! \brief A pointer to the PsiAccount to listen to.*/
152
/*! \brief A list of of established sessions.*/
153
QList< QPointer<SxeSession> > sessions_;
154
/*! \brief A list of negotiations in process.*/
155
QMultiHash<QString, SxeNegotiation* > negotiations_;
156
/*! \brief A timer used to remove unfinished negotiations after a timeout.*/
157
QTimer negotiationTimer_;
158
/*! \brief A list of of detected sessions.*/
159
QList<DetectedSession> DetectedSessions_;
160
/*! \brief A list of Jids corresponding to self.*/
161
QList<QString> ownJids_;
162
/*! \brief A list of callbacks used to determine whether an invitation should be accepted.*/
163
QList<bool (*)(const Jid &peer, const QList<QString> &features)> invitationCallbacks_;
164
/*! \brief A counter used for including a unique id in each sent sxe element.*/
166
/*! \brief A list of messages waiting to be sent out.*/
167
QList<Message> queuedMessages_;
170
/*! \brief Receives incoming message and determines what to do with them.*/
171
void messageReceived(const Message &message);
172
/*! \brief Send given whiteboard element to receiver in a message.*/
173
void sendSxe(QDomElement sxe, const Jid & receiver, bool groupChat);
174
/*! \brief Removes and deletes the session.*/
175
void removeSession(SxeSession* session);
176
/*! \brief Removes the "detected session" record of the given session.*/
177
void removeDetectedSession(SxeSession* session);
178
/*! \brief Removes and deletes the possible sessions for the groupchat.*/
179
void groupChatLeft(const Jid &);
180
/*! \brief Keeps a record of groupchats.*/
181
void groupChatJoined(const Jid &, const Jid &ownJid);
182
/*! \brief Removes inactive and unfinished session negotiations.*/
183
void negotiationTimeout();