README
1 NAME
2 Convert::TNEF - Perl module to read TNEF files
3
4 INSTALL
5 The usual:
6 perl Makefile.PL
7 make
8 make test
9 make install
10
11 SYNOPSIS
12 use Convert::TNEF;
13
14 $tnef = Convert::TNEF->read($iohandle, \%parms)
15 or die Convert::TNEF::errstr;
16
17 $tnef = Convert::TNEF->read_in($filename, \%parms)
18 or die Convert::TNEF::errstr;
19
20 $tnef = Convert::TNEF->read_ent($mime_entity, \%parms)
21 or die Convert::TNEF::errstr;
22
23 $tnef->purge;
24
25 $message = $tnef->message;
26
27 @attachments = $tnef->attachments;
28
29 $attribute_value = $attachments[$i]->data($att_attribute_name);
30 $attribute_value_size = $attachments[$i]->size($att_attribute_name);
31 $attachment_name = $attachments[$i]->name;
32 $long_attachment_name = $attachments[$i]->longname;
33
34 $datahandle = $attachments[$i]->datahandle($att_attribute_name);
35
36
37 DESCRIPTION
38 TNEF stands for Transport Neutral Encapsulation Format, and if you've
39 ever been unfortunate enough to receive one of these files as an email
40 attachment, you may want to use this module.
41
42 read() takes as its first argument any file handle open
43 for reading. The optional second argument is a hash reference
44 which contains one or more of the following keys:
45
46
47 output_dir - Path for storing TNEF attribute data kept in files
48 (default: current directory).
49
50 output_prefix - File prefix for TNEF attribute data kept in files
51 (default: 'tnef').
52
53 output_to_core - TNEF attribute data will be saved in core memory unless
54 it is greater than this many bytes (default: 4096). May also be set to
55 'NONE' to keep all data in files, or 'ALL' to keep all data in core.
56
57 buffer_size - Buffer size for reading in the TNEF file (default: 1024).
58
59 debug - If true, outputs all sorts of info about what the read() function
60 is reading, including the raw ascii data along with the data converted
61 to hex (default: false).
62
63 display_after_err - If debug is true and an error is encountered,
64 reads and displays this many bytes of data following the error
65 (default: 32).
66
67 debug_max_display - If debug is true then read and display at most
68 this many bytes of data for each TNEF attribute (default: 1024).
69
70 debug_max_line_size - If debug is true then at most this many bytes of
71 data will be displayed on each line for each TNEF attribute
72 (default: 64).
73
74 ignore_checksum - If true, will ignore checksum errors while parsing
75 data (default: false).
76
77 read() returns an object containing the TNEF 'attributes' read from the
78 file and the data for those attributes. If all you want are the
79 attachments, then this is mostly garbage, but if you're interested then
80 you can see all the garbage by turning on debugging. If the garbage
81 proves useful to you, then let me know how I can maybe make it more
82 useful.
83
84 If an error is encountered, an undefined value is returned and the
85 package variable $errstr is set to some helpful message.
86
87 read_in() is a convienient front end for read() which takes a filename
88 instead of a handle.
89
90 read_ent() is another convient front end for read() which can take a
91 MIME::Entity object (or any object with like methods, specifically
92 open("r"), read($buff,$num_bytes), and close ).
93
94 purge() deletes any on-disk data that may be in the attachments of
95 the TNEF object.
96
97 message() returns the message portion of the tnef object, if any.
98 The thing it returns is like an attachment, but its not an attachment.
99 For instance, it more than likely does not have a name or any
100 attachment data.
101
102 attachments() returns a list of the attachments that the given TNEF
103 object contains.
104
105 data() takes a TNEF attribute name, and returns a string value for that
106 attribute for that attachment. Its your own problem if the string is too
107 big for memory. If no argument is given, then the 'AttachData' attribute
108 is assumed, which is probably the data you're looking for.
109
110 name() is the same as data(), except the attribute 'AttachTitle' is
111 assumed, which returns the 8 character + 3 character extension name of
112 the attachment.
113
114 longname() returns the long filename and extension of an attachment. This
115 is embedded in the 'Attachment' attribute data, so we attempt to extract
116 the name out of that.
117
118 size() takes an TNEF attribute name, and returns the size in bytes for
119 the data for that attachment attribute.
120
121 datahandle() is a method for attachments which takes a TNEF attribute
122 name, and returns the data for that attribute as an object which is
123 the same as a MIME::Body object. See MIME::Body for all the applicable
124 methods. If no argument is given, then 'AttachData' is assumed.
125
126 SEE ALSO
127 perl(1), IO::Wrap(3), MIME::Parser(3), MIME::Entity(3), MIME::Body(3)
128
129 CAVEATS
130 The parsing may depend on the endianness (see perlport) and width of
131 integers on the system where the TNEF file was created. If this proves
132 to be the case (check the debug output), I'll see what I can do
133 about it.
134
135 AUTHOR
136 Douglas Wilson, dougw@cpan.org
137