NeoMutt  2023-03-22-27-g3cb248
Teaching an old dog new tricks
DOXYGEN
email.h File Reference

Representation of an email. More...

#include "config.h"
#include <stdbool.h>
#include <time.h>
#include "mutt/lib.h"
#include "ncrypt/lib.h"
#include "tags.h"
+ Include dependency graph for email.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  Email
 The envelope/body of an email. More...
 
struct  EmailNode
 List of Emails. More...
 
struct  EventEmail
 An Event that happened to an Email. More...
 
struct  EventHeader
 An event that happened to a header. More...
 

Enumerations

enum  NotifyEmail {
  NT_EMAIL_ADD = 1 , NT_EMAIL_DELETE , NT_EMAIL_DELETE_ALL , NT_EMAIL_CHANGE ,
  NT_EMAIL_CHANGE_ENVELOPE , NT_EMAIL_CHANGE_ATTACH , NT_EMAIL_CHANGE_SECURITY
}
 Types of Email Event. More...
 
enum  NotifyHeader { NT_HEADER_ADD = 1 , NT_HEADER_DELETE , NT_HEADER_CHANGE }
 Types of Header Event. More...
 

Functions

 STAILQ_HEAD (EmailList, EmailNode)
 
bool email_cmp_strict (const struct Email *e1, const struct Email *e2)
 Strictly compare message emails. More...
 
void email_free (struct Email **ptr)
 Free an Email. More...
 
struct Emailemail_new (void)
 Create a new Email. More...
 
size_t email_size (const struct Email *e)
 Compute the size of an email. More...
 
int emaillist_add_email (struct EmailList *el, struct Email *e)
 Add an Email to a list. More...
 
void emaillist_clear (struct EmailList *el)
 Drop a private list of Emails. More...
 
struct ListNodeheader_add (struct ListHead *hdrlist, const char *header)
 Add a header to a list. More...
 
struct ListNodeheader_find (const struct ListHead *hdrlist, const char *header)
 Find a header, matching on its field, in a list of headers. More...
 
void header_free (struct ListHead *hdrlist, struct ListNode *target)
 Free and remove a header from a header list. More...
 
struct ListNodeheader_set (struct ListHead *hdrlist, const char *header)
 Set a header value in a list. More...
 
struct ListNodeheader_update (struct ListNode *hdrnode, const char *header)
 Update an existing header. More...
 

Detailed Description

Representation of an email.

Authors
  • Richard Russon

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file email.h.

Enumeration Type Documentation

◆ NotifyEmail

Types of Email Event.

Observers of NT_EMAIL will be passed an EventEmail.

Note
Delete notifications are sent before the object is deleted.
Other notifications are sent after the event.
Enumerator
NT_EMAIL_ADD 

Email has been added.

NT_EMAIL_DELETE 

Email is about to be deleted.

NT_EMAIL_DELETE_ALL 

All the Emails are about to be deleted.

NT_EMAIL_CHANGE 

Email has changed.

NT_EMAIL_CHANGE_ENVELOPE 

Email's Envelope has changed.

NT_EMAIL_CHANGE_ATTACH 

Email's Attachments have changed.

NT_EMAIL_CHANGE_SECURITY 

Email's security settings have changed.

Definition at line 145 of file email.h.

146{
147 NT_EMAIL_ADD = 1,
154};
@ NT_EMAIL_ADD
Email has been added.
Definition: email.h:147
@ NT_EMAIL_DELETE
Email is about to be deleted.
Definition: email.h:148
@ NT_EMAIL_CHANGE_SECURITY
Email's security settings have changed.
Definition: email.h:153
@ NT_EMAIL_DELETE_ALL
All the Emails are about to be deleted.
Definition: email.h:149
@ NT_EMAIL_CHANGE
Email has changed.
Definition: email.h:150
@ NT_EMAIL_CHANGE_ATTACH
Email's Attachments have changed.
Definition: email.h:152
@ NT_EMAIL_CHANGE_ENVELOPE
Email's Envelope has changed.
Definition: email.h:151

