1TNEF(3)               User Contributed Perl Documentation              TNEF(3)
2
3
4

NAME

6        Convert::TNEF - Perl module to read TNEF files
7

SYNOPSIS

9        use Convert::TNEF;
10
11        $tnef = Convert::TNEF->read($iohandle, \%parms)
12         or die Convert::TNEF::errstr;
13
14        $tnef = Convert::TNEF->read_in($filename, \%parms)
15         or die Convert::TNEF::errstr;
16
17        $tnef = Convert::TNEF->read_ent($mime_entity, \%parms)
18         or die Convert::TNEF::errstr;
19
20        $tnef->purge;
21
22        $message = $tnef->message;
23
24        @attachments = $tnef->attachments;
25
26        $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
31        $datahandle = $attachments[$i]->datahandle($att_attribute_name);
32

DESCRIPTION

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
38        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
42
43        output_dir - Path for storing TNEF attribute data kept in files
44        (default: current directory).
45
46        output_prefix - File prefix for TNEF attribute data kept in files
47        (default: 'tnef').
48
49        output_to_core - TNEF attribute data will be saved in core memory unless
50        it is greater than this many bytes (default: 4096). May also be set to
51        'NONE' to keep all data in files, or 'ALL' to keep all data in core.
52
53        buffer_size - Buffer size for reading in the TNEF file (default: 1024).
54
55        debug - If true, outputs all sorts of info about what the read() function
56        is reading, including the raw ascii data along with the data converted
57        to hex (default: false).
58
59        display_after_err - If debug is true and an error is encountered,
60        reads and displays this many bytes of data following the error
61        (default: 32).
62
63        debug_max_display - If debug is true then read and display at most
64        this many bytes of data for each TNEF attribute (default: 1024).
65
66        debug_max_line_size - If debug is true then at most this many bytes of
67        data will be displayed on each line for each TNEF attribute
68        (default: 64).
69
70        ignore_checksum - If true, will ignore checksum errors while parsing
71        data (default: false).
72
73        read() returns an object containing the TNEF 'attributes' read from the
74        file and the data for those attributes. If all you want are the
75        attachments, then this is mostly garbage, but if you're interested then
76        you can see all the garbage by turning on debugging. If the garbage
77        proves useful to you, then let me know how I can maybe make it more
78        useful.
79
80        If an error is encountered, an undefined value is returned and the
81        package variable $errstr is set to some helpful message.
82
83        read_in() is a convienient front end for read() which takes a filename
84        instead of a handle.
85
86        read_ent() is another convient front end for read() which can take a
87        MIME::Entity object (or any object with like methods, specifically
88        open("r"), read($buff,$num_bytes), and close ).
89
90        purge() deletes any on-disk data that may be in the attachments of
91        the TNEF object.
92
93        message() returns the message portion of the tnef object, if any.
94        The thing it returns is like an attachment, but its not an attachment.
95        For instance, it more than likely does not have a name or any
96        attachment data.
97
98        attachments() returns a list of the attachments that the given TNEF
99        object contains. Returns a list ref if not called in array context.
100
101        data() takes a TNEF attribute name, and returns a string value for that
102        attribute for that attachment. Its your own problem if the string is too
103        big for memory. If no argument is given, then the 'AttachData' attribute
104        is assumed, which is probably the attachment data you're looking for.
105
106        name() is the same as data(), except the attribute 'AttachTitle' is
107        the default, which returns the 8 character + 3 character extension name
108        of the attachment.
109
110        longname() returns the long filename and extension of an attachment. This
111        is embedded within a MAPI property of the 'Attachment' attribute data, so
112        we attempt to extract the name out of that.
113
114        size() takes an TNEF attribute name, and returns the size in bytes for
115        the data for that attachment attribute.
116
117        datahandle() is a method for attachments which takes a TNEF attribute
118        name, and returns the data for that attribute as a handle which is
119        the same as a MIME::Body handle.  See MIME::Body for all the applicable
120        methods. If no argument is given, then 'AttachData' is assumed.
121

EXAMPLES

123        # Here's a rather long example where mail is retrieved
124        # from a POP3 server based on header information, then
125        # it is MIME parsed, and then the TNEF contents
126        # are extracted and converted.
127
128        use strict;
129        use Net::POP3;
130        use MIME::Parser;
131        use Convert::TNEF;
132
133        my $mail_dir = "mailout";
134        my $mail_prefix = "mail";
135
136        my $pop = new Net::POP3 ( "pop3server_name" );
137        my $num_msgs = $pop->login("user_name","password");
138        die "Can't login: $!" unless defined $num_msgs;
139
140        # Get mail by sender and subject
141        my $mail_out_idx = 0;
142        MESSAGE: for ( my $i=1; $i<= $num_msgs;  $i++ ) {
143         my $header = join "", @{$pop->top($i)};
144
145         for ($header) {
146          next MESSAGE unless
147           /^from:.*someone\@somewhere.net/im &&
148           /^subject:\s*important stuff/im
149         }
150
151         my $fname = $mail_prefix."-".$$.++$mail_out_idx.".doc";
152         open (MAILOUT, ">$mail_dir/$fname")
153          or die "Can't open $mail_dir/$fname: $!";
154         # If the get() complains, you need the new libnet bundle
155         $pop->get($i, \*MAILOUT) or die "Can't read mail";
156         close MAILOUT or die "Error closing $mail_dir/$fname";
157         # If you want to delete the mail on the server
158         # $pop->delete($i);
159        }
160
161        close MAILOUT;
162        $pop->quit();
163
164        # Parse the mail message into separate mime entities
165        my $parser=new MIME::Parser;
166        $parser->output_dir("mimemail");
167
168        opendir(DIR, $mail_dir) or die "Can't open directory $mail_dir: $!";
169        my @files = map { $mail_dir."/".$_ } sort
170         grep { -f "$mail_dir/$_" and /$mail_prefix-$$-/o } readdir DIR;
171        closedir DIR;
172
173        for my $file ( @files ) {
174         my $entity=$parser->parse_in($file) or die "Couldn't parse mail";
175         print_tnef_parts($entity);
176         # If you want to delete the working files
177         # $entity->purge;
178        }
179
180        sub print_tnef_parts {
181         my $ent = shift;
182
183         if ( $ent->parts ) {
184          for my $sub_ent ( $ent->parts ) {
185           print_tnef_parts($sub_ent);
186          }
187         } elsif ( $ent->mime_type =~ /ms-tnef/i ) {
188
189          # Create a tnef object
190          my $tnef = Convert::TNEF->read_ent($ent,{output_dir=>"tnefmail"})
191           or die $Convert::TNEF::errstr;
192          for ($tnef->attachments) {
193           print "Title:",$_->name,"\n";
194           print "Data:\n",$_->data,"\n";
195          }
196
197          # If you want to delete the working files
198          # $tnef->purge;
199         }
200        }
201

SEE ALSO

203       perl(1), IO::Wrap(3), MIME::Parser(3), MIME::Entity(3), MIME::Body(3)
204

CAVEATS

206        The parsing may depend on the endianness (see perlport) and width of
207        integers on the system where the TNEF file was created. If this proves
208        to be the case (check the debug output), I'll see what I can do
209        about it.
210

AUTHOR

212        Douglas Wilson, dougw@cpan.org
213
214
215
216perl v5.12.0                      2002-02-24                           TNEF(3)
Impressum