mail::emailAddress — An E-mail address
#include <libmail/rfcaddr.H>
mail::emailAddress address;
bool errflag;
address.setDisplayName("Jóse Smith", "iso-8859-1");
address.setDisplayAddr("josesmith@example.com", "utf-8");
std::string addr=address.getDisplayAddr("utf-8");
std::string addr=address.getDisplayAddr("utf-8", errflag);
std::string name=address.getDisplayName("utf-8");
std::string name=address.getDisplayName("utf-8", errflag);
address.setAddr(addr);
address.setDisplayName(name, "utf-8");
mail::emailAddress is a
subclass of mail::address
that defines four new methods: getDisplayName(), setDisplayName(), getDisplayAddr() and setDisplayAddr(), which retrieve or set the
name and the address components of an E-mail address
specified in a native character set. mail::emailAddress can be constructed
from an existing mail::address; or, the default
constructor initializes an empty address, then use
setDisplayName() and
setDisplayAddr() to set the
address structure. setDisplayName() and setDisplayAddr() return an empty string if
the display name or address was succesfully mapped from the
native character, or an error message.
The overloaded methods that take a boolean flag will initialize it to indicate if the address contains characters that do not exist in the specified character set.
Non-Latin characters in the name component use MIME
encoding. Passing the name component to setDisplayName() MIME-encodes it using RFC
2047 and stores the encoded name in the mail::address superclass. setDisplayAddr() encoded non-Latin
characters in the domain portion of the address using IDNA
encoding. getDisplayName() and
getDisplayAddr() retrieve the
name or the address portion from the mail::address superclass, and decode it
into the native character set, accordingly.
For most purposes, using mail::emailAddress is preferrable to
using mail::address.
mail::address's getName(), setName(), getAddr() and setAddr() methods deal with the raw,
MIME-encoded format of E-mail addresses. This structure lets
the application deal with human-readable representation of
the email address.
Convert a native name to its MIME-encoded format by using
setDisplayName() followed by
getName(). Similarly, decode a
MIME-encoded name by using setName() followed by getDisplayName().
Convert an email address to its IDNA-encoded format by
using setDisplayAddr() followed
by getAddr(). Similarly, decode
an IDNA-encoded name by using setAddr() followed by getDisplayAddr().
The toString and
fromString methods are
templates, and may be used with a vector of mail::emailAddress or mail::address objects. The two classes
are completely interchangable. A mail::emailAddress object may be assigned
or converted to a mail::address, and vice-versa.