◆ NotifyHeader

Types of Header Event.

Observers of NT_HEADER will be passed an EventHeader.

Enumerator
NT_HEADER_ADD 

Header has been added.

NT_HEADER_DELETE 

Header has been removed.

NT_HEADER_CHANGE 

An existing header has been changed.

Definition at line 170 of file email.h.

171{
172 NT_HEADER_ADD = 1,
175};
@ NT_HEADER_CHANGE
An existing header has been changed.
Definition: email.h:174
@ NT_HEADER_ADD
Header has been added.
Definition: email.h:172
@ NT_HEADER_DELETE
Header has been removed.
Definition: email.h:173

Function Documentation

◆ STAILQ_HEAD()

STAILQ_HEAD ( EmailList  ,
EmailNode   
)

◆ email_cmp_strict()

bool email_cmp_strict ( const struct Email e1,
const struct Email e2 
)

Strictly compare message emails.

Parameters
e1First Email
e2Second Email
Return values
trueEmails are strictly identical

Definition at line 100 of file email.c.

101{
102 if (e1 && e2)
103 {
104 if ((e1->received != e2->received) || (e1->date_sent != e2->date_sent) ||
105 (e1->body->length != e2->body->length) || (e1->lines != e2->lines) ||
106 (e1->zhours != e2->zhours) || (e1->zminutes != e2->zminutes) ||
107 (e1->zoccident != e2->zoccident) || (e1->mime != e2->mime) ||
108 !mutt_env_cmp_strict(e1->env, e2->env) || !mutt_body_cmp_strict(e1->body, e2->body))
109 {
110 return false;
111 }
112 return true;
113 }
114 else
115 {
116 return (!e1 && !e2);
117 }
118}
bool mutt_body_cmp_strict(const struct Body *b1, const struct Body *b2)
Strictly compare two email Body's.
Definition: body.c:108
bool mutt_env_cmp_strict(const struct Envelope *e1, const struct Envelope *e2)
Strictly compare two Envelopes.
Definition: envelope.c:258
LOFF_T length
length (in bytes) of attachment
Definition: body.h:53
unsigned int zminutes
Minutes away from UTC.
Definition: email.h:55
struct Envelope * env
Envelope information.
Definition: email.h:66
bool mime
Has a MIME-Version header?
Definition: email.h:46
int lines
How many lines in the body of this message?
Definition: email.h:60
struct Body * body
List of MIME parts.
Definition: email.h:67
bool zoccident
True, if west of UTC, False if east.
Definition: email.h:56
unsigned int zhours
Hours away from UTC.
Definition: email.h:54
time_t date_sent
Time when the message was sent (UTC)
Definition: email.h:58
time_t received
Time when the message was placed in the mailbox.
Definition: email.h:59
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ email_free()

void email_free ( struct Email **  ptr)

Free an Email.

Parameters
[out]ptrEmail to free

Definition at line 44 of file email.c.

