1TNEF(3) User Contributed Perl Documentation TNEF(3)
2
6 Convert::TNEF - Perl module to read TNEF files
7
9 use Convert::TNEF;
10 $tnef = Convert::TNEF->read($iohandle, \%parms)
12 or die Convert::TNEF::errstr;
13 $tnef = Convert::TNEF->read_in($filename, \%parms)
15 or die Convert::TNEF::errstr;
16 $tnef = Convert::TNEF->read_ent($mime_entity, \%parms)
18 or die Convert::TNEF::errstr;
19 $tnef->purge;
21 $message = $tnef->message;
23 @attachments = $tnef->attachments;
25 $attribute_value = $attachments[$i]->data($att_attribute_name);
27 $attribute_value_size = $attachments[$i]->size($att_attribute_name);
28 $attachment_name = $attachments[$i]->name;
29 $long_attachment_name = $attachments[$i]->longname;
30 $datahandle = $attachments[$i]->datahandle($att_attribute_name);
32
34 TNEF stands for Transport Neutral Encapsulation Format, and if you've
35 ever been unfortunate enough to receive one of these files as an email
36 attachment, you may want to use this module.
37 read() takes as its first argument any file handle open
39 for reading. The optional second argument is a hash reference
40 which contains one or more of the following keys:
41 output_dir - Path for storing TNEF attribute data kept in files
45 (default: current directory).
46 output_prefix - File prefix for TNEF attribute data kept in files
48 (default: 'tnef').
49 output_to_core - TNEF attribute data will be saved in core memory unless
51 it is greater than this many bytes (default: 4096). May also be set to
52 'NONE' to keep all data in files, or 'ALL' to keep all data in core.
53 buffer_size - Buffer size for reading in the TNEF file (default: 1024).
55 debug - If true, outputs all sorts of info about what the read() function
57 is reading, including the raw ascii data along with the data converted
58 to hex (default: false).
59 display_after_err - If debug is true and an error is encountered,
61 reads and displays this many bytes of data following the error
62 (default: 32).
63 debug_max_display - If debug is true then read and display at most
65 this many bytes of data for each TNEF attribute (default: 1024).
66 debug_max_line_size - If debug is true then at most this many bytes of
68 data will be displayed on each line for each TNEF attribute
69 (default: 64).
70 ignore_checksum - If true, will ignore checksum errors while parsing
72 data (default: false).
73 read() returns an object containing the TNEF 'attributes' read from the
75 file and the data for those attributes. If all you want are the
76 attachments, then this is mostly garbage, but if you're interested then
77 you can see all the garbage by turning on debugging. If the garbage
78 proves useful to you, then let me know how I can maybe make it more
79 useful.
80 If an error is encountered, an undefined value is returned and the
82 package variable $errstr is set to some helpful message.
83 read_in() is a convienient front end for read() which takes a filename
85 instead of a handle.
86 read_ent() is another convient front end for read() which can take a
88 MIME::Entity object (or any object with like methods, specifically
89 open("r"), read($buff,$num_bytes), and close ).
90 purge() deletes any on-disk data that may be in the attachments of
92 the TNEF object.
93 message() returns the message portion of the tnef object, if any.
95 The thing it returns is like an attachment, but its not an attachment.
96 For instance, it more than likely does not have a name or any
97 attachment data.
98 attachments() returns a list of the attachments that the given TNEF
100 object contains. Returns a list ref if not called in array context.
101 data() takes a TNEF attribute name, and returns a string value for that
103 attribute for that attachment. Its your own problem if the string is too
104 big for memory. If no argument is given, then the 'AttachData' attribute
105 is assumed, which is probably the attachment data you're looking for.
106 name() is the same as data(), except the attribute 'AttachTitle' is
108 the default, which returns the 8 character + 3 character extension name
109 of the attachment.
110 longname() returns the long filename and extension of an attachment. This
112 is embedded within a MAPI property of the 'Attachment' attribute data, so
113 we attempt to extract the name out of that.
114 size() takes an TNEF attribute name, and returns the size in bytes for
116 the data for that attachment attribute.
117 datahandle() is a method for attachments which takes a TNEF attribute
119 name, and returns the data for that attribute as a handle which is
120 the same as a MIME::Body handle. See MIME::Body for all the applicable
121 methods. If no argument is given, then 'AttachData' is assumed.
122
124 # Here's a rather long example where mail is retrieved
125 # from a POP3 server based on header information, then
126 # it is MIME parsed, and then the TNEF contents
127 # are extracted and converted.
128 use strict;
130 use Net::POP3;
131 use MIME::Parser;
132 use Convert::TNEF;
133 my $mail_dir = "mailout";
135 my $mail_prefix = "mail";
136 my $pop = new Net::POP3 ( "pop3server_name" );
138 my $num_msgs = $pop->login("user_name","password");
139 die "Can't login: $!" unless defined $num_msgs;
140 # Get mail by sender and subject
142 my $mail_out_idx = 0;
143 MESSAGE: for ( my $i=1; $i<= $num_msgs; $i++ ) {
144 my $header = join "", @{$pop->top($i)};
145 for ($header) {
147 next MESSAGE unless
148 /^from:.*someone\@somewhere.net/im &&
149 /^subject:\s*important stuff/im
150 }
151 my $fname = $mail_prefix."-".$$.++$mail_out_idx.".doc";
153 open (MAILOUT, ">$mail_dir/$fname")
154 or die "Can't open $mail_dir/$fname: $!";
155 # If the get() complains, you need the new libnet bundle
156 $pop->get($i, \*MAILOUT) or die "Can't read mail";
157 close MAILOUT or die "Error closing $mail_dir/$fname";
158 # If you want to delete the mail on the server
159 # $pop->delete($i);
160 }
161 close MAILOUT;
163 $pop->quit();
164 # Parse the mail message into separate mime entities
166 my $parser=new MIME::Parser;
167 $parser->output_dir("mimemail");
168 opendir(DIR, $mail_dir) or die "Can't open directory $mail_dir: $!";
170 my @files = map { $mail_dir."/".$_ } sort
171 grep { -f "$mail_dir/$_" and /$mail_prefix-$$-/o } readdir DIR;
172 closedir DIR;
173 for my $file ( @files ) {
175 my $entity=$parser->parse_in($file) or die "Couldn't parse mail";
176 print_tnef_parts($entity);
177 # If you want to delete the working files
178 # $entity->purge;
179 }
180 sub print_tnef_parts {
182 my $ent = shift;
183 if ( $ent->parts ) {
185 for my $sub_ent ( $ent->parts ) {
186 print_tnef_parts($sub_ent);
187 }
188 } elsif ( $ent->mime_type =~ /ms-tnef/i ) {
189 # Create a tnef object
191 my $tnef = Convert::TNEF->read_ent($ent,{output_dir=>"tnefmail"})
192 or die $Convert::TNEF::errstr;
193 for ($tnef->attachments) {
194 print "Title:",$_->name,"\n";
195 print "Data:\n",$_->data,"\n";
196 }
197 # If you want to delete the working files
199 # $tnef->purge;
200 }
201 }
202
204 perl(1), IO::Wrap(3), MIME::Parser(3), MIME::Entity(3), MIME::Body(3)
205
207 The parsing may depend on the endianness (see perlport) and width of
208 integers on the system where the TNEF file was created. If this proves
209 to be the case (check the debug output), I'll see what I can do
210 about it.
211
213 Douglas Wilson, dougw@cpan.org
214perl v5.8.8 2002-02-24 TNEF(3)