address.h File Reference

Representation of an email address. More...

#include <stddef.h>
#include <stdbool.h>
#include <stdio.h>
#include "mutt/lib.h"

Include dependency graph for address.h:

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

Go to the source code of this file.

Data Structures
struct	Address
	An email address. More...

Macros
#define	address_error(num)   AddressErrors[num]

Typedefs
typedef bool(*	addr_predicate_t) (const struct Address *a)

Enumerations
enum	AddressError {   ADDR_ERR_MEMORY = 1 , ADDR_ERR_MISMATCH_PAREN , ADDR_ERR_MISMATCH_QUOTE , ADDR_ERR_BAD_ROUTE ,   ADDR_ERR_BAD_ROUTE_ADDR , ADDR_ERR_BAD_ADDR_SPEC }
	Possible values for AddressError. More...

Functions
	TAILQ_HEAD (AddressList, Address)
void	mutt_addr_cat (char *buf, size_t buflen, const char *value, const char *specials)
	Copy a string and wrap it in quotes if it contains special characters. More...
bool	mutt_addr_valid_msgid (const char *msgid)
	Is this a valid Message ID? More...
bool	mutt_addr_cmp (const struct Address *a, const struct Address *b)
	Compare two e-mail addresses. More...
struct Address *	mutt_addr_copy (const struct Address *addr)
	Copy the real address. More...
struct Address *	mutt_addr_create (const char *personal, const char *mailbox)
	Create and populate a new Address. More...
const char *	mutt_addr_for_display (const struct Address *a)
	Convert an Address for display purposes. More...
void	mutt_addr_free (struct Address **ptr)
	Free a single Address. More...
struct Address *	mutt_addr_new (void)
	Create a new Address. More...
bool	mutt_addr_to_intl (struct Address *a)
	Convert an Address to Punycode. More...
bool	mutt_addr_to_local (struct Address *a)
	Convert an Address from Punycode. More...
bool	mutt_addr_uses_unicode (const char *str)
	Does this address use Unicode character. More...
size_t	mutt_addr_write (struct Buffer *buf, struct Address *addr, bool display)
	Write a single Address to a buffer. More...
void	mutt_addrlist_append (struct AddressList *al, struct Address *a)
	Append an Address to an AddressList. More...
void	mutt_addrlist_clear (struct AddressList *al)
	Unlink and free all Address in an AddressList. More...
void	mutt_addrlist_copy (struct AddressList *dst, const struct AddressList *src, bool prune)
	Copy a list of addresses into another list. More...
int	mutt_addrlist_count_recips (const struct AddressList *al)
	Count the number of Addresses with valid recipients. More...
void	mutt_addrlist_dedupe (struct AddressList *al)
	Remove duplicate addresses. More...
bool	mutt_addrlist_equal (const struct AddressList *ala, const struct AddressList *alb)
	Compare two Address lists for equality. More...
int	mutt_addrlist_parse (struct AddressList *al, const char *s)
	Parse a list of email addresses. More...
int	mutt_addrlist_parse2 (struct AddressList *al, const char *s)
	Parse a list of email addresses. More...
void	mutt_addrlist_prepend (struct AddressList *al, struct Address *a)
	Prepend an Address to an AddressList. More...
void	mutt_addrlist_qualify (struct AddressList *al, const char *host)
	Expand local names in an Address list using a hostname. More...
int	mutt_addrlist_remove (struct AddressList *al, const char *mailbox)
	Remove an Address from a list. More...
void	mutt_addrlist_remove_xrefs (const struct AddressList *a, struct AddressList *b)
	Remove cross-references. More...
bool	mutt_addrlist_search (const struct AddressList *haystack, const struct Address *needle)
	Search for an e-mail address in a list. More...
int	mutt_addrlist_to_intl (struct AddressList *al, char **err)
	Convert an Address list to Punycode. More...
int	mutt_addrlist_to_local (struct AddressList *al)
	Convert an Address list from Punycode. More...
bool	mutt_addrlist_uses_unicode (const struct AddressList *al)
	Do any of a list of addresses use Unicode characters. More...
size_t	mutt_addrlist_write (const struct AddressList *al, struct Buffer *buf, bool display)
	Write an Address to a buffer. More...