45{
46 if (!ptr || !*ptr)
47 return;
48
49 struct Email *e = *ptr;
50
51 mutt_debug(LL_NOTIFY, "NT_EMAIL_DELETE: %p\n", e);
52 struct EventEmail ev_e = { 1, &e };
54
55 if (e->edata_free && e->edata)
56 e->edata_free(&e->edata);
57
58 mutt_env_free(&e->env);
60 FREE(&e->tree);
61 FREE(&e->path);
62#ifdef MIXMASTER
64#endif
65#ifdef USE_NOTMUCH
67#endif
70
71 FREE(ptr);
72}
void mutt_body_free(struct Body **ptr)
Free a Body.
Definition: body.c:57
void nm_edata_free(void **ptr)
Free data attached to an Email.
Definition: edata.c:42
void mutt_env_free(struct Envelope **ptr)
Free an Envelope.
Definition: envelope.c:97
#define mutt_debug(LEVEL,...)
Definition: logging.h:84
void mutt_list_free(struct ListHead *h)
Free a List AND its strings.
Definition: list.c:122
@ LL_NOTIFY
Log of notifications.
Definition: logging.h:45
#define FREE(x)
Definition: memory.h:43
bool notify_send(struct Notify *notify, enum NotifyType event_type, int event_subtype, void *event_data)
Send out a notification message.
Definition: notify.c:171
void notify_free(struct Notify **ptr)
Free a notification handler.
Definition: notify.c:73
@ NT_EMAIL
Email has changed, NotifyEmail, EventEmail.
Definition: notify_type.h:44
The envelope/body of an email.
Definition: email.h:37
void * edata
Driver-specific data.
Definition: email.h:72
void * nm_edata
Notmuch private data.
Definition: email.h:92
char * tree
Character string to print thread tree.
Definition: email.h:124
void(* edata_free)(void **ptr)
Free the private data attached to the Email.
Definition: email.h:86
struct ListHead chain
Mixmaster chain.
Definition: email.h:89
struct TagList tags
For drivers that support server tagging.
Definition: email.h:70
struct Notify * notify
Notifications: NotifyEmail, EventEmail.
Definition: email.h:71
char * path
Path of Email (for local Mailboxes)
Definition: email.h:68
An Event that happened to an Email.
Definition: email.h:160
void driver_tags_free(struct TagList *list)
Free tags from a header.
Definition: tags.c:107
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ email_new()

struct Email * email_new ( void  )

Create a new Email.

Return values
ptrNewly created Email

Definition at line 78 of file email.c.

79{
80 static size_t sequence = 0;
81
82 struct Email *e = mutt_mem_calloc(1, sizeof(struct Email));
83#ifdef MIXMASTER
84 STAILQ_INIT(&e->chain);
85#endif
86 STAILQ_INIT(&e->tags);
87 e->visible = true;
88 e->sequence = sequence++;
89 e->notify = notify_new();
90
91 return e;
92}
void * mutt_mem_calloc(size_t nmemb, size_t size)
Allocate zeroed memory on the heap.
Definition: memory.c:50
struct Notify * notify_new(void)
Create a new notifications handler.
Definition: notify.c:60
#define STAILQ_INIT(head)
Definition: queue.h:372
bool visible
Is this message part of the view?
Definition: email.h:120
size_t sequence
Sequence number assigned on creation.
Definition: email.h:65
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ email_size()

size_t email_size ( const struct Email e)

Compute the size of an email.

Parameters
eEmail
Return values
numSize of the email, in bytes

Definition at line 125 of file email.c.

126{
127 if (!e || !e->body)
128 return 0;
129 return e->body->length + e->body->offset - e->body->hdr_offset;
130}
LOFF_T offset
offset where the actual data begins
Definition: body.h:52
long hdr_offset
Offset in stream where the headers begin.
Definition: body.h:80
+ Here is the caller graph for this function:

◆ emaillist_add_email()

int emaillist_add_email ( struct EmailList *  el,
struct Email e 
)

Add an Email to a list.

Parameters
eEmail to add
elEmailList to add to
Return values
0Success
-1Error

Definition at line 159 of file email.c.

160{
161 if (!el || !e)
162 return -1;
163
164 struct EmailNode *en = mutt_mem_calloc(1, sizeof(*en));
165 en->email = e;
166 STAILQ_INSERT_TAIL(el, en, entries);
167
168 return 0;
169}
#define STAILQ_INSERT_TAIL(head, elm, field)
Definition: queue.h:389
List of Emails.
Definition: email.h:131
struct Email * email
Email in the list.
Definition: email.h:132
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ emaillist_clear()

void emaillist_clear ( struct EmailList *  el)

Drop a private list of Emails.

Parameters
elEmailList to empty

The Emails are not freed.

Definition at line 138 of file email.c.

139{
140 if (!el)
141 return;
142
143 struct EmailNode *en = NULL, *tmp = NULL;
144 STAILQ_FOREACH_SAFE(en, el, entries, tmp)
145 {
146 STAILQ_REMOVE(el, en, EmailNode, entries);
147 FREE(&en);
148 }
149 STAILQ_INIT(el);
150}
#define STAILQ_REMOVE(head, elm, type, field)
Definition: queue.h:402
#define STAILQ_FOREACH_SAFE(var, head, field, tvar)
Definition: queue.h:362
+ Here is the caller graph for this function:

◆ header_add()

struct ListNode * header_add ( struct ListHead *  hdrlist,
const char *  header 
)

Add a header to a list.

Parameters
hdrlistList of headers to search
headerString to set as the header
Return values
nodeThe created header

Definition at line 203 of file email.c.

204{
205 struct ListNode *n = mutt_list_insert_tail(hdrlist, NULL);
206 n->data = mutt_str_dup(header);
207
208 return n;
209}
struct ListNode * mutt_list_insert_tail(struct ListHead *h, char *s)
Append a string to the end of a List.
Definition: list.c:64
char * mutt_str_dup(const char *str)
Copy a string, safely.
Definition: string.c:250
A List node for strings.
Definition: list.h:35
char * data
String.
Definition: list.h:36
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ header_find()

struct ListNode * header_find ( const struct ListHead *  hdrlist,
const char *  header 
)

Find a header, matching on its field, in a list of headers.

Parameters
hdrlistList of headers to search
headerThe header to search for
Return values
nodeThe node in the list matching the header
NULLNo matching header is found

The header should either of the form "X-Header:" or "X-Header: value"

Definition at line 180 of file email.c.

181{
182 const char *key_end = strchr(header, ':');
183 if (!key_end)
184 return NULL;
185
186 const int keylen = key_end - header + 1;
187
188 struct ListNode *n = NULL;
189 STAILQ_FOREACH(n, hdrlist, entries)
190 {
191 if (mutt_istrn_equal(n->data, header, keylen))
192 return n;
193 }
194 return n;
195}
bool mutt_istrn_equal(const char *a, const char *b, size_t num)
Check for equality of two strings ignoring case (to a maximum), safely.
Definition: string.c:524
#define STAILQ_FOREACH(var, head, field)
Definition: queue.h:352
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ header_free()

void header_free ( struct ListHead *  hdrlist,
struct ListNode target 
)

Free and remove a header from a header list.

Parameters
hdrlistList to free the header from
targetThe header to free

Definition at line 245 of file email.c.

246{
247 STAILQ_REMOVE(hdrlist, target, ListNode, entries);
248 FREE(&target->data);
249 FREE(&target);
250}
+ Here is the caller graph for this function:

◆ header_set()

struct ListNode * header_set ( struct ListHead *  hdrlist,
const char *  header 
)

Set a header value in a list.

Parameters
hdrlistList of headers to search
headerString to set the value of the header to
Return values
nodeThe updated or created header

If a header exists with the same field, update it, otherwise add a new header.

Definition at line 233 of file email.c.

234{
235 struct ListNode *n = header_find(hdrlist, header);
236
237 return n ? header_update(n, header) : header_add(hdrlist, header);
238}
struct ListNode * header_add(struct ListHead *hdrlist, const char *header)
Add a header to a list.
Definition: email.c:203
struct ListNode * header_update(struct ListNode *hdr, const char *header)
Update an existing header.
Definition: email.c:217
struct ListNode * header_find(const struct ListHead *hdrlist, const char *header)
Find a header, matching on its field, in a list of headers.
Definition: email.c:180
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ header_update()

struct ListNode * header_update ( struct ListNode hdr,
const char *  header 
)

Update an existing header.

Parameters
hdrThe header to update
headerString to update the header with
Return values
nodeThe updated header

Definition at line 217 of file email.c.

218{
219 FREE(&hdr->data);
220 hdr->data = mutt_str_dup(header);
221
222 return hdr;
223}
+ Here is the call graph for this function:
+ Here is the caller graph for this function: