mailbox.h File Reference

Representation of a mailbox. More...

#include <stdbool.h>
#include <stdint.h>
#include <sys/types.h>
#include <time.h>
#include "mutt/lib.h"

Include dependency graph for mailbox.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Mailbox
	A mailbox. More...
struct	EventMailbox
	An Event that happened to a Mailbox. More...

Macros
#define	MUTT_ACL_NO_FLAGS   0
	No flags are set.
#define	MUTT_ACL_ADMIN   (1 << 0)
	Administer the account (get/set permissions)
#define	MUTT_ACL_CREATE   (1 << 1)
	Create a mailbox.
#define	MUTT_ACL_DELETE   (1 << 2)
	Delete a message.
#define	MUTT_ACL_DELMX   (1 << 3)
	Delete a mailbox.
#define	MUTT_ACL_EXPUNGE   (1 << 4)
	Expunge messages.
#define	MUTT_ACL_INSERT   (1 << 5)
	Add/copy into the mailbox (used when editing a message)
#define	MUTT_ACL_LOOKUP   (1 << 6)
	Lookup mailbox (visible to 'list')
#define	MUTT_ACL_POST   (1 << 7)
	Post (submit messages to the server)
#define	MUTT_ACL_READ   (1 << 8)
	Read the mailbox.
#define	MUTT_ACL_SEEN   (1 << 9)
	Change the 'seen' status of a message.
#define	MUTT_ACL_WRITE   (1 << 10)
	Write to a message (for flagging or linking threads)
#define	MUTT_ACL_ALL   ((1 << 11) - 1)
	All permissions.

Typedefs
typedef uint16_t	AclFlags
	ACL Rights - These show permission to...

Enumerations
enum	MailboxType {   MUTT_MAILBOX_ANY = -2 , MUTT_MAILBOX_ERROR , MUTT_UNKNOWN , MUTT_MBOX ,   MUTT_MMDF , MUTT_MH , MUTT_MAILDIR , MUTT_NNTP ,   MUTT_IMAP , MUTT_NOTMUCH , MUTT_POP , MUTT_COMPRESSED }
	Supported mailbox formats. More...
enum	ExpandoDataMailbox { ED_MBX_MAILBOX_NAME = 1 , ED_MBX_MESSAGE_COUNT , ED_MBX_PERCENTAGE }
	Expando UIDs for Mailboxes. More...
enum	NotifyMailbox {   NT_MAILBOX_ADD = 1 , NT_MAILBOX_DELETE , NT_MAILBOX_DELETE_ALL , NT_MAILBOX_CHANGE ,   NT_MAILBOX_INVALID , NT_MAILBOX_RESORT , NT_MAILBOX_UPDATE , NT_MAILBOX_UNTAG }
	Types of Mailbox Event. More...

Functions
	ARRAY_HEAD (MailboxArray, struct Mailbox *)
void	mailbox_changed (struct Mailbox *m, enum NotifyMailbox action)
	Notify observers of a change to a Mailbox.
struct Mailbox *	mailbox_find (const char *path)
	Find the mailbox with a given path.
struct Mailbox *	mailbox_find_name (const char *name)
	Find the mailbox with a given name.
void	mailbox_free (struct Mailbox **ptr)
	Free a Mailbox.
int	mailbox_gen (void)
	Get the next generation number.
struct Mailbox *	mailbox_new (void)
	Create a new Mailbox.
bool	mailbox_set_subset (struct Mailbox *m, struct ConfigSubset *sub)
	Set a Mailbox's Config Subset.
void	mailbox_size_add (struct Mailbox *m, const struct Email *e)
	Add an email's size to the total size of a Mailbox.
void	mailbox_size_sub (struct Mailbox *m, const struct Email *e)
	Subtract an email's size from the total size of a Mailbox.
void	mailbox_update (struct Mailbox *m)
	Get the mailbox's current size.
void	mailbox_gc_add (struct Email *e)
	Add an Email to the garbage-collection set.
void	mailbox_gc_run (void)
	Run the garbage-collection.
const char *	mailbox_get_type_name (enum MailboxType type)
	Get the type of a Mailbox.
static const char *	mailbox_path (const struct Mailbox *m)
	Get the Mailbox's path string.

Detailed Description

Representation of a mailbox.

Authors

• Richard Russon
• Pietro Cerutti

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

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 mailbox.h.

Macro Definition Documentation

MUTT_ACL_NO_FLAGS

#define MUTT_ACL_NO_FLAGS   0

No flags are set.

Definition at line 59 of file mailbox.h.

MUTT_ACL_ADMIN

#define MUTT_ACL_ADMIN   (1 << 0)

Administer the account (get/set permissions)

