<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>mail::address</title>
<link rel="stylesheet" href="manpage.css" type="text/css"/>
<link rel="start" href="index.html" title="Cone: COnsole Newsreader And Emailer"/>
<link rel="up" href="misc.html" title="Extra/Miscellaneous objects/methods"/>
<link rel="prev" href="misc.html" title="Extra/Miscellaneous objects/methods"/>
<link rel="next" href="mail-attachments.html" title="mail::Attachment"/>
<link xmlns="" rel="icon" href="icon.gif" type="image/gif"/>
<meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/>
<!--
Copyright 2002 - 2007 Double Precision, Inc. See COPYING for distribution
information.
-->
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center" rowspan="1">
mail::address</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="misc.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
Extra/Miscellaneous objects/methods</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="mail-attachments.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="refentry" lang="en" xml:lang="en">
<a id="address" shape="rect" name="address"> </a>
<div class="titlepage"/>
<div class="refnamediv">
<h2>Name</h2>
<p>mail::address — An E-mail address</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="literallayout">
<p><br clear="none"/>
#include <libmail/rfcaddr.H><br clear="none"/>
<br clear="none"/>
mail::address address("John Smith", "johnsmith@example.com");<br clear="none"/>
<br clear="none"/>
std::string addr=address.getAddr();<br clear="none"/>
std::string name=address.getName();<br clear="none"/>
<br clear="none"/>
address.setAddr(addr);<br clear="none"/>
address.setName(name);<br clear="none"/>
<br clear="none"/>
std::string str=address.toString();<br clear="none"/>
<br clear="none"/>
std::vector<mail::address> addressList;<br clear="none"/>
<br clear="none"/>
std::string header= mail::address::toString("From: ", addressList,<br clear="none"/>
                                            size_t width=76);<br clear="none"/>
<br clear="none"/>
size_t errorIndex;<br clear="none"/>
<br clear="none"/>
bool error=mail::address::fromString(std::string addresses,<br clear="none"/>
                                     addressList,<br clear="none"/>
                                     errorIndex);<br clear="none"/>
<br clear="none"/>
std::string stdAddr=address.getCanonAddress();<br clear="none"/>
<br clear="none"/>
mail::address addr1, addr2;<br clear="none"/>
<br clear="none"/>
bool same= addr1 == addr2;<br clear="none"/>
bool notsame= addr1 != addr2;<br clear="none"/></p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id639436" shape="rect" name="id639436"> </a>
<h2>USAGE</h2>
<p><span class="structname">mail::address</span> represents a
single E-mail address. An E-mail address consists of the
recipient's name, and the actual address in the format of
<em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>domain</code></em>. The name and the
address components may be accessed or changed by <code class="function">getName()</code>, <code class="function">getAddr()</code>, <code class="function">setName()</code> and <code class="function">setAddr()</code> methods.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p><span class="structname">mail::emailAddress</span> would
be a more appropriate class for most situations. The name
component used by <code class="function">getName()</code>
and <code class="function">setName()</code> methods is the
Internet-format, MIME-encoded name. <span class="structname">mail::emailAddress</span> is a subclass of
<span class="structname">mail::address</span>, and provides
more convenient methods for working with the name component
of an E-mail address.</p>
<p>The <code class="function">toString</code> and
<code class="function">fromString</code> methods, defined
below, will take a vector of either <span class="structname">mail::emailAddress</span> or <span class="structname">mail::address</span> objects, and in all other
ways both classes are freely interchangable, and may be
converted to one another.</p>
</div>
<p>The <code class="function">toString</code> method converts
an address to a text string formatted as "<code class="literal">name <user@domain></code>". A second
<code class="function">toString</code> 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 <span class="structname">mail::address</span> objects. An optional third
parameter sets the maximum line width; the text string
returned by <code class="function">toString</code> will have
newline characters, if necessary to make sure that each line
is shorter than the specified maximum.</p>
<p><code class="function">fromString</code> does the
opposite: it converts the contents of an E-mail header to an
array of <span class="structname">mail::address</span>
objects. The first parameter is the E-mail header's contents
(<span class="emphasis"><em>without</em></span> <code class="literal">Header-Name:</code>). The second parameter is a
reference to a vector of <span class="structname">mail::address</span> objects. <code class="function">fromString</code> returns false if a fatal error
has occured (out of memory, or something else). <em class="parameter"><code>errorIndex</code></em> is normally set to
<code class="literal">string::npos</code>. If the header
cannot be parsed; <em class="parameter"><code>errorIndex</code></em> is set to the index
of the character in <em class="parameter"><code>addresses</code></em> where a syntax error
was found (the header is still parsed, and any recognizable
addresses are still saved in <em class="parameter"><code>addressList</code></em>).</p>
<p><em class="parameter"><code>addressList</code></em> should
be empty. Otherwise the addresses are appended to <em class="parameter"><code>addressList</code></em>'s existing
contents.</p>
<div class="refsect2" lang="en" xml:lang="en">
<a id="id639650" shape="rect" name="id639650"> </a>
<h3>Comparing addresses</h3>
<p>The <em class="replaceable"><code>domain</code></em>
part of an E-mail address is case insensitive, however the
<em class="replaceable"><code>user</code></em> part of an
E-mail address is not case insensitive. It is up to each
individual <em class="replaceable"><code>domain</code></em>
whether or not the <em class="replaceable"><code>user</code></em> part is case
sensitive, or not. Since it is not possible to determine
whether <em class="replaceable"><code>user</code></em> is
case sensitive; the <code class="function">getCanonAddress</code> method returns the E-mail
address as <em class="replaceable"><code>user</code></em>@<em class="replaceable"><code>domain</code></em>, with only the
<em class="replaceable"><code>domain</code></em> part
converted to lowercase.</p>
<p>The object also defines the equality and non-equality
operators, which compare the address portion of two
<span class="structname">mail::address</span> objects (the
name portions are ignored), with the <em class="replaceable"><code>domain</code></em> part of each domain
being case insensitive</p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en">
<a id="id639711" shape="rect" name="id639711"> </a>
<h2>SEE ALSO</h2>
<p><a class="link" href="emailaddress.html" title="mail::emailAddress" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::emailAddress</span>(3x)</span></a>,
<a class="link" href="envelope.html" title="mail::envelope" shape="rect"><span class="citerefentry"><span class="refentrytitle">mail::envelope</span>(3x)</span></a>.</p>
</div>
</div>
<div class="navfooter">
<hr/>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="misc.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="misc.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="mail-attachments.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">Extra/Miscellaneous objects/methods </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="h" href="index.html" shape="rect">Home</a> | <a accesskey="t" href="bk01-toc.html" shape="rect">ToC</a></td>
<td width="40%" align="right" valign="top" rowspan="1" colspan="1"> mail::Attachment</td>
</tr>
</table>
</div>
</body>
</html>
