freeutils.net
Presents:
JTNEF - Java TNEF package
Download
Download the latest release: (What's new?)
JTNEF 1.5.0 (includes source code) (128K)
Previous releases:
JTNEF 1.4.0 (includes source code) (127K)
JTNEF 1.3.1 (includes source code) (112K)
JTNEF 1.3.0 (includes source code) (101K)
JTNEF 1.2.3 (includes source code) (94K)
What is TNEF?
Transport-Neutral Encapsulation Format (TNEF) is Microsoft's non-standard
format for encapsulating mail which has any non-plain-text content or
properties (such as rich text, embedded OLE objects, voting buttons, and
sometimes just attachments). Whether or not a given message is encoded
using TNEF is determined by the Outlook default settings, per-recipient
setting, Exchange Server settings, and message type and content.
Once a TNEF message is used, the entire message, including all the
original attachments and properties, is encapsulated in a single
attachment of mime type "application/ms-tnef" added to the message to be
sent over the Internet. This attachment is usually named "WINMAIL.DAT",
and when sent to any non-MS mail client, is useless, and makes access to
the original message attachments impossible.
What is the Java TNEF package?
The Java TNEF package is an open source code implementation of a TNEF message
handler, which can be used as a command-line utility or integrated into
Java-based mail applications to extract the original message content.
How do I use the Java TNEF package?
The TNEF package is written in pure Java, and thus requires no special
installation. Just add the "tnef.jar" file to your classpath.
If you are an end user getting strange attachments named "WINMAIL.DAT" or
"ATT00001.DAT", instead of other expected attachments, you can simply run
the net.freeutils.tnef.TNEF class from the command line to extract the original
attachments from such a TNEF file.
If you are a Java developer working on a mail client or server, and need
to handle TNEF attachments (because whether u like it or not, they're out
there in real-world messages), you have several choices:
-
Low-level: you can use the TNEFInputStream class to read TNEF
attributes, which are the basic unit in a TNEF stream, and do with
them as you please.
-
Middle-level: the net.freeutils.tnef package gives you access to the
entire TNEF content through simple Java objects representing the
underlying TNEF data structures. You can use these classes to
access all TNEF attributes and MAPI properties that were sent with
the message.
For example, you can choose to implement voting buttons or receipt
notifications in your Java application by finding and interpreting
the appropriate MAPI properties. This requires knowledge of the
MAPI properties and their meaning.
-
High-level: The net.freeutils.tnef.TNEF class is a simple example of
using these middle-level classes to display the message properties
and extract the attachments. You can use it directly from your
application, or just browse the source code for an example of how
to do things yourself.
The net.freeutils.tnef.mime package gives you high-level access to the
TNEF message using the JavaMail API. The TNEFMime class is a simple
example of using these classes, and allows you to extract a TNEF
attachment from a mime message (which can then be processed using the
TNEF or TNEFMime classes) or to convert a TNEF attachment or a message
containing a TNEF attachment to an equivalent standard mime message
with the original header fields and attachments, including read
receipt notification conversion and contact to vCard conversion, etc.
This package is still considered experimental (though it's already
being used in production grade systems), so go ahead and experiment
with it!
The net.freeutils.tnef.msg package contains a proof-of-concept .msg
file handler. The Msg class uses Jakarta's POI project and provides
a simple API for reading a .msg file into a net.freeutils.tnef.Message
instance for access to its MAPI properties and attachments.
If you're interested in the format of the PR_RTF_COMPRESSED MAPI property,
please read on here.
What's New?
in version 1.5.0:
- Changed Msg.processRecipients() to return array instead of List and fixed ClassCaseException.
- Added PR_HTML and PR_BODY_HTML properties and their conversion in TNEFMime.
- Made text body parts converted by TNEFMime use the UTF-8 encoding explicitly.
- Fixed RawInputStream mark/reset implementation.
- Added thrown IOException if attribute length is greater than actual available bytes in TNEFInputStream.readAttr().
- Fixed NullPointerException in ReadReceiptHandler when a field is missing.
- Added TNEFMime command line option to directly convert a TNEF attachment into a MIME file.
- Improved documentation, javadocs, formatting and misc. minor refactorings.
in version 1.4.0:
- Fixed attachment filename to be taken from TNEF attributes if it cannot be determined from the MAPI props.
- Added support for converting a contact field with multiple values to multiple vCard fields in ContactHandler.
- Fixed equals-hashCode contract of MAPIPropName.
- Improved documentation, misc. minor fixes and applied some FindBugs recommendations.
- Introduced the GUID class with immutability guarantee and convenience methods, now used wherever guids are needed.
- Fixed RawInputStream to always handle end of stream conditions properly.
- Added initial proof-of-concept .msg file handling in the new msg package and Msg class.
- Fixed Attachment to remove leading GUID only on PT_OBJECTs.
- Added Attr constructor which accepts an arbitrary data object (not just a RawInputStream).
- Added an empty constructor to Message and extracted a read() method for easier subclassing and external use.
- Added an embed parameter to TNEFMime.convert() for making converted TNEF message embedding optional.
in version 1.3.1:
- Fixed TNEFMime conversion when the TNEF attachment is the root mime part, rather than an attachment.
- Added experimental support for read receipt notifications (RFC 2298) in the new ReadReceiptHandler class.
- Added a name field to RawDataSource, which is being used to properly support attachment filenames.
- Reorganized and significantly improved vCard (contact) support in the new ContactHandler class.
- Updated and added many vCard fields, including additional contact devices and X509 certificates.
- Improved documentation and misc. minor fixes.
in version 1.3.0:
- Fixed backward compatibility with JDK 1.3.1.
- Added TNEFUtils.replace() method, which is used instead of String.replaceAll().
- Fixed PR_ATTACH_DATA_OBJ properties to provide the content data without the leading GUID.
- Fixed robustness of reading from streams, using read loop instead of single read.
- Added TNEFUTils.calculateChecksum() overloads that accept a partial byte array or a RawInputStream.
- Improved TNEFInputStream.readAttr() to reuse RawInputStream and avoid reading data into memory.
- Added RawInputStream.readFully() method, and modified RawInputStream to use it internally.
- Added RawInputStream.readXXX() methods for the primitive TNEF types.
- Added MAPIValue.getRawData().
- Changed ByteArrayInputStream returned by MAPIValue.getValue() with PT_OBJECT to RawInputStream.
- Changed internal MAPIValue data to be stored as RawInputStream.
- Added constructors to all objects that parse from a RawInputStream.
- Improved TNEF.main to catch Throwable rather than Exception.
- Modified a RawInputStream constructor contract - it now starts at current position of given RawInputStream.
- Removed byte array constructors.
- Fixed RawInputStream.available(), which is now used internally.
- Modified everything for minimal memory use, by using RawInputStream everywhere.
- Fixed parsing of PT_SHORT type properties.
- Fixed parsing of PT_CLSID type properties.
- Added URL (PR_BUSINESS_HOME_PAGE) to vCard.
- Added common CDO PropSetId GUID constants to MAPIProp for convenient use with MAPIPropNames.
- Added TNEFUtils.toGUID() convenience method to convert a GUID string to a GUID byte array.
- Added overloaded MAPIProp.findProp(), getProp() and getPropValue() methods that work with MAPIPropNames.
- Added MAPIPropName.equals() method.
- Fixed vCard conversion of email field, using the CDO named property.
- Reorganized contact to vCard conversion code.
- Fixed escaped character handling in vCard conversion.
- Updated to vCard version 3.0.
- Added TNEFUtils.calculateCRC32() method and its use in decompressRTF().
- Added BufferedInputStream wrapping for files in RawInputStream.
- Fixed up the javadocs.
in version 1.2.3:
- Added getMAPIProps convenience method to Message.
- Changed atpWord attributes (attMessageClass) to return a string value.
- Added experimental vCard (IPM.Contact) processing in TNEFMime.
- Added RTF bodypart to converted message in TNEFMime if PR_RTF_COMPRESSED property exists.
- Updated Attachment.getFilename javadoc to explicitly mention that filename may be null.
- Added VCARD (IPM.Contact) support in TNEFMime.
- Added text/rtf bodypart when PR_RTF_COMPRESSED property exists in TNEFMime.
- Fixed TNEFMime handling when attachment has no filename.
- Added jtnef.checksum.ignore system property to ignore invalid checksums.
- Added TNEFInputStream.setChecksumIgnore method to ignore invalid checksums.
in version 1.2.2:
- Fixed casting bug in TNEFMime.
- Fixed overwriting of text of inner rfc822 message in TNEFMime.
- Added getPropValue convenience method in MAPIProps.
- Added finalizer in RawInputStream to close the underlying resources when no longer used.
- Added utility method in TNEFUtils to check if a mime type is TNEF (includes application/vnd.ms-tnef).
- Fixed Attachment.writeTo method to use a copy of the stream and leave the main stream untouched.
- Fixed Attachment.writeTo when an attachment has no content.
- Optimized Attachment.writeTo by using a buffer.
- Fixed up the javadocs.
in version 1.2.1:
- Added TNEFUtils.decompressRTF method which can decompress PR_RTF_COMPRESSED properties.
- TNEFInputStream now uses RawInputStream internally to reduce memory footprint.
- Fixed TNEFInputStream when used with file-based constructors (using RawInputStream).
- Fixed TNEFUtils bytes-to-unsigned methods to be truly unsigned.
in version 1.2:
- Added getAttribute(int ID) methods to Message and Attachment for easier access to attributes.
- Attributes of type atpDate are now always in GMT and with 0 milliseconds.
- Fixed attRecipTable attributes with multiple recipients.
- Fixed the MAPIProps unused constructor.
- Added GUID to MAPIPropName display.
- Added MAPIProps container for easier access to property collections.
- Changed MAPIValue.getValue() return object types to better reflect the MAPI types:
- PT_INT -> Integer
- PT_ERROR -> Integer
- PT_BOOLEAN -> Boolean
- PT_FLOAT -> Float
- PT_DOUBLE -> Double
- Fixed RawInputStream.toByteArray() to work properly when the raw source is a byte array.
- Fixed RawInputStream.newStream() to return proper length for -1 parameter.
- Added TNEFUtils.getU64() method.
- Changed non-Unicode string decoding to use "ISO8859-1" encoding (see TNEFUtils.createString() JavaDoc). This allows the original bytes to be reconstructed.
in version 1.1:
- TNEFMime command line now takes an options parameter.
- TNEFMime command line supports option to extract a TNEF attachment from a MIME file.
- Added getKey() method to TNEFInputStream to retrieve stream key.
- Fixed handling of named properties of type MNID_STRING.
- Fixed handling of properties of type PT_NULL.
- Fixed Unicode support for properties of type PT_UNICODE_STRING.
- Fixed handling of some multivalued properties (MV_FLAG).
- Added toString() methods to Address, TRPAddress and RawInputStream for friendlier display.
- Limited hex dump length for long binary fields.
- Changed non-Unicode string decoding to use "Cp1252" encoding (see TNEFUtils.createString() JavaDoc).
in version 1.0:
- This is the first release of the Java TNEF package.
License
The JTNEF Package is provided under the
GNU General Public License agreement.
For non-GPL commercial licensing please contact the author.
Donate
If you appreciate this project or benefit from using it, please donate something back to support it.
Contact
you can contact the author via e-mail at:
support@freeutils.net
Please write in to report bugs, problems, suggestions, ideas, questions, answers, source code queries and especially just to let me know you've found JTNEF Package useful. Getting feedback will encourage me to continue development and add some advanced features I have in mind...
For updates and additional information, you can always visit the website at
http://www.freeutils.net