mail::address.3x man page
mail::address — An E-mail address
#include <libmail/rfcaddr.H> mail::address address("John Smith", "email@example.com"); std::string addr=address.getAddr(); std::string name=address.getName(); address.setAddr(addr); address.setName(name); std::string str=address.toString(); std::vector<mail::address> addressList; std::string header= mail::address::toString("From: ", addressList, size_t width=76); size_t errorIndex; bool error=mail::address::fromString(std::string addresses, addressList, errorIndex); std::string stdAddr=address.getCanonAddress(); mail::address addr1, addr2; bool same= addr1 == addr2; bool notsame= addr1 != addr2;
mail::address represents a single E-mail address. An E-mail address consists of the recipient's name, and the actual address in the format of user@domain. The name and the address components may be accessed or changed by getName(), getAddr(), setName() and setAddr() methods.
mail::emailAddress would be a more appropriate class for most situations. The name component used by getName() and setName() methods is the Internet-format, MIME-encoded name. mail::emailAddress is a subclass of mail::address, and provides more convenient methods for working with the name component of an E-mail address.
The toString and fromString methods, defined below, will take a vector of either mail::emailAddress or mail::address objects, and in all other ways both classes are freely interchangable, and may be converted to one another.
The toString method converts an address to a text string formatted as "name <user@domain>". A second toString function creates an E-mail header that contains a comma-separated list of E-mail addresses. The first parameter must be the header's name (with a trailing space character); the second parameter is a reference to a vector of mail::address objects. An optional third parameter sets the maximum line width; the text string returned by toString will have newline characters, if necessary to make sure that each line is shorter than the specified maximum.
fromString does the opposite: it converts the contents of an E-mail header to an array of mail::address objects. The first parameter is the E-mail header's contents (withoutHeader-Name:). The second parameter is a reference to a vector of mail::address objects. fromString returns false if a fatal error has occured (out of memory, or something else). errorIndex is normally set to string::npos. If the header cannot be parsed; errorIndex is set to the index of the character in addresses where a syntax error was found (the header is still parsed, and any recognizable addresses are still saved in addressList).
addressList should be empty. Otherwise the addresses are appended to addressList's existing contents.
The domain part of an E-mail address is case insensitive, however the user part of an E-mail address is not case insensitive. It is up to each individual domain whether or not the user part is case sensitive, or not. Since it is not possible to determine whether user is case sensitive; the getCanonAddress method returns the E-mail address as user@domain, with only the domain part converted to lowercase.
The object also defines the equality and non-equality operators, which compare the address portion of two mail::address objects (the name portions are ignored), with the domain part of each domain being case insensitive