LS-TNEF 
Lifestreams TNEF Decoder API
Written by Priyantha Jayanetti
(c) 1999-2000 Mirror Worlds Technologies
http://wwww.mirrorworlds.com
-----------------------------------------

Name        : LSTNEF
Version     : EA 1 (Early Access 1)
Date        : Feb 22, 2000.
Platforms   : Tested on Windows 98, NT 4.0
JDK         : Java2 (1.2.2)
JAR         : lstnef.jar 

1. License Agreement
--------------------
Please read license.txt file given with this distribution.


2. Description
--------------
This Java API allows one to decode TNEF (Transport Neutral Encoding Format) streams into 
individual files. Typically, the TNEF files are sent as email attachment with the
MIME content type of 'application/ms-tnef'. The TNEF attachment's default filename is
winmail.dat. See http://www.microsoft.com for more information regarding the TNEF 
format. (search for "Transport Neutral Encoding Format").

The LS-TNEF API allows one to decode the wimail.dat file from the command line, via
the API or by using Sun's Java Mail API. 

The LS-TNEF api is work in progress and this release is meant to be the first early 
access release.

3. Command Line Usage
---------------------

usage: com.mirrorworlds.lifestreams.mail.tnef.JTnef [xv] winmail.dat [outputdir]

     v generates verbose output to the stdout.
     x extracts the attachments to the current directory.
     outputdir specifies a extract destination directory.

example:
  com.mirrorworlds.lifestreams.mail.tnef.JTnef v winmail.dat
    prints the contents of the winmail file.

  com.mirrorworlds.lifestreams.mail.tnef.JTnef xv winmail.dat
    extracts(and prints) the contents of the winmail.dat to current directory.

  com.mirrorworlds.lifestreams.mail.tnef.JTnef xv winmail.dat c:\temp
    extracts(and prints) the contents of the winmail.dat to directory c:\temp.


4. API Usage
------------
Please see the accompaning JavaDocs for more information on specific classes.

The following code snippet requires you to import the packages
com.mirrorworlds.lifestreams.mail.tnef.*;
java.io.*;

       try {
          String filename = "winmail.dat";
          //create message object using default parser and builder.
          TnefMessage msg = JTnef.createTnefMessage(filename);          
          msg.printInfo(); // print debug info
          int count = msg.getCount();   // get number of attachments.   
           for (int i = 0; i < count; i++) { // loop thru attachments and print
              TnefAttachment a = msg.getAttachmentAt(i);
               System.out.println("   -- ");
               a.printInfo();
               // content-type of attachment is a.getContentType();
               // filename of attachment is a.getFilename();
               // attachment stream is a.getInputStream();
               // you can save attachment:
               //      File f = new File(a.getFilename);
               //      FileOutputStream fos = new FileOutputStream(f);      
               //      a.writeTo(f); // save attachment.
           }
       }catch(Exception e) {
           e.printStackTrace
       } 

If you want to, you could specify a TNEF stream parser and builder.

       //get parser - this class parses the tnef byte streams
       TnefStreamParser = new TnefStreamParserImpl();

       // get the builder. The parser will call methods in the builder when 
       // the parser encounters tnef tokens, attributes, data etc. The builder
       // will take this information to build a TnefMessage class.
       TnefBuilder builder = new TnefMessageBuilder();

       //associate the builder with the parser.
       parser.setBuilder(builder);
       
       //get content-type manager (maps file extensions to MIME content-types)
       TnefContentType contentTypes = new DefaultContentTypeImpl(); 
       
       //associate the content-types with the builder.
       builder.setContentTypes(contentTypes);
       
       // begin parsing.
       parser.parse(tnefStream);        
       // and finaly grab the message.
       TnefMessage msg =  builder.getMessage();




5. Java MAIL API Usage
----------------------
Please see the accompaning JavaDocs for more information on specific classes.  Note
that the lstnef api to integrate with the Java Mail API is still at a very
early stage.

The following code snippet requires you to import the packages (including Java Mail
and Java Activation Framwork API).

com.mirrorworlds.lifestreams.mail.tnef.*;
com.mirrorworlds.lifestreams.mail.tnef.intenet.*;
java.io.*;
javax.mail.*;
javax.mail.internet.*;
javax.activation.*;

  // assume you have Java Mail API MultiPart object that has text/plain message
  // as well as an application/ms-tnef attachment (bodypart).
  // The solution (hack alert!) described here basically removes this bodypart from the
  // multipart, then obtains the tnef attachments from this application/ms-tnef
  // bodypart and adds these attachments back into the original multipart object.

  // (ideally, all of these should be transparent to the Java Mail API user,
  //  probably by associating a DataContentHandler etc. for the tnef content-type).
  // (i.e. use the J.A.F).

  // mp is of type Multipart that has the application/ms-tnef attachment.
  // loop thru and get the tnef part.
  int size = mp.getCount();
  for (int i = 0; i < size; i++) {
      BodyPart bp = mp.getBodyPart(i);
      // ct is content-type of the body part.
      String ct = bp.getContentType();
      //if this is a tnef, then process it.
       if (ct.indexOf("application/ms-tnef") != -1) {
           // create tnef data source.
           TnefMultipartDataSource tnefDS = new TnefMultipartDataSource((MimePart)bp);
           // create Tnef multipart
           MimeMultipart tnefMP = new TnefMultipart(tnefDS);
           // get num of tnef attachments
           int partCount = tnefMP.getCount();
           // loop thru and add the attachment into the original multipart.
           for (int k = 0; k < partCount; k++) {
               BodyPart tnefBodyPart = tnefMP.getBodyPart(k);
               mp.addBodyPart(tnefBodyPart);                    
           }
           //remove the original application/ms-tnef part.
           mp.removeBodyPart(bp);
           bp = null;
           break;
       }// if
  }//for           


6. Adding your own extension/content-type entries
-------------------------------------------------
The DefaultContentTypeImpl class comes with 72 content-type entries. If you want, 
you could expand this collection by adding your own type via addType(ext,type) method
or by loading the type from file via load(inputstream, clear) method. If you are loading
from file, then the format of the file should be:

# This is a comment
# Format: file-extension <space> mime-type
jpg image/jpeg
tif image/tiff

If you want to the contents from the command line by

   java com.mirrorworlds.lifestreams.mail.tnef.DefaultContentTypeImpl mimetypes.txt

This saves the preconfigured entries to the file named mimetypes.txt

If you alread have some sort of a mime-type/file-extension manager or registry class,
then you could simply write a class that implements the TnefContentTypes interface.
(proxy). For example:

 public class MyTypeImpl implements TnefContentTypes {
	private CustomTypeManager ct;

	public MyTypeImpl() {
	   ct = new CustomTypeManager();
        }
	public String getContentTypeFromExtension(String ext) {
	   return ct.getContentTypeFromExtension(ext);
        }

	public String getContentTypeFromFilename(String filename) {
	   return ct.getContentTypeFromFilename(filename);
        }
 }


7. Extending the API
--------------------
You can
 (a) write your own parser (which implements the TnefStreamParser interface) and
     plug it in.
 (b) write your own buider which implements the TnefBuilder interface or extends 
     TnefMessageBuilder implementation.

