1/*
2 Copyright (c) 2009 Kevin Ottens <ervin@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 KIMAP_IDLEJOB_H
21#define KIMAP_IDLEJOB_H
22
23#include "kimap_export.h"
24
25#include "imapset.h"
26#include "job.h"
27
28#include "kmime/kmime_content.h"
29#include "kmime/kmime_message.h"
30
31#include <boost/shared_ptr.hpp>
32
33namespace KIMAP {
34
35class Session;
36struct Message;
37class IdleJobPrivate;
38
39/**
40 * Idles the connection to the IMAP server.
41 *
42 * This job can be run while the client has no other use
43 * for the connection, and the server will send updates
44 * about the selected mailbox.
45 *
46 * Note that although the server may send a variety of
47 * responses while the job is running (including EXPUNGE,
48 * for example), only RECENT and EXISTS responses are
49 * actually reported by this job.
50 *
51 * The job also processes updates in pairs - if the server
52 * sends an EXISTS update but not a RECENT one (because
53 * another client is changing the mailbox contents), this
54 * job will not report the update.
55 *
56 * It only makes sense to run this job when the session is
57 * in the selected state.
58 *
59 * This job requires that the server supports the IDLE
60 * capability, defined in
61 * <a href="http://www.apps.ietf.org/rfc/rfc2177.html">RFC 2177</a>.
62 */
63class KIMAP_EXPORT IdleJob : public Job
64{
65 Q_OBJECT
66 Q_DECLARE_PRIVATE( IdleJob )
67
68 public:
69 explicit IdleJob( Session *session );
70 virtual ~IdleJob();
71
72 /**
73 * The last mailbox status that was reported.
74 *
75 * This is just the session's selected mailbox.
76 */
77 QString lastMailBox() const;
78 /**
79 * The last message count that was reported.
80 *
81 * The server will send updates about the number of
82 * messages in the mailbox when that number changes.
83 * This is the last number it reported.
84 *
85 * @return the last message count the server reported,
86 * or -1 if it has not reported a message count
87 * since the job started.
88 */
89 int lastMessageCount() const;
90 /**
91 * The last recent message count that was reported.
92 *
93 * The server will send updates about the number of
94 * messages in the mailbox that are tagged with \Recent
95 * when that number changes. This is the last number it
96 * reported.
97 *
98 * @return the last recent message count the server reported,
99 * or -1 if it has not reported a recent message count
100 * since the job started.
101 */
102 int lastRecentCount() const;
103
104 public Q_SLOTS:
105 /**
106 * Stops the idle job.
107 */
108 void stop();
109
110 Q_SIGNALS:
111 /**
112 * Signals that the server has notified that the total and
113 * recent message counts have changed.
114 *
115 * @param job this object
116 * @param mailBox the selected mailbox
117 * @param messageCount the new total message count reported by the server
118 * @param recentCount the new "recent message" count reported by the server
119 */
120 void mailBoxStats(KIMAP::IdleJob *job, const QString &mailBox, int messageCount, int recentCount);
121
122 /**
123 * Signals that the server has notified that the some messages flags
124 * have changed
125 *
126 * @param job this object
127 * @param uid UID of message that has changed
128 * @since 4.12
129 */
130 void mailBoxMessageFlagsChanged(KIMAP::IdleJob *job, qint64 uid);
131
132 protected:
133 virtual void doStart();
134 virtual void handleResponse(const Message &response);
135
136 private:
137 Q_PRIVATE_SLOT( d_func(), void emitStats() )
138 Q_PRIVATE_SLOT( d_func(), void resetTimeout() )
139};
140
141}
142
143#endif
144