NeoMutt  2021-02-05-89-gabe350
Teaching an old dog new tricks
DOXYGEN
email.h File Reference
#include "config.h"
#include <stddef.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_REMOVE }
 Types of Email Event. More...
 
enum  NotifyHeader { NT_HEADER_ADD = 1, NT_HEADER_CHANGE, NT_HEADER_REMOVE }
 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.

Enumerator
NT_EMAIL_ADD 

A new Email has just been created.

NT_EMAIL_REMOVE 

An Email is about to be destroyed.

Definition at line 137 of file email.h.

138 {
139  NT_EMAIL_ADD = 1,
141 };

◆ NotifyHeader

Types of Header Event.

Observers on NT_HEADER will be passed an EventHeader

Enumerator
NT_HEADER_ADD 

A new header has been added.

NT_HEADER_CHANGE 

An existing header has been changed.

NT_HEADER_REMOVE 

A header is about to be removed.

Definition at line 157 of file email.h.

158 {
159  NT_HEADER_ADD = 1,
162 };

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 92 of file email.c.

93 {
94  if (e1 && e2)
95  {
96  if ((e1->received != e2->received) || (e1->date_sent != e2->date_sent) ||
97  (e1->body->length != e2->body->length) || (e1->lines != e2->lines) ||
98  (e1->zhours != e2->zhours) || (e1->zminutes != e2->zminutes) ||
99  (e1->zoccident != e2->zoccident) || (e1->mime != e2->mime) ||
100  !mutt_env_cmp_strict(e1->env, e2->env) || !mutt_body_cmp_strict(e1->body, e2->body))
101  {
102  return false;
103  }
104  return true;
105  }
106  else
107  {
108  return (!e1 && !e2);
109  }
110 }
+ 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 43 of file email.c.

44 {
45  if (!ptr || !*ptr)
46  return;
47 
48  struct Email *e = *ptr;
49 
50  if (e->edata && e->edata_free)
51  e->edata_free(&e->edata);
52 
53  mutt_env_free(&e->env);
54  mutt_body_free(&e->body);
55  FREE(&e->tree);
56  FREE(&e->path);
57 #ifdef MIXMASTER
58  mutt_list_free(&e->chain);
59 #endif
60 #ifdef USE_NOTMUCH
62 #endif
64 
65  FREE(ptr);
66 }
+ 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 72 of file email.c.

73 {
74  static size_t sequence = 0;
75 
76  struct Email *e = mutt_mem_calloc(1, sizeof(struct Email));
77 #ifdef MIXMASTER
78  STAILQ_INIT(&e->chain);
79 #endif
80  STAILQ_INIT(&e->tags);
81  e->visible = true;
82  e->sequence = sequence++;
83  return e;
84 }
+ 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 117 of file email.c.

118 {
119  if (!e || !e->body)
120  return 0;
121  return e->body->length + e->body->offset - e->body->hdr_offset;
122 }
+ 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 151 of file email.c.

152 {
153  if (!el || !e)
154  return -1;
155 
156  struct EmailNode *en = mutt_mem_calloc(1, sizeof(*en));
157  en->email = e;
158  STAILQ_INSERT_TAIL(el, en, entries);
159 
160  return 0;
161 }
+ 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 130 of file email.c.

131 {
132  if (!el)
133  return;
134 
135  struct EmailNode *en = NULL, *tmp = NULL;
136  STAILQ_FOREACH_SAFE(en, el, entries, tmp)
137  {
138  STAILQ_REMOVE(el, en, EmailNode, entries);
139  FREE(&en);
140  }
141  STAILQ_INIT(el);
142 }
+ 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 195 of file email.c.

196 {
197  struct ListNode *n = mutt_list_insert_tail(hdrlist, NULL);
198  n->data = mutt_str_dup(header);
199 
200  return n;
201 }
+ 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
NULLIf no matching header is found

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

Definition at line 172 of file email.c.

173 {
174  const char *key_end = strchr(header, ':');
175  if (!key_end)
176  return NULL;
177 
178  const int keylen = key_end - header + 1;
179 
180  struct ListNode *n = NULL;
181  STAILQ_FOREACH(n, hdrlist, entries)
182  {
183  if (mutt_istrn_equal(n->data, header, keylen))
184  return n;
185  }
186  return n;
187 }
+ 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 237 of file email.c.

238 {
239  STAILQ_REMOVE(hdrlist, target, ListNode, entries);
240  FREE(&target->data);
241  FREE(&target);
242 }
+ 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 225 of file email.c.

226 {
227  struct ListNode *n = header_find(hdrlist, header);
228 
229  return n ? header_update(n, header) : header_add(hdrlist, header);
230 }
+ 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 209 of file email.c.

