<<< Previous |  | Next >>>

# mail::address

## Name

mail::address -- An E-mail address

## Synopsis

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

## USAGE

`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.

NOTE: | `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.

### Comparing addresses

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

## SEE ALSO

mail::emailAddress(3x), mail::envelope(3x).

<<< Previous | Home | Next >>>
Extra/Miscellaneous objects/methods | Up | mail::Attachment