ch16_02.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

$<em class="replaceable">msg</em>-&gt;bcc(<em class="replaceable">values</em>)
</pre><p><a name="INDEX-2080" />Adds a <tt class="literal">Bcc</tt>
header containing the mail addresses specified in the list of
<em class="replaceable"><tt>values</tt></em> to the message. If there already is
a <tt class="literal">Bcc</tt>, the new values replace any old values.
</p></div>

<a name="INDEX-2081" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>cancel</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
<em class="replaceable">$msg</em>-&gt;cancel
</pre><p><a name="INDEX-2081" />Not implemented yet, but will
cancel the message.
</p></div>

<a name="INDEX-2082" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>cc</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
<em class="replaceable">$msg</em>-&gt;cc(<em class="replaceable">values</em>)
</pre><p><a name="INDEX-2082" />Adds a <tt class="literal">Cc</tt>
header containing the mail addresses in the list of
<em class="replaceable"><tt>values</tt></em> to the message. If there already is
a <tt class="literal">Cc</tt>, the new values replace any old values.
</p></div>

<a name="INDEX-2083" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>close</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">fh</em>-&gt;close
</pre><p><a name="INDEX-2083" />Closes the filehandle
<tt class="literal">$</tt><em class="replaceable"><tt>fh</tt></em> (which was returned
by <tt class="literal">open</tt>) and sends the message.
</p></div>

<a name="INDEX-2084" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>delete</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">msg</em>-&gt;delete(<em class="replaceable">header</em>)
</pre><p><a name="INDEX-2084" />Deletes the header
<em class="replaceable"><tt>header</tt></em> from the message.
</p></div>

<a name="INDEX-2085" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>open</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">fh</em> = $<em class="replaceable">msg</em>-&gt;open
</pre><p><a name="INDEX-2085" />Opens a filehandle for the message
object. The filehandle is a Mail::Mailer object.
</p></div>

<a name="INDEX-2086" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>set</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">msg</em>-&gt;set(<em class="replaceable">header</em>, <em class="replaceable">values</em>)
</pre><p><a name="INDEX-2086" />Sets the header
<em class="replaceable"><tt>header</tt></em> to the contents of the array
<em class="replaceable"><tt>values</tt></em>.
</p></div>

<a name="INDEX-2087" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>subject</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">msg</em>-&gt;subject('<em class="replaceable">What this message is about</em>')
</pre><p><a name="INDEX-2087" />Sets the value of the
<tt class="literal">Subject</tt> field.
</p></div>

<a name="INDEX-2088" /><a name="INDEX-2089" /><a name="INDEX-2090" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>to</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">msg</em>-&gt;to(<em class="replaceable">values</em>)
</pre><p><a name="INDEX-2088" />Sets the <tt class="literal">To</tt> field to
the list of recipients in
<em class="replaceable"><tt>values</tt></em>.<a name="INDEX-2089" /><a name="INDEX-2090" />
</p></div>

</div>
<a name="perlnut2-CHP-16-SECT-2.3" /><div class="sect2">
<h3 class="sect2">16.2.3. Handle Folders with Mail::Folder</h3>

<p><a name="INDEX-2091" /><a name="INDEX-2092" /><a name="INDEX-2093" /><a name="INDEX-2094" />Once you've begun
downloading and reading your mail from a POP server, you might want
to save or categorize your messages into folders, which allow you to
add, delete, save, and move messages easily. You can do this with
Mail::Folder, which was written by Kevin Johnson as an
object-oriented, folder-independent interface to mail folders.
Mail::Folder supports a number of mailbox formats with the following
interfaces:
</p>

<dl>
<dt><i>Mail::Folder::Emaul</i></dt>
<dd>
A folder interface somewhat similar to MH.</p>
</dd>


<dt><i>Mail::Folder::Maildir</i></dt>
<dd>
An interface to <em class="emphasis">maildir</em> folders.</p>
</dd>


<dt><i>Mail::Folder::Mbox</i></dt>
<dd>
Standard Unix mailbox format.</p>
</dd>


<dt><i>Mail::Folder::NNTP</i></dt>
<dd>
The beginnings of an interface to NNTP. Not all the methods are
implemented yet.
</p>
</dd>

