@code{#include <mailutils/mailbox.h>}
@deftp {Data Type} address_t
The @code{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 a address in the address list.

Several address functions have a set of common arguments, which are described
here to avoid repetition.

Since an address-list may contain multiple addresses, they are accessed
by a @strong{one-based} index number, @var{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 @var{len} is greater than @code{0} it is the length of the buffer
@var{buf}, and as much of the component as possible will be copied
into the buffer. The buffer will be nul terminated.

The size of a particular component may be queried by providing @code{0}
for the @var{len} of the buffer, in which case the buffer is optional.
In this case, if @var{n} is provided *@var{n} is assigned the length of
the component string.

Comments:

What happens if @var{no} is past the end of the list? I think you
just get zero-length output, but it should be an error, maybe EINVAL.

Musings:

Two problems are domain literals, and non-ascii characters. I
think domain literals should be parsed from [127.0.0.1] into
the more commonly groked 127.0.0.1 when somebody does a get_domain()
on one, and that if somebody wants to provide one as a domain, they
can.

Non ascii chars are uglier, perhaps a warning? Perhaps a non-strict
switch that makes it an error, and otherwise if they want umlauts
and utf-8 in the strings, just allow it? The machinery to encode
and decode header fields according to the MIME spec doesn't really
belong here, it's a layer on top of rfc822.

@end deftp

@deftypefun int address_create (address_t *@var{addr}, const char *@var{string})
This function allocates and initializes @var{addr} by parsing the
RFC822 address-list @var{string}. Parsing is best effort, if the
@var{string} isn't a valid RFC822 syntax list of addresses, then
the results are undefined.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item ENOMEM
Not enough memory to allocate resources.
@end table
@end deftypefun

@deftypefun  void address_destroy (address_t *@var{addr})
The @var{addr} is destroyed.
@end deftypefun

@deftypefun  int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})

Acesses the @var{no}th 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 @code{0} on success and a code number on error conditions:
@table @code
@item EINVAL
@var{addr} is NULL.
@end table
@end deftypefun

@deftypefun  int address_get_personal (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})

Acesses the personal phrase describing the @var{no}th email address. This
phrase is optional, so may not be present.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EINVAL
@var{addr} is NULL.
@end table
@end deftypefun


@deftypefun  int address_get_comments (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})

Acesses the comments extracted while parsing the @var{no}th email address.
These comments have no defined meaning, but in the absence of the personal
descriptive phrase, may describe the email address.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EINVAL
@var{addr} is NULL.
@end table
@end deftypefun


@deftypefun  int address_to_string (address_t *@var{addr}, char* @var{buf}, size_t @var{len}, size_t* @var{n})

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

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EINVAL
@var{addr} is NULL.
@end table
@end deftypefun


@deftypefun  int address_get_count (address_t *@var{addr}, size_t* @var{no})

Returns the number of addresses in the address list.

The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EINVAL
@var{addr} is NULL.
@end table
@end deftypefun


@section Example
@example
#include <stdio.h>
#include <mailutils/address.h>

int
main(int argc, const char *argv[])
@{
  for(argc = 1; argv[argc]; argc++)
  @{
    const char* str = argv[argc];
    address_t  address = NULL;

    address_create(&address, str);

    printf("'%s' ->\n", str);
    @{
      size_t no = 0;
      size_t pcount;

      address_get_count(address, &pcount);

      printf("  pcount %d\n", pcount);

      for(no = 1; no <= pcount; no++)
      @{
        char buf[BUFSIZ];

        address_get_personal(address, no, buf, sizeof(buf), 0);

        printf("  personal '%s'\n", buf);

        address_get_comments(address, no, buf, sizeof(buf), 0);

        printf("  comments '%s'\n", buf);

        address_get_email(address, no, buf, sizeof(buf), 0);

        printf("  email '%s'\n", buf);

        address_to_string(address, buf, sizeof(buf), 0);

        printf("  to_string '%s'\n", buf);
      @}
    @}
    
    address_destroy(&address);
  @}

  return 0;
@}
@end example