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