/src/dovecot/src/lib-smtp/smtp-address.h

Source
#ifndef SMTP_ADDRESS_H
#define SMTP_ADDRESS_H

#include "array-decl.h"

struct message_address;

enum smtp_address_parse_flags {
  /* Strictly enforce the RFC 5321 syntax */
  SMTP_ADDRESS_PARSE_FLAG_STRICT              = BIT(0),
  /* Allow an empty/NULL address */
  SMTP_ADDRESS_PARSE_FLAG_ALLOW_EMPTY         = BIT(1),
  /* Allow an address without a domain part */
  SMTP_ADDRESS_PARSE_FLAG_ALLOW_LOCALPART     = BIT(2),
  /* Allow omission of the <...> brackets in a path. This flag is only
     relevant for smtp_address_parse_path(). */
  SMTP_ADDRESS_PARSE_FLAG_BRACKETS_OPTIONAL   = BIT(3),
  /* Allow localpart to have all kinds of bad unquoted characters by
     parsing the last '@' in the string directly as the localpart/domain
     separator. Addresses starting with `<' or `"' are parsed as normal.
     The address is rejected when the resulting localpart and domain
     cannot be used to construct a valid RFC 5321 address.
   */
  SMTP_ADDRESS_PARSE_FLAG_ALLOW_BAD_LOCALPART = BIT(4),
  /* Store an unparsed copy of the address in the `raw' field of struct
     smtp_address. When combined with SMTP_ADDRESS_PARSE_FLAG_SKIP_BROKEN,
     the broken address will be stored there. This flag is only relevant
     for smtp_address_parse_path(). */
  SMTP_ADDRESS_PARSE_FLAG_PRESERVE_RAW        = BIT(5),
  /* Try to skip over a broken address to allow working around syntax
     errors in e.g. the sender address for the MAIL command. This flag is
     only relevant for smtp_address_parse_path*(). The parser will return
     failure, but it will return a broken address which is be equivalent
     to <>. The raw broken address string is available in the address->raw
     field. When the broken address contains control characters or is
     badly delimited, parsing will still fail completely. */
  SMTP_ADDRESS_PARSE_FLAG_IGNORE_BROKEN       = BIT(6),
};

struct smtp_address {
  /* Localpart */
  const char *localpart;
  /* Domain */
  const char *domain;
  /* Raw, unparsed address. If localpart == NULL, the value of this field
     is syntactically invalid and MUST NOT be used for any purposes that
     may be visible to external systems. It can be e.g. used for logging.
     This is always in mailbox format, meaning that there are no
     surrounding '<' and '>'.
   */
  const char *raw;
};

ARRAY_DEFINE_TYPE(smtp_address, struct smtp_address *);
ARRAY_DEFINE_TYPE(smtp_address_const, const struct smtp_address *);

/*
 * SMTP address parsing
 */


/* Parse the RFC 5321 address from the provided mailbox string. Returns 0 when
   the address was parsed successfully and -1 upon error. The address is
   returned in address_r. When address_r is NULL, the provided string will be
   verified for validity as a mailbox only. */
int smtp_address_parse_mailbox(pool_t pool, const char *mailbox,
             enum smtp_address_parse_flags flags,
             struct smtp_address **address_r,
             const char **error_r) ATTR_NULL(4, 5);
/* Parse the RFC 5321 address from the provided path string. Returns 0 when
   the address was parsed successfully and -1 upon error. The address is
   returned in address_r. When address_r is NULL, the provided string will be
   verified for validity as a path only. The endp_r parameter is used to
   return a pointer to the end of the path string, so that the caller can
   continue parsing from there. When the SMTP_ADDRESS_PARSE_FLAG_IGNORE_BROKEN
   flag is set, a broken address will be returned, even when the return value
   is -1 (see above). If it is totally broken, *endp_r will be then be NULL.
 */
int smtp_address_parse_path_full(pool_t pool, const char *path,
         enum smtp_address_parse_flags flags,
         struct smtp_address **address_r,
         const char **error_r, const char **endp_r)
         ATTR_NULL(4, 5, 6);
/* Parse the RFC 5321 address from the provided path string. Returns 0 when
   the address was parsed successfully and -1 upon error. The address is
   returned in address_r. When address_r is NULL, the provided string will be
   verified for validity as a path only. When the
   SMTP_ADDRESS_PARSE_FLAG_IGNORE_BROKEN flag is set, a broken address will be
   returned, even when the return value is -1 (see above). */
int smtp_address_parse_path(pool_t pool, const char *path,
          enum smtp_address_parse_flags flags,
          struct smtp_address **address_r,
          const char **error_r) ATTR_NULL(4, 5);
/* Parse the RFC 5321 address from the provided username string. A username
   string is not strictly parsed as an RFC 5321 mailbox; it allows a more
   lenient syntax. If the address obtained from splitting the string at the last
   `@' can be encoded back into a valid RFC 5321 mailbox string, parsing the
   username will succeeded. Returns 0 when the address was parsed successfully
   and -1 upon error. The address is returned in address_r. When address_r is
   NULL, the provided string will be verified for validity as a username only.
 */
int smtp_address_parse_username(pool_t pool, const char *username,
        struct smtp_address **address_r,
        const char **error_r) ATTR_NULL(3, 4);

/* Parse address+detail@domain into address@domain and detail
   using given delimiters. Returns used delimiter. */
void smtp_address_detail_parse(pool_t pool, const char *delimiters,
             struct smtp_address *address,
             const char **username_r, char *delim_r,
             const char **detail_r);
void smtp_address_detail_parse_temp(const char *delimiters,
            struct smtp_address *address,
            const char **username_r, char *delim_r,
            const char **detail_r);

/* Parse any (possibly broken) address on the input to the best of our ability
   until end of input or unquoted ` '. Things that are truly evil (unending
   quoted string, control characters and a path without a closing '>') will
   still fail and return -1. If the parse was successful, it will return 0.
   The parsed address string is returned in address_r. Any outer < and > are
   omitted in the parsed address. The endp_r parameter is used to return a
   pointer to the end of the path string, so that the caller can continue
   parsing from there.*/
int smtp_address_parse_any(const char *in, const char **address_r,
         const char **endp_r) ATTR_NULL(2, 3);

/*
 * SMTP address construction
 */

void smtp_address_write(string_t *out, const struct smtp_address *address)
      ATTR_NULL(2);
void smtp_address_write_path(string_t *out, const struct smtp_address *address)
      ATTR_NULL(2);

const char *smtp_address_encode(const struct smtp_address *address)
        ATTR_NULL(1);
const char *smtp_address_encode_path(const struct smtp_address *address)
             ATTR_NULL(1);

const char *
smtp_address_encode_raw(const struct smtp_address *address) ATTR_NULL(1);
const char *
smtp_address_encode_raw_path(const struct smtp_address *address) ATTR_NULL(1);

/*
 * SMTP address manipulation
 */

void smtp_address_init(struct smtp_address *address,
           const char *localpart, const char *domain)
           ATTR_NULL(2,3);
int smtp_address_init_from_msg(struct smtp_address *address,
             const struct message_address *msg_addr);

struct smtp_address *
smtp_address_clone(pool_t pool, const struct smtp_address *address)
       ATTR_NULL(2);
struct smtp_address *
smtp_address_create(pool_t pool, const char *localpart, const char *domain)
        ATTR_NULL(2, 3);
int smtp_address_create_from_msg(pool_t pool,
         const struct message_address *msg_addr,
         struct smtp_address **address_r);

struct smtp_address *
smtp_address_clone_temp(const struct smtp_address *address) ATTR_NULL(1);
struct smtp_address *
smtp_address_create_temp(const char *localpart, const char *domain)
       ATTR_NULL(2, 3);
int smtp_address_create_from_msg_temp(const struct message_address *msg_addr,
              struct smtp_address **address_r);

struct smtp_address *
smtp_address_add_detail(pool_t pool, const struct smtp_address *address,
      const char *detail, char delim_c);
struct smtp_address *
smtp_address_add_detail_temp(const struct smtp_address *address,
           const char *detail, char delim_c);

int smtp_address_cmp(const struct smtp_address *address1,
         const struct smtp_address *address2) ATTR_NULL(1, 2);
int smtp_address_cmp_icase(const struct smtp_address *address1,
        const struct smtp_address *address2) ATTR_NULL(1, 2);

static inline bool ATTR_NULL(1, 2)
smtp_address_equals(const struct smtp_address *address1,
        const struct smtp_address *address2)
{
  return (smtp_address_cmp(address1, address2) == 0);
}
static inline bool ATTR_NULL(1, 2)
smtp_address_equals_icase(const struct smtp_address *address1,
        const struct smtp_address *address2)
{
  return (smtp_address_cmp_icase(address1, address2) == 0);
}

static inline bool ATTR_NULL(1) ATTR_PURE
smtp_address_isnull(const struct smtp_address *address)
{
  return (address == NULL || address->localpart == NULL);
}

static inline bool ATTR_NULL(1) ATTR_PURE
smtp_address_is_broken(const struct smtp_address *address)
{
  return (address != NULL &&
    smtp_address_isnull(address) &&
    (address->raw != NULL && *address->raw != '\0'));
}

#endif

Coverage Report

Created: 2026-10-28 07:22

Line	Count	Source
1		#ifndef SMTP_ADDRESS_H
2		#define SMTP_ADDRESS_H
3
4		#include "array-decl.h"
5
6		struct message_address;
7
8		enum smtp_address_parse_flags {
9		/* Strictly enforce the RFC 5321 syntax */
10		SMTP_ADDRESS_PARSE_FLAG_STRICT = BIT(0),
11		/* Allow an empty/NULL address */
12		SMTP_ADDRESS_PARSE_FLAG_ALLOW_EMPTY = BIT(1),
13		/* Allow an address without a domain part */
14		SMTP_ADDRESS_PARSE_FLAG_ALLOW_LOCALPART = BIT(2),
15		/* Allow omission of the <...> brackets in a path. This flag is only
16		relevant for smtp_address_parse_path(). */
17		SMTP_ADDRESS_PARSE_FLAG_BRACKETS_OPTIONAL = BIT(3),
18		/* Allow localpart to have all kinds of bad unquoted characters by
19		parsing the last '@' in the string directly as the localpart/domain
20		separator. Addresses starting with `<' or `"' are parsed as normal.
21		The address is rejected when the resulting localpart and domain
22		cannot be used to construct a valid RFC 5321 address.
23		*/
24		SMTP_ADDRESS_PARSE_FLAG_ALLOW_BAD_LOCALPART = BIT(4),
25		/* Store an unparsed copy of the address in the `raw' field of struct
26		smtp_address. When combined with SMTP_ADDRESS_PARSE_FLAG_SKIP_BROKEN,
27		the broken address will be stored there. This flag is only relevant
28		for smtp_address_parse_path(). */
29		SMTP_ADDRESS_PARSE_FLAG_PRESERVE_RAW = BIT(5),
30		/* Try to skip over a broken address to allow working around syntax
31		errors in e.g. the sender address for the MAIL command. This flag is
32		only relevant for smtp_address_parse_path*(). The parser will return
33		failure, but it will return a broken address which is be equivalent
34		to <>. The raw broken address string is available in the address->raw
35		field. When the broken address contains control characters or is
36		badly delimited, parsing will still fail completely. */
37		SMTP_ADDRESS_PARSE_FLAG_IGNORE_BROKEN = BIT(6),
38		};
39