size_t	mutt_addrlist_write_wrap (const struct AddressList *al, struct Buffer *buf, const char *header)
	Write an AddressList to a buffer, perform line wrapping. More...
void	mutt_addrlist_write_file (const struct AddressList *al, FILE *fp, const char *header)
	Wrapper for mutt_write_address() More...
size_t	mutt_addrlist_write_list (const struct AddressList *al, struct ListHead *list)
	Write Addresses to a List. More...

Variables
int	AddressError
	An out-of-band error code. More...
const char *const	AddressErrors []
	Messages for the error codes in AddressError. More...
const char	AddressSpecials []
	Characters with special meaning for email addresses. More...

Detailed Description

Representation of an email address.

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

Macro Definition Documentation

address_error

#define address_error

(

num

)

AddressErrors[num]

Definition at line 63 of file address.h.

Typedef Documentation

addr_predicate_t

typedef bool(* addr_predicate_t) (const struct Address *a)

Definition at line 73 of file address.h.

Enumeration Type Documentation

AddressError

enum AddressError

Possible values for AddressError.

Enumerator
ADDR_ERR_MEMORY	Out of memory.
ADDR_ERR_MISMATCH_PAREN	Mismatched parentheses.
ADDR_ERR_MISMATCH_QUOTE	Mismatches quotes.
ADDR_ERR_BAD_ROUTE	Bad route.
ADDR_ERR_BAD_ROUTE_ADDR	Bad route address.
ADDR_ERR_BAD_ADDR_SPEC	Bad address specifier.

Definition at line 49 of file address.h.

{
  ADDR_ERR_MEMORY = 1,     
  ADDR_ERR_MISMATCH_PAREN, 
  ADDR_ERR_MISMATCH_QUOTE, 
  ADDR_ERR_BAD_ROUTE,      
  ADDR_ERR_BAD_ROUTE_ADDR, 
  ADDR_ERR_BAD_ADDR_SPEC,  
};

Function Documentation

TAILQ_HEAD()

TAILQ_HEAD	(	AddressList	,
		Address
	)

mutt_addr_cat()

void mutt_addr_cat	(	char *	buf,
		size_t	buflen,
		const char *	value,
		const char *	specials
	)

Copy a string and wrap it in quotes if it contains special characters.

Parameters

buf	Buffer for the result
buflen	Length of the result buffer
value	String to copy
specials	Characters to lookup

This function copies the string in the "value" parameter in the buffer pointed to by "buf" parameter. If the input string contains any of the characters specified in the "specials" parameters, the output string is wrapped in double quoted. Additionally, any backslashes or quotes inside the input string are backslash-escaped.

Definition at line 687 of file address.c.

{
  if (!buf || !value || !specials)
    return;
 
  if (strpbrk(value, specials))
  {
    char tmp[256] = { 0 };
    char *pc = tmp;
    size_t tmplen = sizeof(tmp) - 3;
 
    *pc++ = '"';
    for (; *value && (tmplen > 1); value++)
    {
      if ((*value == '\\') || (*value == '"'))
      {
        *pc++ = '\\';
        tmplen--;
      }
      *pc++ = *value;
      tmplen--;
    }
    *pc++ = '"';
    *pc = '\0';
    mutt_str_copy(buf, tmp, buflen);
  }
  else
  {
    mutt_str_copy(buf, value, buflen);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_valid_msgid()

bool mutt_addr_valid_msgid

(

const char *

msgid

)

Is this a valid Message ID?

Parameters

msgid

Message ID

Return values

true	It is a valid message ID

Incomplete. Only used to thwart the APOP MD5 attack

Definition at line 772 of file address.c.

{
  /* msg-id         = "<" addr-spec ">"
   * addr-spec      = local-part "@" domain
   * local-part     = word *("." word)
   * word           = atom / quoted-string
   * atom           = 1*<any CHAR except specials, SPACE and CTLs>
   * CHAR           = ( 0.-127. )
   * specials       = "(" / ")" / "<" / ">" / "@"
   *                / "," / ";" / ":" / "\" / <">
   *                / "." / "[" / "]"
   * SPACE          = ( 32. )
   * CTLS           = ( 0.-31., 127.)
   * quoted-string  = <"> *(qtext/quoted-pair) <">
   * qtext          = <any CHAR except <">, "\" and CR>
   * CR             = ( 13. )
   * quoted-pair    = "\" CHAR
   * domain         = sub-domain *("." sub-domain)
   * sub-domain     = domain-ref / domain-literal
   * domain-ref     = atom
   * domain-literal = "[" *(dtext / quoted-pair) "]"
   */
 
  if (!msgid || (*msgid == '\0'))
    return false;
 
  size_t l = mutt_str_len(msgid);
  if (l < 5) /* <atom@atom> */
    return false;
  if ((msgid[0] != '<') || (msgid[l - 1] != '>'))
    return false;
  if (!(strrchr(msgid, '@')))
    return false;
 
  /* TODO: complete parser */
  for (size_t i = 0; i < l; i++)
    if ((unsigned char) msgid[i] > 127)
      return false;
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_cmp()

bool mutt_addr_cmp	(	const struct Address *	a,
		const struct Address *	b
	)

Compare two e-mail addresses.

Parameters

a	Address 1
b	Address 2

Return values

true	They are equivalent

Definition at line 872 of file address.c.

{
  if (!a || !b)
    return false;
  if (!a->mailbox || !b->mailbox)
    return false;
  if (!mutt_istr_equal(a->mailbox, b->mailbox))
    return false;
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_copy()

struct Address * mutt_addr_copy

(

const struct Address *

addr

)

Copy the real address.

Parameters

addr	Address to copy

Return values

ptr	New Address

Definition at line 724 of file address.c.

{
  if (!addr)
    return NULL;
 
  struct Address *p = mutt_addr_new();
 
  p->personal = mutt_str_dup(addr->personal);
  p->mailbox = mutt_str_dup(addr->mailbox);
  p->group = addr->group;
  p->is_intl = addr->is_intl;
  p->intl_checked = addr->intl_checked;
  return p;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_create()

struct Address * mutt_addr_create	(	const char *	personal,
		const char *	mailbox
	)

Create and populate a new Address.

Parameters

[in]	personal	The personal name for the Address (can be NULL)
[in]	mailbox	The mailbox for the Address (can be NULL)

Return values

ptr	Newly allocated Address

Note

The personal and mailbox values, if not NULL, are going to be copied into the newly allocated Address.

Definition at line 402 of file address.c.

{
  struct Address *a = mutt_addr_new();
  a->personal = mutt_str_dup(personal);
  a->mailbox = mutt_str_dup(mailbox);
  return a;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_for_display()

const char * mutt_addr_for_display

(

const struct Address *

a

)

Convert an Address for display purposes.

Parameters

a	Address to convert

Return values

ptr	Address to display

Warning

This function may return a static pointer. It must not be freed by the caller. Later calls may overwrite the returned pointer.

Definition at line 994 of file address.c.

{
  if (!a)
    return NULL;
 
  char *user = NULL, *domain = NULL;
  static char *buf = NULL;
 
  if (!a->mailbox || addr_is_local(a))
    return a->mailbox;
 
  if (addr_mbox_to_udomain(a->mailbox, &user, &domain) == -1)
    return a->mailbox;
 
  char *local_mailbox = mutt_idna_intl_to_local(user, domain, MI_MAY_BE_IRREVERSIBLE);
 
  FREE(&user);
  FREE(&domain);
 
  if (!local_mailbox)
    return a->mailbox;
 
  mutt_str_replace(&buf, local_mailbox);
  FREE(&local_mailbox);
 
  return buf;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_free()

void mutt_addr_free

(

struct Address **

ptr

)

Free a single Address.

Parameters

[out]

ptr

Address to free

Definition at line 444 of file address.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct Address *a = *ptr;
 
  FREE(&a->personal);
  FREE(&a->mailbox);
  FREE(ptr);
}

Here is the caller graph for this function:

mutt_addr_new()

struct Address * mutt_addr_new

(

void

)

Create a new Address.

Return values

ptr	Newly allocated Address

Free the result with mutt_addr_free()

Definition at line 389 of file address.c.

{
  return mutt_mem_calloc(1, sizeof(struct Address));
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_to_intl()

bool mutt_addr_to_intl

(

struct Address *

a

)

Convert an Address to Punycode.

Parameters

a	Address to convert

Return values

true	Success
false	Otherwise

Definition at line 1249 of file address.c.

{
  if (!a || !a->mailbox || addr_is_intl(a))
    return true;
 
  char *user = NULL;
  char *domain = NULL;
  if (addr_mbox_to_udomain(a->mailbox, &user, &domain) == -1)
    return true;
 
  char *intl_mailbox = mutt_idna_local_to_intl(user, domain);
 
  FREE(&user);
  FREE(&domain);
 
  if (!intl_mailbox)
    return false;
 
  addr_set_intl(a, intl_mailbox);
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_to_local()

bool mutt_addr_to_local

(

struct Address *

a

)

Convert an Address from Punycode.

Parameters

a	Address to convert

Return values

true	Success
false	Otherwise

Definition at line 1324 of file address.c.

{
  if (!a->mailbox)
  {
    return false;
  }
 
  if (addr_is_local(a))
  {
    return true;
  }
 
  char *user = NULL;
  char *domain = NULL;
  if (addr_mbox_to_udomain(a->mailbox, &user, &domain) == -1)
  {
    return false;
  }
 
  char *local_mailbox = mutt_idna_intl_to_local(user, domain, MI_NO_FLAGS);
  FREE(&user);
  FREE(&domain);
 
  if (!local_mailbox)
  {
    return false;
  }
 
  addr_set_local(a, local_mailbox);
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addr_uses_unicode()

bool mutt_addr_uses_unicode

(

const char *

str

)

Does this address use Unicode character.

Parameters

str	Address string to check

Return values

true	The string uses 8-bit characters

Definition at line 1485 of file address.c.

{
  if (!str)
    return false;
 
  while (*str)
  {
    if ((unsigned char) *str & (1 << 7))
      return true;
    str++;
  }
 
  return false;
}

Here is the caller graph for this function:

mutt_addr_write()

size_t mutt_addr_write	(	struct Buffer *	buf,
		struct Address *	addr,
		bool	display
	)

Write a single Address to a buffer.

Parameters

buf	Buffer for the Address
addr	Address to display
display	This address will be displayed to the user

Return values

num	Length of the string written to buf

If 'display' is set, then it doesn't matter if the transformation isn't reversible.

Definition at line 1032 of file address.c.

{
  if (!buf || !addr || (!addr->personal && !addr->mailbox))
  {
    return 0;
  }
 
  const size_t initial_len = mutt_buffer_len(buf);
 
  if (addr->personal)
  {
    if (strpbrk(addr->personal, AddressSpecials))
    {
      mutt_buffer_addch(buf, '"');
      for (const char *pc = addr->personal; *pc; pc++)
      {
        if ((*pc == '"') || (*pc == '\\'))
        {
          mutt_buffer_addch(buf, '\\');
        }
        mutt_buffer_addch(buf, *pc);
      }
      mutt_buffer_addch(buf, '"');
    }
    else
    {
      mutt_buffer_addstr(buf, addr->personal);
    }
 
    mutt_buffer_addch(buf, ' ');
  }
 
  if (addr->personal || (addr->mailbox && (*addr->mailbox == '@')))
  {
    mutt_buffer_addch(buf, '<');
  }
 
  if (addr->mailbox)
  {
    if (!mutt_str_equal(addr->mailbox, "@"))
    {
      const char *a = display ? mutt_addr_for_display(addr) : addr->mailbox;
      mutt_buffer_addstr(buf, a);
    }
 
    if (addr->personal || (addr->mailbox && (*addr->mailbox == '@')))
    {
      mutt_buffer_addch(buf, '>');
    }
 
    if (addr->group)
    {
      mutt_buffer_addstr(buf, ": ");
    }
  }
  else
  {
    mutt_buffer_addch(buf, ';');
  }
 
  return mutt_buffer_len(buf) - initial_len;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_append()

void mutt_addrlist_append	(	struct AddressList *	al,
		struct Address *	a
	)

Append an Address to an AddressList.

Parameters

al	AddressList
a	Address

Definition at line 1463 of file address.c.

{
  if (al && a)
    TAILQ_INSERT_TAIL(al, a, entries);
}

Here is the caller graph for this function:

mutt_addrlist_clear()

void mutt_addrlist_clear

(

struct AddressList *

al

)

Unlink and free all Address in an AddressList.

Parameters

al	AddressList

Note

After this call, the AddressList is reinitialized and ready for reuse.

Definition at line 1443 of file address.c.

{
  if (!al)
    return;
 
  struct Address *a = TAILQ_FIRST(al), *next = NULL;
  while (a)
  {
    next = TAILQ_NEXT(a, entries);
    mutt_addr_free(&a);
    a = next;
  }
  TAILQ_INIT(al);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_copy()

void mutt_addrlist_copy	(	struct AddressList *	dst,
		const struct AddressList *	src,
		bool	prune
	)

Copy a list of addresses into another list.

Parameters

dst	Destination Address list
src	Source Address list
prune	Skip groups if there are more addresses

Definition at line 745 of file address.c.

{
  if (!dst || !src)
    return;
 
  struct Address *a = NULL;
  TAILQ_FOREACH(a, src, entries)
  {
    struct Address *next = TAILQ_NEXT(a, entries);
    if (prune && a->group && (!next || !next->mailbox))
    {
      /* ignore this element of the list */
    }
    else
    {
      mutt_addrlist_append(dst, mutt_addr_copy(a));
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_count_recips()

int mutt_addrlist_count_recips

(

const struct AddressList *

al

)

Count the number of Addresses with valid recipients.

Parameters

al	Address list

Return values

num	Number of valid Addresses

An Address has a recipient if the mailbox is set and is not a group

Definition at line 852 of file address.c.

{
  if (!al)
    return 0;
 
  int c = 0;
  struct Address *a = NULL;
  TAILQ_FOREACH(a, al, entries)
  {
    c += (a->mailbox && !a->group);
  }
  return c;
}

Here is the caller graph for this function:

mutt_addrlist_dedupe()

void mutt_addrlist_dedupe

(

struct AddressList *

al

)

Remove duplicate addresses.

Parameters

al	Address list to de-dupe

Given a list of addresses, return a list of unique addresses

Definition at line 1380 of file address.c.

{
  if (!al)
    return;
 
  struct Address *a = NULL;
  TAILQ_FOREACH(a, al, entries)
  {
    if (a->mailbox)
    {
      struct Address *a2 = TAILQ_NEXT(a, entries);
      struct Address *tmp = NULL;
 
      if (a2)
      {
        TAILQ_FOREACH_FROM_SAFE(a2, al, entries, tmp)
        {
          if (a2->mailbox && mutt_istr_equal(a->mailbox, a2->mailbox))
          {
            mutt_debug(LL_DEBUG2, "Removing %s\n", a2->mailbox);
            TAILQ_REMOVE(al, a2, entries);
            mutt_addr_free(&a2);
          }
        }
      }
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_equal()

bool mutt_addrlist_equal	(	const struct AddressList *	ala,
		const struct AddressList *	alb
	)

Compare two Address lists for equality.

Parameters

ala	First Address
alb	Second Address

Return values

true	Address lists are strictly identical

Definition at line 820 of file address.c.

{
  if (!ala || !alb)
  {
    return !(ala || alb);
  }
 
  struct Address *ana = TAILQ_FIRST(ala);
  struct Address *anb = TAILQ_FIRST(alb);
 
  while (ana && anb)
  {
    if (!mutt_str_equal(ana->mailbox, anb->mailbox) ||
        !mutt_str_equal(ana->personal, anb->personal))
    {
      break;
    }
 
    ana = TAILQ_NEXT(ana, entries);
    anb = TAILQ_NEXT(anb, entries);
  }
 
  return !(ana || anb);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_parse()

int mutt_addrlist_parse	(	struct AddressList *	al,
		const char *	s
	)

Parse a list of email addresses.

Parameters

al	AddressList to append addresses
s	String to parse

Return values

num	Number of parsed addresses

Definition at line 462 of file address.c.

{
  if (!s)
    return 0;
 
  int parsed = 0;
  char comment[1024], phrase[1024];
  size_t phraselen = 0, commentlen = 0;
  AddressError = 0;
 
  bool ws_pending = mutt_str_is_email_wsp(*s);
 
  s = mutt_str_skip_email_wsp(s);
  while (*s)
  {
    switch (*s)
    {
      case ';':
      case ',':
        if (phraselen != 0)
        {
          terminate_buffer(phrase, phraselen);
          if (add_addrspec(al, phrase, comment, &commentlen, sizeof(comment) - 1))
          {
            parsed++;
          }
        }
        else if (commentlen != 0)
        {
          struct Address *last = TAILQ_LAST(al, AddressList);
          if (last && !last->personal && last->mailbox)
          {
            terminate_buffer(comment, commentlen);
            last->personal = mutt_str_dup(comment);
          }
        }
 
        if (*s == ';')
        {
          /* add group terminator */
          mutt_addrlist_append(al, mutt_addr_new());
        }
 
        phraselen = 0;
        commentlen = 0;
        s++;
        break;
 
      case '(':
        if ((commentlen != 0) && (commentlen < (sizeof(comment) - 1)))
          comment[commentlen++] = ' ';
        s = next_token(s, comment, &commentlen, sizeof(comment) - 1);
        if (!s)
        {
          mutt_addrlist_clear(al);
          return 0;
        }
        break;
 
      case '"':
        if ((phraselen != 0) && (phraselen < (sizeof(phrase) - 1)))
          phrase[phraselen++] = ' ';
        s = parse_quote(s + 1, phrase, &phraselen, sizeof(phrase) - 1);
        if (!s)
        {
          mutt_addrlist_clear(al);
          return 0;
        }
        break;
 
      case ':':
      {
        struct Address *a = mutt_addr_new();
        terminate_buffer(phrase, phraselen);
        a->mailbox = mutt_str_dup(phrase);
        a->group = true;
        mutt_addrlist_append(al, a);
        phraselen = 0;
        commentlen = 0;
        s++;
        break;
      }
 
      case '<':
      {
        struct Address *a = mutt_addr_new();
        terminate_buffer(phrase, phraselen);
        a->personal = mutt_str_dup(phrase);
        s = parse_route_addr(s + 1, comment, &commentlen, sizeof(comment) - 1, a);
        if (!s)
        {
          mutt_addrlist_clear(al);
          mutt_addr_free(&a);
          return 0;
        }
        mutt_addrlist_append(al, a);
        phraselen = 0;
        commentlen = 0;
        parsed++;
        break;
      }
 
      default:
        if ((phraselen != 0) && (phraselen < (sizeof(phrase) - 1)) && ws_pending)
          phrase[phraselen++] = ' ';
        if (*s == '\\')
        {
          s++;
          if (*s && (phraselen < (sizeof(phrase) - 1)))
          {
            phrase[phraselen++] = *s;
            s++;
          }
        }
        s = next_token(s, phrase, &phraselen, sizeof(phrase) - 1);
        if (!s)
        {
          mutt_addrlist_clear(al);
          return 0;
        }
        break;
    } // switch (*s)
 
    ws_pending = mutt_str_is_email_wsp(*s);
    s = mutt_str_skip_email_wsp(s);
  } // while (*s)
 
  if (phraselen != 0)
  {
    terminate_buffer(phrase, phraselen);
    terminate_buffer(comment, commentlen);
    if (add_addrspec(al, phrase, comment, &commentlen, sizeof(comment) - 1))
    {
      parsed++;
    }
  }
  else if (commentlen != 0)
  {
    struct Address *last = TAILQ_LAST(al, AddressList);
    if (last && !last->personal && last->mailbox)
    {
      terminate_buffer(comment, commentlen);
      last->personal = mutt_str_dup(comment);
    }
  }
 
  return parsed;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_parse2()

int mutt_addrlist_parse2	(	struct AddressList *	al,
		const char *	s
	)

Parse a list of email addresses.

Parameters

al	Add to this List of Addresses
s	String to parse

Return values

num	Number of parsed addresses

Simple email addresses (without any personal name or grouping) can be separated by whitespace or commas.

Definition at line 620 of file address.c.

{
  if (!s || (*s == '\0'))
    return 0;
 
  int parsed = 0;
 
  /* check for a simple whitespace separated list of addresses */
  if (!strpbrk(s, "\"<>():;,\\"))
  {
    char *copy = mutt_str_dup(s);
    char *r = copy;
    while ((r = strtok(r, " \t")))
    {
      parsed += mutt_addrlist_parse(al, r);
      r = NULL;
    }
    FREE(&copy);
  }
  else
  {
    parsed = mutt_addrlist_parse(al, s);
  }
 
  return parsed;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_prepend()

void mutt_addrlist_prepend	(	struct AddressList *	al,
		struct Address *	a
	)

Prepend an Address to an AddressList.

Parameters

al	AddressList
a	Address

Definition at line 1474 of file address.c.

{
  if (al && a)
    TAILQ_INSERT_HEAD(al, a, entries);
}

Here is the caller graph for this function:

mutt_addrlist_qualify()

void mutt_addrlist_qualify	(	struct AddressList *	al,
		const char *	host
	)

Expand local names in an Address list using a hostname.

Parameters

al	Address list
host	Hostname

Any addresses containing a bare name will be expanded using the hostname. e.g. "john", "example.com" -> 'john@.nosp@m.exam.nosp@m.ple.c.nosp@m.om'. This function has no effect if host is NULL or the empty string.

Definition at line 656 of file address.c.

{
  if (!al || !host || (*host == '\0'))
    return;
 
  struct Address *a = NULL;
  TAILQ_FOREACH(a, al, entries)
  {
    if (!a->group && a->mailbox && !strchr(a->mailbox, '@'))
    {
      char *p = mutt_mem_malloc(mutt_str_len(a->mailbox) + mutt_str_len(host) + 2);
      sprintf(p, "%s@%s", a->mailbox, host);
      FREE(&a->mailbox);
      a->mailbox = p;
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_remove()

int mutt_addrlist_remove	(	struct AddressList *	al,
		const char *	mailbox
	)

Remove an Address from a list.

Parameters

[in,out]	al	AddressList
[in]	mailbox	Email address to match

Return values

0	Success
-1	Error, or email not found

Definition at line 417 of file address.c.

{
  if (!al)
    return -1;
 
  if (!mailbox)
    return 0;
 
  int rc = -1;
  struct Address *a = NULL, *tmp = NULL;
  TAILQ_FOREACH_SAFE(a, al, entries, tmp)
  {
    if (mutt_istr_equal(mailbox, a->mailbox))
    {
      TAILQ_REMOVE(al, a, entries);
      mutt_addr_free(&a);
      rc = 0;
    }
  }
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_remove_xrefs()

void mutt_addrlist_remove_xrefs	(	const struct AddressList *	a,
		struct AddressList *	b
	)

Remove cross-references.

Parameters

a	Reference AddressList
b	AddressLis to trim

Remove addresses from "b" which are contained in "a"

Definition at line 1416 of file address.c.

{
  if (!a || !b)
    return;
 
  struct Address *aa = NULL, *ab = NULL, *tmp = NULL;
 
  TAILQ_FOREACH_SAFE(ab, b, entries, tmp)
  {
    TAILQ_FOREACH(aa, a, entries)
    {
      if (mutt_addr_cmp(aa, ab))
      {
        TAILQ_REMOVE(b, ab, entries);
        mutt_addr_free(&ab);
        break;
      }
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_search()

bool mutt_addrlist_search	(	const struct AddressList *	haystack,
		const struct Address *	needle
	)

Search for an e-mail address in a list.

Parameters

haystack	Address List
needle	Address containing the search email

Return values

true	The Address is in the list

Definition at line 889 of file address.c.

{
  if (!needle || !haystack)
    return false;
 
  struct Address *a = NULL;
  TAILQ_FOREACH(a, haystack, entries)
  {
    if (mutt_addr_cmp(needle, a))
      return true;
  }
  return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_to_intl()

int mutt_addrlist_to_intl	(	struct AddressList *	al,
		char **	err
	)

Convert an Address list to Punycode.

Parameters

[in]	al	Address list to modify
[out]	err	Pointer for failed addresses

Return values

0	Success, all addresses converted
-1	Error, err will be set to the failed address

Definition at line 1278 of file address.c.

{
  if (!al)
    return 0;
 
  int rc = 0;
 
  if (err)
    *err = NULL;
 
  struct Address *a = NULL;
  TAILQ_FOREACH(a, al, entries)
  {
    if (!a->mailbox || addr_is_intl(a))
      continue;
 
    char *user = NULL;
    char *domain = NULL;
    if (addr_mbox_to_udomain(a->mailbox, &user, &domain) == -1)
      continue;
 
    char *intl_mailbox = mutt_idna_local_to_intl(user, domain);
 
    FREE(&user);
    FREE(&domain);
 
    if (!intl_mailbox)
    {
      rc = -1;
      if (err && !*err)
        *err = mutt_str_dup(a->mailbox);
      continue;
    }
 
    addr_set_intl(a, intl_mailbox);
  }
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_to_local()

int mutt_addrlist_to_local

(

struct AddressList *

al

)

Convert an Address list from Punycode.

Parameters

al	Address list to modify

Return values

0

Always

Definition at line 1361 of file address.c.

{
  if (!al)
    return 0;
 
  struct Address *a = NULL;
  TAILQ_FOREACH(a, al, entries)
  {
    mutt_addr_to_local(a);
  }
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_uses_unicode()

bool mutt_addrlist_uses_unicode

(

const struct AddressList *

al

)

Do any of a list of addresses use Unicode characters.

Parameters

al	Address list to check

Return values

true	Any use 8-bit characters

Definition at line 1505 of file address.c.

{
  if (!al)
  {
    return false;
  }
 
  struct Address *a = NULL;
  TAILQ_FOREACH(a, al, entries)
  {
    if (a->mailbox && !a->group && mutt_addr_uses_unicode(a->mailbox))
      return true;
  }
  return false;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_write()

size_t mutt_addrlist_write	(	const struct AddressList *	al,
		struct Buffer *	buf,
		bool	display
	)

Write an Address to a buffer.

Parameters

al	AddressList to display
buf	Buffer for the Address
display	This address will be displayed to the user

Return values

num	Length of the string written to buf

If 'display' is set, then it doesn't matter if the transformation isn't reversible.

Definition at line 1192 of file address.c.

{
  return addrlist_write(al, buf, display, NULL, -1);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_write_wrap()

size_t mutt_addrlist_write_wrap	(	const struct AddressList *	al,
		struct Buffer *	buf,
		const char *	header
	)

Write an AddressList to a buffer, perform line wrapping.

Parameters

al	AddressList to display
buf	Buffer for the Address
header	Header name; if present, addresses we be written after ": "

Return values

num	Length of the string written to buf

If 'display' is set, then it doesn't matter if the transformation isn't reversible.

Definition at line 1175 of file address.c.

{
  return addrlist_write(al, buf, false, header, 74);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_write_file()

void mutt_addrlist_write_file	(	const struct AddressList *	al,
		FILE *	fp,
		const char *	header
	)

Wrapper for mutt_write_address()

Parameters

al	Address list
fp	File to write to
header	Header name; if present, addresses we be written after ": "

So we can handle very large recipient lists without needing a huge temporary buffer in memory

Definition at line 1234 of file address.c.

{
  struct Buffer *buf = mutt_buffer_pool_get();
  mutt_addrlist_write_wrap(al, buf, header);
  fputs(mutt_buffer_string(buf), fp);
  mutt_buffer_pool_release(&buf);
  fputc('\n', fp);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_addrlist_write_list()

size_t mutt_addrlist_write_list	(	const struct AddressList *	al,
		struct ListHead *	list
	)

Write Addresses to a List.

Parameters

al	AddressList to write
list	List for the Addresses

Return values

num	Number of addresses written

Definition at line 1203 of file address.c.

{
  if (!al || !list)
    return 0;
 
  size_t count = 0;
  struct Address *a = NULL;
  TAILQ_FOREACH(a, al, entries)
  {
    struct Buffer buf = { 0 };
    mutt_addr_write(&buf, a, true);
    if (!mutt_buffer_is_empty(&buf))
    {
      /* We're taking the ownership of the buffer string here */
      mutt_list_insert_tail(list, (char *) mutt_buffer_string(&buf));
      count++;
    }
  }
 
  return count;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

AddressError

int AddressError

extern

An out-of-band error code.

Many of the Address functions set this variable on error. Its values are defined in AddressError. Text for the errors can be looked up using AddressErrors.

Definition at line 57 of file address.c.

AddressErrors

const char* const AddressErrors[]

extern

Messages for the error codes in AddressError.

These must defined in the same order as enum AddressError.

Definition at line 64 of file address.c.

AddressSpecials

const char AddressSpecials[]

extern

Characters with special meaning for email addresses.

Definition at line 42 of file address.c.