mail::emailAddress
Prev | Extra/Miscellaneous objects/methods | Next

## Name

mail::emailAddress — An E-mail address

## Synopsis

#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");

## USAGE

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.

## SEE ALSO

mail::address(3x), mail::setappcharset(3x).

Prev | Up | Next
mail::Attachment | Home | ToC | mail::envelope