1/*
2 Copyright (c) 2007 Volker Krause <vkrause@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_SESSION_H
21#define AKONADI_SESSION_H
22
23#include "akonadi_export.h"
24#include <QtCore/QObject>
25
26class KJob;
27class FakeSession;
28
29namespace Akonadi {
30
31class Job;
32class SessionPrivate;
33
34/**
35 * @short A communication session with the Akonadi storage.
36 *
37 * Every Job object has to be associated with a Session.
38 * The session is responsible of scheduling its jobs.
39 * For now only a simple serial execution is implemented (the IMAP-like
40 * protocol to communicate with the storage backend is capable of parallel
41 * execution on a single session though).
42 *
43 * @code
44 *
45 * using namespace Akonadi;
46 *
47 * Session *session = new Session( "mySession" );
48 *
49 * CollectionFetchJob *job = new CollectionFetchJob( Collection::root(),
50 * CollectionFetchJob::Recursive,
51 * session );
52 *
53 * connect( job, SIGNAL(result(KJob*)), this, SLOT(slotResult(KJob*)) );
54 *
55 * @endcode
56 *
57 * @author Volker Krause <vkrause@kde.org>
58 */
59class AKONADI_EXPORT Session : public QObject
60{
61 Q_OBJECT
62
63 friend class Job;
64 friend class JobPrivate;
65 friend class SessionPrivate;
66
67public:
68 /**
69 * Creates a new session.
70 *
71 * @param sessionId The identifier for this session, will be a
72 * random value if empty.
73 * @param parent The parent object.
74 *
75 * @see defaultSession()
76 */
77 explicit Session(const QByteArray &sessionId = QByteArray(), QObject *parent = 0);
78
79 /**
80 * Destroys the session.
81 */
82 ~Session();
83
84 /**
85 * Returns the session identifier.
86 */
87 QByteArray sessionId() const;
88
89 /**
90 * Returns the default session for this thread.
91 */
92 static Session *defaultSession();
93
94 /**
95 * Stops all jobs queued for execution.
96 */
97 void clear();
98
99Q_SIGNALS:
100 /**
101 * This signal is emitted whenever the session has been reconnected
102 * to the server (e.g. after a server crash).
103 *
104 * @since 4.6
105 */
106 void reconnected();
107
108protected:
109 /**
110 * Creates a new session with shared private object.
111 *
112 * @param d The private object.
113 * @param sessionId The identifier for this session, will be a
114 * random value if empty.
115 * @param parent The parent object.
116 *
117 * @note This constructor is needed for unit testing only.
118 */
119 explicit Session(SessionPrivate *d, const QByteArray &sessionId = QByteArray(), QObject *parent = 0);
120
121private:
122 //@cond PRIVATE
123 SessionPrivate *const d;
124 friend class ::FakeSession;
125
126 Q_PRIVATE_SLOT(d, void reconnect())
127 Q_PRIVATE_SLOT(d, void socketError(QLocalSocket::LocalSocketError))
128 Q_PRIVATE_SLOT(d, void socketError(QAbstractSocket::SocketError))
129 Q_PRIVATE_SLOT(d, void socketDisconnected())
130 Q_PRIVATE_SLOT(d, void dataReceived())
131 Q_PRIVATE_SLOT(d, void doStartNext())
132 Q_PRIVATE_SLOT(d, void jobDone(KJob *))
133 Q_PRIVATE_SLOT(d, void jobWriteFinished(Akonadi::Job *))
134 Q_PRIVATE_SLOT(d, void jobDestroyed(QObject *))
135 Q_PRIVATE_SLOT(d, void serverStateChanged(Akonadi::ServerManager::State))
136 //@endcond PRIVATE
137};
138
139}
140
141#endif
142