     /* Prefix address_ is reserved */
     #include <mailutils/address.h>

The Internet address format is defined in RFC 822. RFC 822 has been updated, and is now superceeded by RFC 2822, which makes some corrections and clarifications. References to RFC 822 here apply equally to RFC 2822.

The RFC 822 format is more flexible than many people realize, here is a quick summary of the syntax this parser implements, see RFC 822 for the details. "[]" pairs mean "optional", "/" means "one or the other", and double-quoted characters are literals.

     addr-spec    = local-part " domain
     mailbox      = addr-spec ["(" display-name ")"] /
                    [display-name] "<" [route] addr-spec ">"
     mailbox-list = mailbox ["," mailbox-list]
     group        = display-name ":" [mailbox-list] ";"
     address      = mailbox / group / unix-mbox
     address-list = address ["," address-list]

unix-mbox is a non-standard extension meant to deal with the common practice of using user names as addresses in mail utilities. It allows addresses such as "root" to be parsed correctly. These are NOT valid internet email addresses, they must be qualified before use.

Several address functions have a set of common arguments with consistent semantics, these are described here to avoid repetition.

Since an address-list may contain multiple addresses, they are accessed by a one-based index number, NO. The index is one-based because pop, imap, and other message stores commonly use one-based counts to access messages and attributes of messages.

If LEN is greater than 0 it is the length of the buffer BUF, and as much of the component as possible will be copied into the buffer. The buffer will be null terminated.

The size of a particular component may be queried by providing 0 for the LEN of the buffer, in which case the buffer is optional. In this case, if N is provided *N is assigned the length of the component string.

 -- Data Type: address_t
     The address_t object is used to hold information about a parsed RFC822 address list, and is an opaque data structure to the user. Functions are provided to retrieve information about an address in the address list.

 -- Function: int address_create (address_t *ADDR, const char *STRING)
     This function allocates and initializes ADDR by parsing the RFC822 address-list STRING.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOMEM
          Not enough memory to allocate resources.

     ENOENT
          Invalid RFC822 syntax, parsing failed.

 -- Function: void address_destroy (address_t *ADDR)
     The ADDR is destroyed.

 -- Function: int address_get_email (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N)

     Accesses the NOth email address component of the address list. This address is the plain email address, correctly quoted, suitable for using in an smtp dialog, for example, or as the address part of a contact book entry.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_get_personal (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N)

     Accesses the display-name describing the NOth email address. This display-name is optional, so may not be present. If it is not present, but there is an RFC822 comment after the address, that comment will be returned as the personal phrase, as this is a common usage of the comment even though it is not defined in the internet mail standard.

     A group is a kind of a special case. It has a display-name, followed by an optional mailbox-list. The display-name will be allocated an address all it's own, but all the other elements (local-part, domain, etc.) will be zero-length. So "a group: ;" is valid, will have a count of 1, but address_get_email(), and all the rest, will return zero-length output.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_get_comments (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N)

     Accesses the comments extracted while parsing the NOth email address. These comments have no defined meaning, and are not currently collected.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_get_email (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N)

     Accesses the email addr-spec extracted while parsing the NOth email address. This will be 0 length for a unix-mbox.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_get_local_part (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N)

     Accesses the local-part of an email addr-spec extracted while parsing the NOth email address.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_get_domain (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N)

     Accesses the domain of an email addr-spec extracted while parsing the NOth email address. This will be 0 length for a unix-mbox.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_get_route (address_t *ADDR, size_t NO, char* BUF, size_t LEN, size_t* N)

     Accesses the route of an email addr-spec extracted while parsing the NOth email address. This is a rarely used RFC822 address syntax, but is legal in SMTP as well. The entire route is returned as a string, those wishing to parse it should look at <mailutils/parse822.h>.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_is_group (address_t *ADDR, size_t NO, size_t LEN, int* YES)

     Sets *YES to 1 if this address is just the name of a group, 0 otherwise. This is faster than checking if the address has a non-zero length personal, and a zero-length local_part and domain.

     YES can be null, though that doesn't serve much purpose other than determining that NO refers to an address.

     Currently, there is no way to determine the end of the group.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOENT
          The index NO is outside of the range of available addresses.

 -- Function: int address_to_string (address_t *ADDR, char* BUF, size_t LEN, size_t* N)

     Returns the entire address list as a single RFC822 formatted address list.

     The return value is 0 on success and a code number on error conditions:

     EINVAL
          Invalid usage, usually a required argument was null.

     ENOMEM
          Not enough memory to allocate resources.

 -- Function: int address_get_count (address_t ADDR, size_t* COUNT)

     Returns a count of the addresses in the address list.

     If ADDR is null, the count is 0. If COUNT is not null, the count will be written to *COUNT.

     The return value is 0.

Example
=======

          [file ex-address.texi not included]