Definition at line 60 of file mailbox.h.

MUTT_ACL_CREATE

#define MUTT_ACL_CREATE   (1 << 1)

Create a mailbox.

Definition at line 61 of file mailbox.h.

MUTT_ACL_DELETE

#define MUTT_ACL_DELETE   (1 << 2)

Delete a message.

Definition at line 62 of file mailbox.h.

MUTT_ACL_DELMX

#define MUTT_ACL_DELMX   (1 << 3)

Delete a mailbox.

Definition at line 63 of file mailbox.h.

MUTT_ACL_EXPUNGE

#define MUTT_ACL_EXPUNGE   (1 << 4)

Expunge messages.

Definition at line 64 of file mailbox.h.

MUTT_ACL_INSERT

#define MUTT_ACL_INSERT   (1 << 5)

Add/copy into the mailbox (used when editing a message)

Definition at line 65 of file mailbox.h.

MUTT_ACL_LOOKUP

#define MUTT_ACL_LOOKUP   (1 << 6)

Lookup mailbox (visible to 'list')

Definition at line 66 of file mailbox.h.

MUTT_ACL_POST

#define MUTT_ACL_POST   (1 << 7)

Post (submit messages to the server)

Definition at line 67 of file mailbox.h.

MUTT_ACL_READ

#define MUTT_ACL_READ   (1 << 8)

Read the mailbox.

Definition at line 68 of file mailbox.h.

MUTT_ACL_SEEN

#define MUTT_ACL_SEEN   (1 << 9)

Change the 'seen' status of a message.

Definition at line 69 of file mailbox.h.

MUTT_ACL_WRITE

#define MUTT_ACL_WRITE   (1 << 10)

Write to a message (for flagging or linking threads)

Definition at line 70 of file mailbox.h.

MUTT_ACL_ALL

#define MUTT_ACL_ALL   ((1 << 11) - 1)

All permissions.

Definition at line 72 of file mailbox.h.

Typedef Documentation

AclFlags

typedef uint16_t AclFlags

ACL Rights - These show permission to...

Flags, e.g. MUTT_ACL_ADMIN

Definition at line 58 of file mailbox.h.

Enumeration Type Documentation

MailboxType

enum MailboxType

Supported mailbox formats.

Enumerator
MUTT_MAILBOX_ANY	Match any Mailbox type.
MUTT_MAILBOX_ERROR	Error occurred examining Mailbox.
MUTT_UNKNOWN	Mailbox wasn't recognised.
MUTT_MBOX	'mbox' Mailbox type
MUTT_MMDF	'mmdf' Mailbox type
MUTT_MH	'MH' Mailbox type
MUTT_MAILDIR	'Maildir' Mailbox type
MUTT_NNTP	'NNTP' (Usenet) Mailbox type
MUTT_IMAP	'IMAP' Mailbox type
MUTT_NOTMUCH	'Notmuch' (virtual) Mailbox type
MUTT_POP	'POP3' Mailbox type
MUTT_COMPRESSED	Compressed file Mailbox type.

Definition at line 39 of file mailbox.h.

{
  MUTT_MAILBOX_ANY = -2,   
  MUTT_MAILBOX_ERROR,      
  MUTT_UNKNOWN,            
  MUTT_MBOX,               
  MUTT_MMDF,               
  MUTT_MH,                 
  MUTT_MAILDIR,            
  MUTT_NNTP,               
  MUTT_IMAP,               
  MUTT_NOTMUCH,            
  MUTT_POP,                
  MUTT_COMPRESSED,         
};

ExpandoDataMailbox

enum ExpandoDataMailbox

Expando UIDs for Mailboxes.

See also

ED_MAILBOX, ExpandoDomain

Enumerator
ED_MBX_MAILBOX_NAME	Mailbox, mailbox_path()
ED_MBX_MESSAGE_COUNT	Mailbox.msg_count.
ED_MBX_PERCENTAGE	EmailFormatInfo.pager_progress.

Definition at line 155 of file mailbox.h.

{
  ED_MBX_MAILBOX_NAME = 1,     
  ED_MBX_MESSAGE_COUNT,        
  ED_MBX_PERCENTAGE,           
};

NotifyMailbox

enum NotifyMailbox

Types of Mailbox Event.

Observers of NT_MAILBOX will be passed an EventMailbox.

Note

Delete notifications are sent before the object is deleted.

Other notifications are sent after the event.

Enumerator
NT_MAILBOX_ADD	Mailbox has been added.
NT_MAILBOX_DELETE	Mailbox is about to be deleted.
NT_MAILBOX_DELETE_ALL	All Mailboxes are about to be deleted.
NT_MAILBOX_CHANGE	Mailbox has been changed.
NT_MAILBOX_INVALID	Email list was changed.
NT_MAILBOX_RESORT	Email list needs resorting.
NT_MAILBOX_UPDATE	Update internal tables.
NT_MAILBOX_UNTAG	Clear the 'last-tagged' pointer.

