.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "TNEF 3"
.TH TNEF 3 "2012-07-23" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& Convert::TNEF \- Perl module to read TNEF files
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Convert::TNEF;
\&
\& $tnef = Convert::TNEF\->read($iohandle, \e%parms)
\&  or die Convert::TNEF::errstr;
\&
\& $tnef = Convert::TNEF\->read_in($filename, \e%parms)
\&  or die Convert::TNEF::errstr;
\&
\& $tnef = Convert::TNEF\->read_ent($mime_entity, \e%parms)
\&  or die Convert::TNEF::errstr;
\&
\& $tnef\->purge;
\&
\& $message = $tnef\->message;
\&
\& @attachments = $tnef\->attachments;
\&
\& $attribute_value      = $attachments[$i]\->data($att_attribute_name);
\& $attribute_value_size = $attachments[$i]\->size($att_attribute_name);
\& $attachment_name = $attachments[$i]\->name;
\& $long_attachment_name = $attachments[$i]\->longname;
\&
\& $datahandle = $attachments[$i]\->datahandle($att_attribute_name);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 3
\& TNEF stands for Transport Neutral Encapsulation Format, and if you\*(Aqve
\& ever been unfortunate enough to receive one of these files as an email
\& attachment, you may want to use this module.
\&
\& read() takes as its first argument any file handle open
\& for reading. The optional second argument is a hash reference
\& which contains one or more of the following keys:
.Ve
.SS ""
.IX Subsection ""
.Vb 2
\& output_dir \- Path for storing TNEF attribute data kept in files
\& (default: current directory).
\&
\& output_prefix \- File prefix for TNEF attribute data kept in files
\& (default: \*(Aqtnef\*(Aq).
\&
\& output_to_core \- TNEF attribute data will be saved in core memory unless
\& it is greater than this many bytes (default: 4096). May also be set to
\& \*(AqNONE\*(Aq to keep all data in files, or \*(AqALL\*(Aq to keep all data in core.
\&
\& buffer_size \- Buffer size for reading in the TNEF file (default: 1024).
\&
\& debug \- If true, outputs all sorts of info about what the read() function
\& is reading, including the raw ascii data along with the data converted
\& to hex (default: false).
\&
\& display_after_err \- If debug is true and an error is encountered,
\& reads and displays this many bytes of data following the error
\& (default: 32).
\&
\& debug_max_display \- If debug is true then read and display at most
\& this many bytes of data for each TNEF attribute (default: 1024).
\&
\& debug_max_line_size \- If debug is true then at most this many bytes of
\& data will be displayed on each line for each TNEF attribute
\& (default: 64).
\&
\& ignore_checksum \- If true, will ignore checksum errors while parsing
\& data (default: false).
\&
\& read() returns an object containing the TNEF \*(Aqattributes\*(Aq read from the
\& file and the data for those attributes. If all you want are the
\& attachments, then this is mostly garbage, but if you\*(Aqre interested then
\& you can see all the garbage by turning on debugging. If the garbage
\& proves useful to you, then let me know how I can maybe make it more
\& useful.
\&
\& If an error is encountered, an undefined value is returned and the
\& package variable $errstr is set to some helpful message.
\&
\& read_in() is a convienient front end for read() which takes a filename
\& instead of a handle.
\&
\& read_ent() is another convient front end for read() which can take a
\& MIME::Entity object (or any object with like methods, specifically
\& open("r"), read($buff,$num_bytes), and close ).
\&
\& purge() deletes any on\-disk data that may be in the attachments of
\& the TNEF object.
\&
\& message() returns the message portion of the tnef object, if any.
\& The thing it returns is like an attachment, but its not an attachment.
\& For instance, it more than likely does not have a name or any
\& attachment data.
\&
\& attachments() returns a list of the attachments that the given TNEF
\& object contains. Returns a list ref if not called in array context.
\&
\& data() takes a TNEF attribute name, and returns a string value for that 
\& attribute for that attachment. Its your own problem if the string is too
\& big for memory. If no argument is given, then the \*(AqAttachData\*(Aq attribute
\& is assumed, which is probably the attachment data you\*(Aqre looking for.
\&
\& name() is the same as data(), except the attribute \*(AqAttachTitle\*(Aq is
\& the default, which returns the 8 character + 3 character extension name
\& of the attachment.
\&
\& longname() returns the long filename and extension of an attachment. This
\& is embedded within a MAPI property of the \*(AqAttachment\*(Aq attribute data, so
\& we attempt to extract the name out of that.
\&
\& size() takes an TNEF attribute name, and returns the size in bytes for
\& the data for that attachment attribute.
\&
\& datahandle() is a method for attachments which takes a TNEF attribute
\& name, and returns the data for that attribute as a handle which is
\& the same as a MIME::Body handle.  See MIME::Body for all the applicable
\& methods. If no argument is given, then \*(AqAttachData\*(Aq is assumed.
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 4
\& # Here\*(Aqs a rather long example where mail is retrieved
\& # from a POP3 server based on header information, then
\& # it is MIME parsed, and then the TNEF contents
\& # are extracted and converted.
\&
\& use strict;
\& use Net::POP3;
\& use MIME::Parser;
\& use Convert::TNEF;
\&
\& my $mail_dir = "mailout";
\& my $mail_prefix = "mail";
\&
\& my $pop = new Net::POP3 ( "pop3server_name" );
\& my $num_msgs = $pop\->login("user_name","password");
\& die "Can\*(Aqt login: $!" unless defined $num_msgs;
\&
\& # Get mail by sender and subject
\& my $mail_out_idx = 0;
\& MESSAGE: for ( my $i=1; $i<= $num_msgs;  $i++ ) {
\&  my $header = join "", @{$pop\->top($i)};
\&
\&  for ($header) {
\&   next MESSAGE unless
\&    /^from:.*someone\e@somewhere.net/im &&
\&    /^subject:\es*important stuff/im
\&  }
\&
\&  my $fname = $mail_prefix."\-".$$.++$mail_out_idx.".doc";
\&  open (MAILOUT, ">$mail_dir/$fname")
\&   or die "Can\*(Aqt open $mail_dir/$fname: $!";
\&  # If the get() complains, you need the new libnet bundle
\&  $pop\->get($i, \e*MAILOUT) or die "Can\*(Aqt read mail";
\&  close MAILOUT or die "Error closing $mail_dir/$fname";
\&  # If you want to delete the mail on the server
\&  # $pop\->delete($i);
\& }
\&
\& close MAILOUT;
\& $pop\->quit();
\&
\& # Parse the mail message into separate mime entities
\& my $parser=new MIME::Parser;
\& $parser\->output_dir("mimemail");
\&
\& opendir(DIR, $mail_dir) or die "Can\*(Aqt open directory $mail_dir: $!";
\& my @files = map { $mail_dir."/".$_ } sort
\&  grep { \-f "$mail_dir/$_" and /$mail_prefix\-$$\-/o } readdir DIR;
\& closedir DIR;
\&
\& for my $file ( @files ) {
\&  my $entity=$parser\->parse_in($file) or die "Couldn\*(Aqt parse mail";
\&  print_tnef_parts($entity);
\&  # If you want to delete the working files
\&  # $entity\->purge;
\& }
\&
\& sub print_tnef_parts {
\&  my $ent = shift;
\&
\&  if ( $ent\->parts ) {
\&   for my $sub_ent ( $ent\->parts ) {
\&    print_tnef_parts($sub_ent);
\&   }
\&  } elsif ( $ent\->mime_type =~ /ms\-tnef/i ) {
\&
\&   # Create a tnef object
\&   my $tnef = Convert::TNEF\->read_ent($ent,{output_dir=>"tnefmail"})
\&    or die $Convert::TNEF::errstr;
\&   for ($tnef\->attachments) {
\&    print "Title:",$_\->name,"\en";
\&    print "Data:\en",$_\->data,"\en";
\&   }
\&
\&   # If you want to delete the working files
\&   # $tnef\->purge;
\&  }
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBIO::Wrap\fR\|(3), \fBMIME::Parser\fR\|(3), \fBMIME::Entity\fR\|(3), \fBMIME::Body\fR\|(3)
.SH "CAVEATS"
.IX Header "CAVEATS"
.Vb 4
\& The parsing may depend on the endianness (see perlport) and width of
\& integers on the system where the TNEF file was created. If this proves
\& to be the case (check the debug output), I\*(Aqll see what I can do
\& about it.
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\& Douglas Wilson, dougw@cpan.org
.Ve