571 lines
16 KiB
HTML
571 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::Mail::Parts - Data storage class for MIME parts</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#effective_type__access_the_effective_mime_type">effective_type - Access the effective MIME type</a></li>
|
|
<li><a href="#get__access_header_tags_">get - Access header tags.</a></li>
|
|
<li><a href="#set__set_a_header_tag_">set - Set a header tag.</a></li>
|
|
<li><a href="#delete__remove_a_header_tag_">delete - Remove a header tag.</a></li>
|
|
<li><a href="#size__access_the_total_size_">size - Access the total size.</a></li>
|
|
<li><a href="#preamble__set_or_get_the_preamble_">preamble - Set or get the preamble.</a></li>
|
|
<li><a href="#epilogue__set_or_get_the_epilogue_">epilogue - Set or get the epilogue.</a></li>
|
|
<li><a href="#mime_type__set_or_get_the_mime_type_">mime_type - Set or get the MIME type.</a></li>
|
|
<li><a href="#is_multipart__see_if_you_have_a_multipart_part_">is_multipart - See if you have a multi-part part.</a></li>
|
|
<li><a href="#parts__access_sub_parts_">parts - Access sub parts.</a></li>
|
|
<li><a href="#multipart_boundary__set_or_get_the_multipart_boundary_">multipart_boundary - Set or get the multi-part boundary.</a></li>
|
|
<li><a href="#header_as_string__access_the_whole_header_">header_as_string - Access the whole header.</a></li>
|
|
<li><a href="#split_field__retrieve_the_emails_split_up_into_an_array_">split_field - Retrieve the emails split up into an array.</a></li>
|
|
<li><a href="#suggest_encoding__get_a_suggestion_for_encoding_">suggest_encoding - Get a suggestion for encoding.</a></li>
|
|
<li><a href="#recommended_filename__figure_out_the_file_name_">recommended_filename - Figure out the file name.</a></li>
|
|
<li><a href="#body_as_string__get_the_body_as_a_string_">body_as_string - Get the body as a string.</a></li>
|
|
<li><a href="#body_in__find_the_body_">body_in - Find the body.</a></li>
|
|
<li><a href="#body_data__get_the_in_memory_body_">body_data - Get the in memory body.</a></li>
|
|
<li><a href="#body_handle__get_an_io_handle_to_the_body_">body_handle - Get an IO handle to the body.</a></li>
|
|
<li><a href="#body_path__get_the_location_of_the_file_the_body_is_in_">body_path - Get the location of the file the body is in.</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::Mail::Parts - Data storage class for MIME parts</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::Mail;</pre>
|
|
<pre>
|
|
my $mail = new GT::Mail;</pre>
|
|
<pre>
|
|
my $top_part = $mail->parse('/path/to/email');</pre>
|
|
<pre>
|
|
# Access the emails as an array
|
|
my @to = $top_part->split_field('to');
|
|
my @from = $top_part->split_field('from');</pre>
|
|
<pre>
|
|
# Access to the header fields
|
|
my $mailer = $top_part->get('X-Mailer');
|
|
my $subject = $top_part->get('Subject');</pre>
|
|
<pre>
|
|
# Access to this parts sub part
|
|
if ($top_part->is_multipart) {
|
|
my @parts = $top_parts->parts;
|
|
for my $part (@parts) {</pre>
|
|
<pre>
|
|
# Access parts of the header
|
|
print "Filename: ", $part->recommended_filename, "\n";
|
|
print "Part is multi-part\n" if $part->is_multipart;</pre>
|
|
<pre>
|
|
# Get the body as a string
|
|
my $body = $part->body_as_string;
|
|
}
|
|
}</pre>
|
|
<pre>
|
|
# Change who it is to
|
|
$top_part->set('to', 'scott@gossamer-threads.com');</pre>
|
|
<pre>
|
|
# Remove the bcc line
|
|
$top_part->delete('bcc');</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::Mail::Parts is a class to provide methods to change and
|
|
access a MIME messages. The object for this class is meant to
|
|
be istansiated from <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail.html">the GT::Mail manpage</a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="effective_type__access_the_effective_mime_type">effective_type - Access the effective MIME type</a></h2>
|
|
<pre>
|
|
my $type = $obj->effective_type;</pre>
|
|
<pre>
|
|
if ($type eq 'application/octet-stream') {
|
|
...
|
|
}</pre>
|
|
<p>This method returns the effective MIME Type of this objects part.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="get__access_header_tags_">get - Access header tags.</a></h2>
|
|
<pre>
|
|
my $subj = $obj->get('Subject');</pre>
|
|
<pre>
|
|
# or if there is more than one
|
|
my @recv = $obj->get('Received');</pre>
|
|
<p>Used to access any of the tags in the header of the MIME part. If the
|
|
tag requested is not present returns false. The first argument to this
|
|
method is the name of he tag you want to extract. This is case insensitive.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="set__set_a_header_tag_">set - Set a header tag.</a></h2>
|
|
<pre>
|
|
# Change who the email is to
|
|
$obj->set('to', 'scott@gossamer-threads.com');</pre>
|
|
<pre>
|
|
# Change the second Received tag
|
|
$obj->set('Received', 'from unknown', 1);</pre>
|
|
<p>Set any of the tags in the header. If the tag does not exist this will create
|
|
it. This method takes three arguments. The first is the name of the tag to
|
|
change or add, this is case insensitive. The second argument is the value for
|
|
the tag. The third zero based optional argument is the position. The position
|
|
will default to zero if it is not specified.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="delete__remove_a_header_tag_">delete - Remove a header tag.</a></h2>
|
|
<pre>
|
|
# Delete who the message is from
|
|
$obj->delete('from');</pre>
|
|
<p>This method deletes the tag specified by the first argument from this MIME
|
|
part.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="size__access_the_total_size_">size - Access the total size.</a></h2>
|
|
<pre>
|
|
my $size = $obj->size;</pre>
|
|
<p>This method returns the total size of this part. This includes the header and
|
|
the body.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="preamble__set_or_get_the_preamble_">preamble - Set or get the preamble.</a></h2>
|
|
<pre>
|
|
# Retrieve the preamble
|
|
my $pre = $obj->preamble;</pre>
|
|
<pre>
|
|
# Set the preamble
|
|
$obj->preamble('This is a multi-part message in MIME format.');</pre>
|
|
<p>This is a set get method for the preamble. The preamble is the part after the
|
|
head but before the first MIME boundary. This method makes no since if this
|
|
is not a multi-part part.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="epilogue__set_or_get_the_epilogue_">epilogue - Set or get the epilogue.</a></h2>
|
|
<pre>
|
|
# Retrieve the epilogue
|
|
my $ep = $obj->epilogue;</pre>
|
|
<pre>
|
|
# Set the epilogue
|
|
$obj->epilogue('This is my cool epilogue');</pre>
|
|
<p>This is a set get method for the epilogue. The epilogue is the part of the
|
|
MIME part after the MIME boundary and before the next head. This method makes
|
|
no since if this is not a multi-part part.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="mime_type__set_or_get_the_mime_type_">mime_type - Set or get the MIME type.</a></h2>
|
|
<pre>
|
|
my ($type, $subtype) = split('/', $obj->mime_type);</pre>
|
|
<p>This method returns the MIME type of this part. You can pass in an argument
|
|
to change the MIME type as well. So you could do</p>
|
|
<pre>
|
|
$obj->mime_type('text/plain');</pre>
|
|
<p>This is probably not such a good idea unless you are constructing the email from
|
|
scratch.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="is_multipart__see_if_you_have_a_multipart_part_">is_multipart - See if you have a multi-part part.</a></h2>
|
|
<pre>
|
|
if ($obj->is_multipart) {
|
|
# do some multi-part stuff
|
|
}</pre>
|
|
<p>Returns true is this part is a multi-part MIME part.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parts__access_sub_parts_">parts - Access sub parts.</a></h2>
|
|
<pre>
|
|
my @parts = $obj->parts;</pre>
|
|
<p>Returns the parts object this part contains. Returns false if this part does
|
|
no have any sub parts. The parts objects that returns are from this same class.
|
|
Any parts that are milti-part should contain parts.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="multipart_boundary__set_or_get_the_multipart_boundary_">multipart_boundary - Set or get the multi-part boundary.</a></h2>
|
|
<pre>
|
|
my $boundary = $obj->multipart_boundary;</pre>
|
|
<p>This returns the multi-part boundary for this part. Setting this is never needed
|
|
and may be removed in the future. This method only makes since if you are working
|
|
with a multi-part pert.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="header_as_string__access_the_whole_header_">header_as_string - Access the whole header.</a></h2>
|
|
<pre>
|
|
my $head = $obj->header_as_string;</pre>
|
|
<p>This method creates and returns the header for this part. The returned header should
|
|
be fully rfc822 compliant. Avoid calling this method more than once, as it will build
|
|
the header from an internal data structure each time.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="split_field__retrieve_the_emails_split_up_into_an_array_">split_field - Retrieve the emails split up into an array.</a></h2>
|
|
<pre>
|
|
my @to = $obj->split_field; # Defaults to 'to'
|
|
my @bcc = $obj->split_field('bcc');</pre>
|
|
<p>This is mostly a utility method. It takes an option argument as to the field you want
|
|
the email address from (default is to), it then splits the emails on '\s*,\s*' that is
|
|
not inside quotes. Returns an array of the split up string.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="suggest_encoding__get_a_suggestion_for_encoding_">suggest_encoding - Get a suggestion for encoding.</a></h2>
|
|
<pre>
|
|
my $encode = $obj->suggest_encoding;</pre>
|
|
<p>Returns a suggested encoding for the body of this message. This is useful to decide
|
|
what encoding you should use for the body when building an email. This is used in
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parse.html">the GT::Mail::Parse manpage</a> to decide how to encode the message body.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="recommended_filename__figure_out_the_file_name_">recommended_filename - Figure out the file name.</a></h2>
|
|
<pre>
|
|
my $file = $obj->recommended_filename;
|
|
if ($file) {
|
|
...
|
|
}</pre>
|
|
<p>This method tries to figure out the file name of this part. This does not make much
|
|
since if this part is not an attachment of some kind. Returns an empty string on
|
|
failure.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="body_as_string__get_the_body_as_a_string_">body_as_string - Get the body as a string.</a></h2>
|
|
<p>This method returns the entire body of the MIME message as a string. You should not
|
|
use this method if the body could be large.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="body_in__find_the_body_">body_in - Find the body.</a></h2>
|
|
<pre>
|
|
my $in = $obj->body_in;
|
|
my $body;</pre>
|
|
<pre>
|
|
if ($in eq 'MEMORY') {
|
|
$body = $obj->body_data;
|
|
}
|
|
elsif ($in eq 'HANDLE') {
|
|
$body = $obj->body_handle;
|
|
}
|
|
elsif ($in eq 'FILE') {
|
|
$body = $obj->body_path;
|
|
}</pre>
|
|
<p>This method returns the location of the body. The location can be one of three things:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_memory">MEMORY</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
The body is in a string.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_handle">HANDLE</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
The body is in an IO handle.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_file">FILE</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
The body is in a file.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>You would use this to decide what method to use to access the body. If the MIME message
|
|
was parsed into GT::Mail::Parts using <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parser.html">the GT::Mail::Parser manpage</a> the body will always be in
|
|
a FILE.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="body_data__get_the_in_memory_body_">body_data - Get the in memory body.</a></h2>
|
|
<p>This method returns the body if it is stored in memory. Returns undefined if the body is
|
|
not in memory.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="body_handle__get_an_io_handle_to_the_body_">body_handle - Get an IO handle to the body.</a></h2>
|
|
<p>This method returns a handle to the body if the body is stored in a handle for this part.
|
|
Returns undefined if not.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="body_path__get_the_location_of_the_file_the_body_is_in_">body_path - Get the location of the file the body is in.</a></h2>
|
|
<p>This method returns the file path to the file the body is located in if the body for this
|
|
part is stored in a file. Returns undefined if not.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>$Revision: 1.77 $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|