Definition at line 170 of file mailbox.h.

{
  NT_MAILBOX_ADD = 1,    
  NT_MAILBOX_DELETE,     
  NT_MAILBOX_DELETE_ALL, 
  NT_MAILBOX_CHANGE,     
 
  /* These don't really belong here as they are tied to GUI operations.
   * Eventually, they'll be eliminated. */
  NT_MAILBOX_INVALID,    
  NT_MAILBOX_RESORT,     
  NT_MAILBOX_UPDATE,     
  NT_MAILBOX_UNTAG,      
};

Function Documentation

ARRAY_HEAD()

ARRAY_HEAD	(	MailboxArray	,
		struct Mailbox *	)

mailbox_changed()

void mailbox_changed	(	struct Mailbox *	m,
		enum NotifyMailbox	action )

Notify observers of a change to a Mailbox.

Parameters

m	Mailbox
action	Change to Mailbox

Definition at line 232 of file mailbox.c.

{
  if (!m)
    return;
 
  mutt_debug(LL_NOTIFY, "NT_MAILBOX_CHANGE: %s %p\n",
             mailbox_get_type_name(m->type), (void *) m);
  struct EventMailbox ev_m = { m };
  notify_send(m->notify, NT_MAILBOX, action, &ev_m);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_find()

struct Mailbox * mailbox_find

(

const char *

path

)

Find the mailbox with a given path.

Parameters

path	Path to match

Return values

ptr	Matching Mailbox

Definition at line 151 of file mailbox.c.

{
  if (!path)
    return NULL;
 
  struct stat st = { 0 };
  struct stat st_tmp = { 0 };
 
  if (stat(path, &st) != 0)
    return NULL;
 
  struct MailboxArray ma = neomutt_mailboxes_get(NeoMutt, MUTT_MAILBOX_ANY);
  struct Mailbox **mp = NULL;
  struct Mailbox *m = NULL;
  ARRAY_FOREACH(mp, &ma)
  {
    if ((stat(mailbox_path(*mp), &st_tmp) == 0) &&
        (st.st_dev == st_tmp.st_dev) && (st.st_ino == st_tmp.st_ino))
    {
      m = *mp;
      break;
    }
  }
 
  ARRAY_FREE(&ma); // Clean up the ARRAY, but not the Mailboxes
  return m;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_find_name()

struct Mailbox * mailbox_find_name

(

const char *

name

)

Find the mailbox with a given name.

Parameters

name	Name to match

Return values

ptr	Matching Mailbox
NULL	No matching mailbox found

Note

This searches across all Accounts

Definition at line 187 of file mailbox.c.

{
  if (!name)
    return NULL;
 
  struct MailboxArray ma = neomutt_mailboxes_get(NeoMutt, MUTT_MAILBOX_ANY);
  struct Mailbox **mp = NULL;
  struct Mailbox *m = NULL;
  ARRAY_FOREACH(mp, &ma)
  {
    if (mutt_str_equal((*mp)->name, name))
    {
      m = *mp;
      break;
    }
  }
 
  ARRAY_FREE(&ma); // Clean up the ARRAY, but not the Mailboxes
  return m;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_free()

void mailbox_free

(

struct Mailbox **

ptr

)

Free a Mailbox.

Parameters

[out]

ptr

Mailbox to free

Definition at line 90 of file mailbox.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct Mailbox *m = *ptr;
 
  const bool do_free = (m->opened == 0) && !m->visible;
 
  mutt_debug(LL_DEBUG3, "%sfreeing %s mailbox %s with refcount %d\n",
             do_free ? "" : "not ", m->visible ? "visible" : "invisible",
             buf_string(&m->pathbuf), m->opened);
 
  if (!do_free)
  {
    return;
  }
 
  mutt_debug(LL_NOTIFY, "NT_MAILBOX_DELETE: %s %p\n",
             mailbox_get_type_name(m->type), (void *) m);
  struct EventMailbox ev_m = { m };
  notify_send(m->notify, NT_MAILBOX, NT_MAILBOX_DELETE, &ev_m);
 
  mutt_debug(LL_NOTIFY, "NT_EMAIL_DELETE_ALL\n");
  struct EventEmail ev_e = { 0, NULL };
  notify_send(m->notify, NT_EMAIL, NT_EMAIL_DELETE_ALL, &ev_e);
 
  for (size_t i = 0; i < m->email_max; i++)
    email_free(&m->emails[i]);
 
  m->email_max = 0;
  m->msg_count = 0;
  m->msg_deleted = 0;
  m->msg_flagged = 0;
  m->msg_new = 0;
  m->msg_tagged = 0;
  m->msg_unread = 0;
 
  if (m->mdata_free && m->mdata)
    m->mdata_free(&m->mdata);
 
  buf_dealloc(&m->pathbuf);
  cs_subset_free(&m->sub);
  FREE(&m->name);
  FREE(&m->realpath);
  FREE(&m->emails);
  FREE(&m->v2r);
  notify_free(&m->notify);
  mailbox_gc_run();
 
  /* The NT_MAILBOX_DELETE notification might already have caused *ptr to be NULL,
   * so call free() on the m pointer */
  *ptr = NULL;
  FREE(&m);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_gen()

int mailbox_gen

(

void

)

Get the next generation number.

Return values

num	Unique number

Definition at line 59 of file mailbox.c.

{
  static int gen = 0;
  return gen++;
}

Here is the caller graph for this function:

mailbox_new()

struct Mailbox * mailbox_new

(

void

)

Create a new Mailbox.

Return values

ptr	New Mailbox

Definition at line 69 of file mailbox.c.

{
  struct Mailbox *m = MUTT_MEM_CALLOC(1, struct Mailbox);
 
  buf_init(&m->pathbuf);
  m->notify = notify_new();
 
  m->email_max = 25;
  m->emails = MUTT_MEM_CALLOC(m->email_max, struct Email *);
  m->v2r = MUTT_MEM_CALLOC(m->email_max, int);
  m->gen = mailbox_gen();
  m->notify_user = true;
  m->poll_new_mail = true;
 
  return m;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_set_subset()

bool mailbox_set_subset	(	struct Mailbox *	m,
		struct ConfigSubset *	sub )

Set a Mailbox's Config Subset.

Parameters

m	Mailbox
sub	Parent Config Subset

Return values

true

Success

Definition at line 269 of file mailbox.c.

{
  if (!m || m->sub || !sub)
    return false;
 
  m->sub = cs_subset_new(m->name, sub, m->notify);
  m->sub->scope = SET_SCOPE_MAILBOX;
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_size_add()

void mailbox_size_add	(	struct Mailbox *	m,
		const struct Email *	e )

Add an email's size to the total size of a Mailbox.

Parameters

m	Mailbox
e	Email

Definition at line 248 of file mailbox.c.

{
  m->size += email_get_size(e);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_size_sub()

void mailbox_size_sub	(	struct Mailbox *	m,
		const struct Email *	e )

Subtract an email's size from the total size of a Mailbox.

Parameters

m	Mailbox
e	Email

Definition at line 258 of file mailbox.c.

{
  m->size -= email_get_size(e);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_update()

void mailbox_update

(

struct Mailbox *

m

)

Get the mailbox's current size.

Parameters

m	Mailbox to check

Note

Only applies to local Mailboxes

Definition at line 214 of file mailbox.c.

{
  struct stat st = { 0 };
 
  if (!m)
    return;
 
  if (stat(mailbox_path(m), &st) == 0)
    m->size = (off_t) st.st_size;
  else
    m->size = 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_gc_add()

void mailbox_gc_add

(

struct Email *

e

)

Add an Email to the garbage-collection set.

Parameters

e

Email

Precondition

e is not NULL

Definition at line 297 of file mailbox.c.

{
  ASSERT(e);
  if (GC.idx == countof(GC.arr))
  {
    mailbox_gc_run();
  }
  GC.arr[GC.idx] = e;
  GC.idx++;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_gc_run()

void mailbox_gc_run

(

void

)

Run the garbage-collection.

Definition at line 311 of file mailbox.c.

{
  for (size_t i = 0; i < GC.idx; i++)
  {
    email_free(&GC.arr[i]);
  }
  GC.idx = 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_get_type_name()

const char * mailbox_get_type_name

(

enum MailboxType

type

)

Get the type of a Mailbox.

Parameters

type	Mailbox type, e.g. MUTT_IMAP

Return values

ptr	String describing Mailbox type

Definition at line 325 of file mailbox.c.

{
  const char *name = mutt_map_get_name(type, MailboxTypes);
  if (name)
    return name;
  return "UNKNOWN";
}

Here is the call graph for this function:

Here is the caller graph for this function:

mailbox_path()

static const char * mailbox_path ( const struct Mailbox * m )

inlinestatic

Get the Mailbox's path string.

Parameters

m

Mailbox

Return values

ptr	Path string

Definition at line 213 of file mailbox.h.

{
  return buf_string(&m->pathbuf); // LCOV_EXCL_LINE
}

Here is the call graph for this function: