KMbox

mbox.h
1/*
2 SPDX-FileCopyrightText: 2009 Bertjan Broeksema <broeksema@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "kmbox_export.h"
10#include "mboxentry.h"
11#include <memory>
12
13#include <KMime/Message>
14
15namespace KMBox
16{
17class MBoxPrivate;
18
19/**
20 * @short A class to access mail storages in MBox format.
21 *
22 * @author Bertjan Broeksema <broeksema@kde.org>
23 * @since 4.6
24 */
25class KMBOX_EXPORT MBox
26{
27public:
28 /**
29 * Describes the type of locking that will be used.
30 */
31 enum LockType {
32 ProcmailLockfile,
33 MuttDotlock,
34 MuttDotlockPrivileged,
35 None
36 };
37
38 /**
39 * Creates a new mbox object.
40 */
41 MBox();
42
43 /**
44 * Destroys the mbox object.
45 *
46 * The file will be unlocked if it is still open.
47 */
48 ~MBox();
49
50 /**
51 * Appends @p message to the MBox and returns the corresponding mbox entry for it.
52 * You must load a mbox file by making a call to load( const QString& ) before
53 * appending entries.
54 * The returned mbox entry is <em>only</em> valid for that particular file.
55 *
56 * @param message The message to append to the mbox.
57 * @return the corresponding mbox entry for the message in the file or an invalid mbox entry
58 * if the message was not added.
59 */
60 [[nodiscard]] MBoxEntry appendMessage(const KMime::Message::Ptr &message);
61
62 /**
63 * Retrieve the mbox entry objects for all emails from the file except the
64 * @p deleteEntries.
65 * The @p deletedEntries should be a list of mbox entries with offsets of deleted messages.
66 * @param deletedEntries list of mbox entries that have been deleted and need not be retrieved
67 * Note: One <em>must</em> call load() before calling this method.
68 */
69 [[nodiscard]] MBoxEntry::List entries(const MBoxEntry::List &deletedEntries = MBoxEntry::List()) const;
70
71 /**
72 * Returns the file name that was passed to the last call to load().
73 */
74 [[nodiscard]] QString fileName() const;
75
76 /**
77 * Loads the raw mbox data from disk into the current MBox object. Messages
78 * already present are <em>not</em> preserved. This method does not load the
79 * full messages into memory but only the offsets of the messages and their
80 * sizes. If the file currently is locked this method will do nothing and
81 * return false. Appended messages that are not written yet will get lost.
82 *
83 * @param fileName the name of the mbox on disk.
84 * @return true, if successful, false on error.
85 *
86 * @see save( const QString & )
87 */
88 [[nodiscard]] bool load(const QString &fileName);
89
90 /**
91 * Locks the mbox file using the configured lock method. This can be used
92 * for consecutive calls to readMessage and readMessageHeaders. Calling lock()
93 * before these calls prevents the mbox file being locked for every call.
94 *
95 * NOTE: Even when the lock method is None the mbox is internally marked as
96 * locked. This means that it must be unlocked before calling load().
97 *
98 * @return true if locked successful, false on error.
99 *
100 * @see setLockType( LockType ), unlock()
101 */
102 [[nodiscard]] bool lock();
103
104 /**
105 * Returns whether or not the mbox currently is locked.
106 */
107 [[nodiscard]] bool locked() const;
108
109 /**
110 * Removes all messages for the given mbox entries from the current reference file
111 * (the file that is loaded with load( const QString & ).
112 * This method will first check if all lines at the offsets are actually
113 * separator lines if this is not then no message will be deleted to prevent
114 * corruption.
115 *
116 * @param deletedEntries The mbox entries of the messages that should be removed from
117 * the file.
118 * @param movedEntries Optional list for storing pairs of mbox entries that got moved
119 * within the file due to the deletions.
120 * The @c first member of the pair is the entry with the original offsets
121 * the @c second member is the entry with the new (current) offset
122 *
123 * @return true if all offsets refer to a mbox separator line and a file was
124 * loaded, false otherwise. If the latter, the physical file has
125 * not changed.
126 */
127 [[nodiscard]] bool purge(const MBoxEntry::List &deletedEntries, QList<MBoxEntry::Pair> *movedEntries = nullptr);
128
129 /**
130 * Reads the entire message from the file for the given mbox @p entry. If the
131 * mbox file is not locked this method will lock the file before reading and
132 * unlock it after reading. If the file already is locked, it will not
133 * unlock the file after reading the entry.
134 *
135 * @param entry The entry in the mbox file.
136 * @return Message for the given entry or 0 if the file could not be locked
137 * or the entry offset > fileSize.
138 *
139 * @see lock(), unlock()
140 */
141 KMime::Message *readMessage(const MBoxEntry &entry);
142
143 /**
144 * Reads the headers of the message for the given mbox @p entry. If the
145 * mbox file is not locked this method will lock the file before reading and
146 * unlock it after reading. If the file already is locked, it will not
147 * unlock the file after reading the entry.
148 *
149 * @param entry The entry in the mbox file.
150 * @return QByteArray containing the raw message header data.
151 *
152 * @see lock(), unlock()
153 */
154 [[nodiscard]] QByteArray readMessageHeaders(const MBoxEntry &entry);
155
156 /**
157 * Reads the entire message from the file for the given mbox @p entry. If the
158 * mbox file is not locked this method will lock the file before reading and
159 * unlock it after reading. If the file already is locked, it will not
160 * unlock the file after reading the entry.
161 *
162 * @param entry The entry in the mbox file.
163 * @return QByteArray containing the raw message data.
164 *
165 * @see lock(), unlock()
166 */
167 [[nodiscard]] QByteArray readRawMessage(const MBoxEntry &entry);
168
169 /**
170 * Writes the mbox to disk. If the fileName is empty only appended messages
171 * will be written to the file that was passed to load( const QString & ).
172 * Otherwise the contents of the file that was loaded with load is copied to
173 * @p fileName first.
174 *
175 * @param fileName the name of the file
176 * @return true if the save was successful; false otherwise.
177 *
178 * @see load( const QString & )
179 */
180 [[nodiscard]] bool save(const QString &fileName = QString());
181
182 /**
183 * Sets the locktype that should be used for locking the mbox file. If the
184 * new LockType cannot be used (e.g. the lockfile executable could not be
185 * found) the LockType will not be changed.
186 * @param ltype the locktype to set
187 * This method will not do anything if the mbox object is currently locked
188 * to make sure that it doesn't leave a locked file for one of the lockfile
189 * / mutt_dotlock methods.
190 */
191 [[nodiscard]] bool setLockType(LockType ltype);
192
193 /**
194 * Sets the lockfile that should be used by the procmail or the KDE lock
195 * file method. If this method is not called and one of the before mentioned
196 * lock methods is used the name of the lock file will be equal to
197 * MBOXFILENAME.lock.
198 * @param lockFile the lockfile to set
199 */
200 void setLockFile(const QString &lockFile);
201
202 /**
203 * By default the unlock method will directly unlock the file. However this
204 * is expensive in case of many consecutive calls to readEntry. Setting the
205 * time out to a non zero value will keep the lock open until the timeout has
206 * passed. On each read the timer will be reset.
207 * @param msec the time out to set for file lock
208 */
209 void setUnlockTimeout(int msec);
210
211 /**
212 * Unlock the mbox file.
213 *
214 * @return true if the unlock was successful, false otherwise.
215 *
216 * @see lock()
217 */
218 [[nodiscard]] bool unlock();
219 /**
220 * Set the access mode of the mbox file to read only.
221 *
222 * If this is set to true, the mbox file can only be read from disk.
223 * When the mbox file given in load() can not be opened in readWrite mode,
224 * but can be opened in readOnly mode, this flag is automatically set to true.
225 * You can still append messages, which are stored in memory
226 * until save() is called, but the mbox can not be saved/purged to itself.
227 * However it is possible to save it to a different file.
228 * @param ro the readOnly flag to use
229 *
230 * @see save( const QString & )
231 *
232 * @since 4.14.5
233 */
234 void setReadOnly(bool ro = true);
235
236 /**
237 * Returns if the current access mode is set to readOnly.
238 *
239 * The access mode can either be set explicitly with setReadOnly() or
240 * implicitly by calling load() on a readOnly file.
241 *
242 * @since 4.14.5
243 */
244 [[nodiscard]] bool isReadOnly() const;
245
246private:
247 //@cond PRIVATE
248 Q_DISABLE_COPY(MBox)
249 std::unique_ptr<class MBoxPrivate> const d;
250 //@endcond
251};
252}
A class that encapsulates an entry of a MBox.
Definition mboxentry.h:25
A class to access mail storages in MBox format.
Definition mbox.h:26
LockType
Describes the type of locking that will be used.
Definition mbox.h:31
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:02:06 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.