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