210 {
211  FREE(&hdr->data);
212  hdr->data = mutt_str_dup(header);
213 
214  return hdr;
215 }
+ Here is the call graph for this function:
+ Here is the caller graph for this function:
Body::hdr_offset
long hdr_offset
Offset in stream where the headers begin.
Definition: body.h:42
Email::date_sent
time_t date_sent
Time when the message was sent (UTC)
Definition: email.h:82
STAILQ_INIT
#define STAILQ_INIT(head)
Definition: queue.h:369
Email::mime
bool mime
Has a MIME-Version header?
Definition: email.h:42
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.
Definition: email.c:172
mutt_mem_calloc
void * mutt_mem_calloc(size_t nmemb, size_t size)
Allocate zeroed memory on the heap.
Definition: memory.c:50
Email::lines
int lines
How many lines in the body of this message?
Definition: email.h:85
ListNode
A List node for strings.
Definition: list.h:34
Body::offset
LOFF_T offset
offset where the actual data begins
Definition: body.h:44
STAILQ_REMOVE
#define STAILQ_REMOVE(head, elm, type, field)
Definition: queue.h:399
header_add
struct ListNode * header_add(struct ListHead *hdrlist, const char *header)
Add a header to a list.
Definition: email.c:195
driver_tags_free
void driver_tags_free(struct TagList *list)
Free tags from a header.
Definition: tags.c:106
NT_HEADER_CHANGE
@ NT_HEADER_CHANGE
An existing header has been changed.
Definition: email.h:160
EmailNode::email
struct Email * email
Email in the list.
Definition: email.h:127
mutt_str_dup
char * mutt_str_dup(const char *str)
Copy a string, safely.
Definition: string.c:370
FREE
#define FREE(x)
Definition: memory.h:40
EmailNode
List of Emails.
Definition: email.h:125
Email::path
char * path
Path of Email (for local Mailboxes)
Definition: email.h:92
Email::edata_free
void(* edata_free)(void **ptr)
Free the private data attached to the Email.
Definition: email.h:117
mutt_body_free
void mutt_body_free(struct Body **ptr)
Free a Body.
Definition: body.c:57
mutt_list_insert_tail
struct ListNode * mutt_list_insert_tail(struct ListHead *h, char *s)
Append a string to the end of a List.
Definition: list.c:64
STAILQ_FOREACH
#define STAILQ_FOREACH(var, head, field)
Definition: queue.h:349
Email::zoccident
bool zoccident
True, if west of UTC, False if east.
Definition: email.h:65
Email::sequence
size_t sequence
Sequence number assigned on creation.
Definition: email.h:99
Email::tree
char * tree
Character string to print thread tree.
Definition: email.h:94
Email::received
time_t received
Time when the message was placed in the mailbox.
Definition: email.h:83
mutt_env_cmp_strict
bool mutt_env_cmp_strict(const struct Envelope *e1, const struct Envelope *e2)
Strictly compare two Envelopes.
Definition: envelope.c:241
NT_EMAIL_ADD
@ NT_EMAIL_ADD
A new Email has just been created.
Definition: email.h:139
mutt_env_free
void mutt_env_free(struct Envelope **ptr)
Free an Envelope.
Definition: envelope.c:96
mutt_body_cmp_strict
bool mutt_body_cmp_strict(const struct Body *b1, const struct Body *b2)
Strictly compare two email Body's.
Definition: body.c:108
Email::visible
bool visible
Is this message part of the view?
Definition: email.h:74
Email::zminutes
unsigned int zminutes
Minutes away from UTC.
Definition: email.h:64
Body::length
LOFF_T length
length (in bytes) of attachment
Definition: body.h:45
Email::env
struct Envelope * env
Envelope information.
Definition: email.h:90
nm_edata_free
void nm_edata_free(void **ptr)
Free data attached to an Email.
Definition: edata.c:41
NT_HEADER_REMOVE
@ NT_HEADER_REMOVE
A header is about to be removed.
Definition: email.h:161
Email::zhours
unsigned int zhours
Hours away from UTC.
Definition: email.h:63
STAILQ_FOREACH_SAFE
#define STAILQ_FOREACH_SAFE(var, head, field, tvar)
Definition: queue.h:359
Email::chain
struct ListHead chain
Mixmaster chain.
Definition: email.h:102
NT_HEADER_ADD
@ NT_HEADER_ADD
A new header has been added.
Definition: email.h:159
header_update
struct ListNode * header_update(struct ListNode *hdr, const char *header)
Update an existing header.
Definition: email.c:209
Email::edata
void * edata
Driver-specific data.
Definition: email.h:111
Email::tags
struct TagList tags
For drivers that support server tagging.
Definition: email.h:109
STAILQ_INSERT_TAIL
#define STAILQ_INSERT_TAIL(head, elm, field)
Definition: queue.h:386
NT_EMAIL_REMOVE
@ NT_EMAIL_REMOVE
An Email is about to be destroyed.
Definition: email.h:140
ListNode::data
char * data
String.
Definition: list.h:36
mutt_istrn_equal
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:621
Email
The envelope/body of an email.
Definition: email.h:37
mutt_list_free
void mutt_list_free(struct ListHead *h)
Free a List AND its strings.
Definition: list.c:122
Email::nm_edata
void * nm_edata
Notmuch private data.
Definition: email.h:106
Email::body
struct Body * body
List of MIME parts.
Definition: email.h:91