#include <mailutils/mailbox.h>
 -- 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 the address list. An address list is a sequence of addresses, each of which has four components: an optional phrase describing the address, the local-part of the address, the domain of the address, and an optional comment field.

     If the phrase is present it is probably the personal name associated with the the address, if not, the comment may contain some identifying information.

     Since the address-list may contain multiple addresses, they are accessed by a one-based index number, NO.

     Comment: Why is this one-based? nobody familiar with C would ever expect that!

     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 and if N is provided *N is assigned the length of the component string.

     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.

     Comments:

     The API isn't complete, there are useful things you can't do.

     There needs to be a way of accessing the local-part and the domain of an email address seperately, the syntax of local-part is too complex to expect somebody to parse it, in particular strchring for '@' will fail if there is an '@' in the local-part, which is valid if its quoted or escaped.

     You can't create an address or an address list.

     Creating one should apropriately quote unsafe characters in the local part and phrase/personal name, not allow a comment (its deprecated), etc.

     What about groups? They are easy to parse, but a pain from an api point of view. _address, instead of being a pure linked list, could be more tree-like, so each _address also contained and _address* group member. If there was a group, then email would be the name of the group, something like "my special group: ;", and group would be the (possibly empty) list of addresses in the group, and each of those addresses could in turn be a group, etc.

     This data structure reflects the structure of an address ok, but doesn't address (;-)) what happens if you had a program that just wanted to print out all the recipients email addresses. The NO could still be a linear index into the tree, so those not wanting to know could not know, and the group nodes could silently dissappear.

     But what if you wanted to iterate the whole tree? address_is_group(addr, no)? address_get_group_name(addr, no)? address_get_group(addr, &addr)?

     For creating, maybe the easy way is to splice an address list.

     address_create(&addr, NULL)

     address_insert(addr, -1, "Big John", "bluesman", "yahoo.com");

     // -1 is the end, anything else is position to be inserted at, for ex.

     address_create(&group, NULL)

     address_insert(group, -1, "Sam", "sroberts", "uniserve.com");

     address_insert(group, -1, "Joe  \"home\"", "joe", "uniserve.com");

     address_insert_group(addr, group, "the uniserve boys");

     This would be:

            Big John <bluesman@yahoo.com>, the uniserve boys: Sam
            <sroberts@uniserve.com>, "Joe @ \"home\"" <joe@uniserve.com> ;

     This is just a sketch of what I think should be conceptually possible in a complete address parser class. Basically the goals are to be able to see the structure of an RFC822 address exactly (except for comments... they get munged together if present, but what the hell, they're comments!) and to build as complex an address as is possible. Simple things should still be simple.

     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.

 -- 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:

     ENOMEM
          Not enough memory to allocate resources.

 -- 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) Acesses the NOth email address component.

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

     EINVAL
          ADDR is NULL.