</dl>

<p>If you are interested in writing a folder interface, see the
documentation for the module. The documentation explains the concepts
and issues involved and describes some of the methods you may need to
override.
</p>

<p>The following methods are defined for Mail::Folder.</p>



<a name="INDEX-2095" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>new</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">folder</em> = new(<em class="replaceable">ftype</em>[, <em class="replaceable">foldername</em>][, <em class="replaceable">options</em>])
</pre><p><a name="INDEX-2095" />Creates a new Mail::Folder object of
the specified type. Arguments are:
</p><dl>
<dt><i><em class="replaceable"><tt>ftype</tt></em></i></dt>
<dd>
The type of folder. Possible values are <tt class="literal">mbox</tt>,
<tt class="literal">maildir</tt>, <tt class="literal">emaul</tt>, or
<tt class="literal">NNTP</tt>.
</p>
</dd>


<dt><i><em class="replaceable"><tt>foldername</tt></em></i></dt>
<dd>
The name of the folder. If present, the <tt class="literal">open</tt>
method is called with <em class="replaceable"><tt>foldername</tt></em> as the
argument.
</p>
</dd>


<dt><i><em class="replaceable"><tt>options</tt></em></i></dt>
<dd>
A hash in which the following options may be the keys:</p>

<dl>

<dt><b><tt class="literal">Content-Length</tt></b></dt>
<dd>
<tt class="literal">Content-length</tt> header is created or updated by
<tt class="literal">append_message</tt> and
<tt class="literal">update_message</tt>.
</p>
</dd>


<dt><b><tt class="literal">Create</tt></b></dt>
<dd>
If set, the folder is created if it doesn't already
exist.
</p>
</dd>


<dt><b><tt class="literal">DefaultFolderType</tt></b></dt>
<dd>
Autodetects folder type if <tt class="literal">create</tt> option is set
and <tt class="literal">AUTODETECT</tt> has been set.
</p>
</dd>


<dt><b><tt class="literal">DotLock</tt></b></dt>
<dd>
Uses <em class="filename">.lock</em>-style folder locking with the proper
folder interface (currently used only with the
<em class="filename">mbox</em> interface).
</p>
</dd>


<dt><b><tt class="literal">Flock</tt></b></dt>
<dd>
Uses <tt class="literal">flock</tt>-style folder locking with the proper
folder interface (currently used only with the
<em class="filename">mbox</em> interface).
</p>
</dd>


<dt><b><tt class="literal">NFSLock</tt></b></dt>
<dd>
Deals with NFS-style file locking with the proper folder interface
and the NFS server in question.
</p>
</dd>


<dt><b><tt class="literal">notMUA</tt></b></dt>
<dd>
If set, makes updates but doesn't save message
labels or the current message indicator. If not set (the default),
saves labels and the current message indicator as appropriate for the
folder interface.
</p>
</dd>


<dt><b><tt class="literal">Timeout</tt></b></dt>
<dd>
Overrides the default timeout value. Specified in seconds.
Particularly useful for folder interfaces that involve network
communications.
</p>
</dd>

</dl>
</dd>

</dl></div>

<a name="INDEX-2096" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>add_label</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">folder</em>-&gt;add_label(<em class="replaceable">msg_num</em>, <em class="replaceable">label</em>)
</pre><p><a name="INDEX-2096" />Associates the label
<em class="replaceable"><tt>label</tt></em> with the message
<em class="replaceable"><tt>msg_num</tt></em>. Returns <tt class="literal">1</tt> on
success or <tt class="literal">0</tt> if the label has a length of 0.
Possible values of <em class="replaceable"><tt>label</tt></em> are:
</p><dl>
<dt><b><tt class="literal">deleted</tt></b></dt>
<dd>
Used by <tt class="literal">delete_message</tt> and <tt class="literal">sync</tt>
to process message deletion.
</p>
</dd>


<dt><b><tt class="literal">edited</tt></b></dt>
<dd>
Added by <tt class="literal">update_message</tt> to indicate that the
message has been edited.
</p>
</dd>


<dt><b><tt class="literal">filed</tt>, <tt class="literal">forwarded</tt>, <tt class="literal">printed</tt>, <tt class="literal">replied</tt></b></dt>