1 /**
2 * @file
3 * Representation of a mailbox
4 *
5 * @authors
6 * Copyright (C) 1996-2000,2010,2013 Michael R. Elkins <me@mutt.org>
7 * Copyright (C) 2018-2019 Richard Russon <rich@flatcap.org>
8 *
9 * @copyright
10 * This program is free software: you can redistribute it and/or modify it under
11 * the terms of the GNU General Public License as published by the Free Software
12 * Foundation, either version 2 of the License, or (at your option) any later
13 * version.
14 *
15 * This program is distributed in the hope that it will be useful, but WITHOUT
16 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * details.
19 *
20 * You should have received a copy of the GNU General Public License along with
21 * this program. If not, see <http://www.gnu.org/licenses/>.
22 */
23
24 #ifndef MUTT_CORE_MAILBOX_H
25 #define MUTT_CORE_MAILBOX_H
26
27 #include "config.h"
28 #include <stdbool.h>
29 #include <stdint.h>
30 #include <sys/types.h>
31 #include <time.h>
32 #include "mutt/lib.h"
33
34 struct ConfigSubset;
35 struct Email;
36
37 #define MB_NORMAL 0
38 #define MB_HIDDEN 1
39
40 /**
41 * enum MailboxType - Supported mailbox formats
42 */
43 enum MailboxType
44 {
45 MUTT_MAILBOX_ANY = -2, ///< Match any Mailbox type
46 MUTT_MAILBOX_ERROR = -1, ///< Error occurred examining Mailbox
47 MUTT_UNKNOWN = 0, ///< Mailbox wasn't recognised
48 MUTT_MBOX, ///< 'mbox' Mailbox type
49 MUTT_MMDF, ///< 'mmdf' Mailbox type
50 MUTT_MH, ///< 'MH' Mailbox type
51 MUTT_MAILDIR, ///< 'Maildir' Mailbox type
52 MUTT_NNTP, ///< 'NNTP' (Usenet) Mailbox type
53 MUTT_IMAP, ///< 'IMAP' Mailbox type
54 MUTT_NOTMUCH, ///< 'Notmuch' (virtual) Mailbox type
55 MUTT_POP, ///< 'POP3' Mailbox type
56 MUTT_COMPRESSED, ///< Compressed file Mailbox type
57 };
58
59 /**
60 * ACL Rights - These show permission to...
61 */
62 typedef uint16_t AclFlags; ///< Flags, e.g. #MUTT_ACL_ADMIN
63 #define MUTT_ACL_NO_FLAGS 0 ///< No flags are set
64 #define MUTT_ACL_ADMIN (1 << 0) ///< Administer the account (get/set permissions)
65 #define MUTT_ACL_CREATE (1 << 1) ///< Create a mailbox
66 #define MUTT_ACL_DELETE (1 << 2) ///< Delete a message
67 #define MUTT_ACL_DELMX (1 << 3) ///< Delete a mailbox
68 #define MUTT_ACL_EXPUNGE (1 << 4) ///< Expunge messages
69 #define MUTT_ACL_INSERT (1 << 5) ///< Add/copy into the mailbox (used when editing a message)
70 #define MUTT_ACL_LOOKUP (1 << 6) ///< Lookup mailbox (visible to 'list')
71 #define MUTT_ACL_POST (1 << 7) ///< Post (submit messages to the server)
72 #define MUTT_ACL_READ (1 << 8) ///< Read the mailbox
73 #define MUTT_ACL_SEEN (1 << 9) ///< Change the 'seen' status of a message
74 #define MUTT_ACL_WRITE (1 << 10) ///< Write to a message (for flagging or linking threads)
75
76 #define MUTT_ACL_ALL ((1 << 11) - 1)
77
78 /**
79 * struct Mailbox - A mailbox
80 */
81 struct Mailbox
82 {
83 struct Buffer pathbuf; ///< Path of the Mailbox
84 char *realpath; ///< Used for duplicate detection, context comparison, and the sidebar
85 char *name; ///< A short name for the Mailbox
86 struct ConfigSubset *sub; ///< Inherited config items
87 off_t size; ///< Size of the Mailbox
88 bool has_new; ///< Mailbox has new mail
89
90 // These next three are only set when MailCheckStats is set
91 int msg_count; ///< Total number of messages
92 int msg_unread; ///< Number of unread messages
93 int msg_flagged; ///< Number of flagged messages
94
95 int msg_new; ///< Number of new messages
96 int msg_deleted; ///< Number of deleted messages
97 int msg_tagged; ///< How many messages are tagged?
98
99 struct Email **emails; ///< Array of Emails
100 int email_max; ///< Number of pointers in emails
101 int *v2r; ///< Mapping from virtual to real msgno
102 int vcount; ///< The number of virtual messages
103
104 bool notified; ///< User has been notified
105 enum MailboxType type; ///< Mailbox type
106 bool newly_created; ///< Mbox or mmdf just popped into existence
107 struct timespec mtime; ///< Time Mailbox was last changed
108 struct timespec last_visited; ///< Time of last exit from this mailbox
109 struct timespec stats_last_checked; ///< Mtime of mailbox the last time stats where checked.
110
111 const struct MxOps *mx_ops; ///< MXAPI callback functions
112
113 bool append : 1; ///< Mailbox is opened in append mode
114 bool changed : 1; ///< Mailbox has been modified
115 bool dontwrite : 1; ///< Don't write the mailbox on close
116 bool first_check_stats_done : 1; ///< True when the check have been done at least on time
117 bool peekonly : 1; ///< Just taking a glance, revert atime
118 bool verbose : 1; ///< Display status messages?
119 bool readonly : 1; ///< Don't allow changes to the mailbox
120
121 AclFlags rights; ///< ACL bits, see #AclFlags
122
123 #ifdef USE_COMP_MBOX
124 void *compress_info; ///< Compressed mbox module private data
125 #endif
126
127 struct HashTable *id_hash; ///< Hash Table by msg id
128 struct HashTable *subj_hash; ///< Hash Table by subject
129 struct HashTable *label_hash; ///< Hash Table for x-labels
130
131 struct Account *account; ///< Account that owns this Mailbox
132 int opened; ///< Number of times mailbox is opened
133
134 uint8_t flags; ///< e.g. #MB_NORMAL
135
136 void *mdata; ///< Driver specific data
137
138 /**
139 * mdata_free - Free the private data attached to the Mailbox
140 * @param ptr Private data to be freed
141 *
142 * **Contract**
143 * - @a ptr is not NULL
144 * - @a *ptr is not NULL
145 */
146 void (*mdata_free)(void **ptr);
147
148 struct Notify *notify; ///< Notifications: #NotifyMailbox, #EventMailbox
149
150 int gen; ///< Generation number, for sorting
151 };
152
153 /**
154 * struct MailboxNode - List of Mailboxes
155 */
156 struct MailboxNode
157 {
158 struct Mailbox *mailbox; ///< Mailbox in the list
159 STAILQ_ENTRY(MailboxNode) entries; ///< Linked list
160 };
161 STAILQ_HEAD(MailboxList, MailboxNode);
162
163 /**
164 * enum NotifyMailbox - Types of Mailbox Event
165 *
166 * Observers of #NT_MAILBOX will be passed an #EventMailbox.
167 *
168 * @note Delete notifications are sent **before** the object is deleted.
169 * @note Other notifications are sent **after** the event.
170 */
171 enum NotifyMailbox
172 {
173 NT_MAILBOX_ADD = 1, ///< Mailbox has been added
174 NT_MAILBOX_DELETE, ///< Mailbox is about to be deleted
175 NT_MAILBOX_DELETE_ALL, ///< All Mailboxes are about to be deleted
176 NT_MAILBOX_CHANGE, ///< Mailbox has been changed
177
178 /* These don't really belong here as they are tied to GUI operations.
179 * Eventually, they'll be eliminated. */
180 NT_MAILBOX_INVALID, ///< Email list was changed
181 NT_MAILBOX_RESORT, ///< Email list needs resorting
182 NT_MAILBOX_SWITCH, ///< Current Mailbox has changed
183 NT_MAILBOX_UPDATE, ///< Update internal tables
184 NT_MAILBOX_UNTAG, ///< Clear the 'last-tagged' pointer
185 };
186
187 /**
188 * struct EventMailbox - An Event that happened to a Mailbox
189 */
190 struct EventMailbox
191 {
192 struct Mailbox *mailbox; ///< The Mailbox this Event relates to
193 };
194
195 void mailbox_changed (struct Mailbox *m, enum NotifyMailbox action);
196 struct Mailbox *mailbox_find (const char *path);
197 struct Mailbox *mailbox_find_name (const char *name);
198 void mailbox_free (struct Mailbox **ptr);
199 int mailbox_gen (void);
200 struct Mailbox *mailbox_new (void);
201 bool mailbox_set_subset(struct Mailbox *m, struct ConfigSubset *sub);
202 void mailbox_size_add (struct Mailbox *m, const struct Email *e);
203 void mailbox_size_sub (struct Mailbox *m, const struct Email *e);
204 void mailbox_update (struct Mailbox *m);
205 void mailbox_gc_add (struct Email *e);
206 void mailbox_gc_run (void);
207
208 const char *mailbox_get_type_name(enum MailboxType type);
209
210 /**
211 * mailbox_path - Get the Mailbox's path string
212 * @param m Mailbox
213 * @retval ptr Path string
214 */
mailbox_path(const struct Mailbox * m)215 static inline const char *mailbox_path(const struct Mailbox *m) // LCOV_EXCL_LINE
216 {
217 return mutt_buffer_string(&m->pathbuf); // LCOV_EXCL_LINE
218 }
219
220 #endif /* MUTT_CORE_MAILBOX_H */
221