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("", "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.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.