mail::address — An E-mail address
#include <libmail/rfcaddr.H>
mail::address address("John Smith", "johnsmith@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
(without Header-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