org.apache.poi.hsmf

Class MAPIMessage

java.lang.Object

org.apache.poi.POIDocument

org.apache.poi.POIReadOnlyDocument

org.apache.poi.hsmf.MAPIMessage

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class MAPIMessage
extends POIReadOnlyDocument

Reads an Outlook MSG File in and provides hooks into its data structure. If you want to develop with HSMF, you might find it worth getting some of the Microsoft public documentation, such as: [MS-OXCMSG]: Message and Attachment Object Protocol Specification

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MAPIMessage.MESSAGE_CLASS A MAPI file can be an email (NOTE) or a number of other types

Constructor Summary

Constructors

Constructor and Description
MAPIMessage() Constructor for creating new files.
MAPIMessage(DirectoryNode poifsDir) Constructor for reading MSG Files from a certain point within a POIFS filesystem
MAPIMessage(java.io.File file) Constructor for reading MSG Files from the file system.
MAPIMessage(java.io.InputStream in) Constructor for reading MSG Files from an input stream.
MAPIMessage(POIFSFileSystem fs) Constructor for reading MSG Files from a POIFS filesystem
MAPIMessage(java.lang.String filename) Constructor for reading MSG Files from the file system.

Method Summary

Modifier and Type	Method and Description
AttachmentChunks[]	getAttachmentFiles() Gets the message attachments.
java.lang.String	getConversationTopic() Gets the conversation topic of the parsed Outlook Message.
java.lang.String	getDisplayBCC() Gets the display value of the "BCC" line of the outlook message.
java.lang.String	getDisplayCC() Gets the display value of the "CC" line of the outlook message.
java.lang.String	getDisplayFrom() Gets the display value of the "FROM" line of the outlook message This is not the actual address that was sent from but the formated display of the user name.
java.lang.String	getDisplayTo() Gets the display value of the "TO" line of the outlook message.
java.lang.String[]	getHeaders() Returns all the headers, one entry per line
java.lang.String	getHtmlBody() Gets the html body of this Outlook Message, if this email contains a html version.
Chunks	getMainChunks() Gets the main, core details chunks
MAPIMessage.MESSAGE_CLASS	getMessageClassEnum() Gets the message class of the parsed Outlook Message.
java.util.Calendar	getMessageDate() Gets the date that the message was accepted by the server on.
NameIdChunks	getNameIdChunks() Gets the Name ID chunks, or null if there aren't any
RecipientChunks[]	getRecipientDetailsChunks() Gets all the recipient details chunks.
java.lang.String	getRecipientEmailAddress() Returns all the recipients' email address, separated by semicolons.
java.lang.String[]	getRecipientEmailAddressList() Returns an array of all the recipient's email address, normally in TO then CC then BCC order.
java.lang.String	getRecipientNames() Returns all the recipients' names, separated by semicolons.
java.lang.String[]	getRecipientNamesList() Returns an array of all the recipient's names, normally in TO then CC then BCC order.
java.lang.String	getRtfBody() Gets the RTF Rich Message body of this Outlook Message, if this email contains a RTF (rich) version.
java.lang.String	getStringFromChunk(StringChunk chunk) Gets a string value based on the passed chunk.
java.lang.String	getSubject() Gets the subject line of the Outlook Message
java.lang.String	getTextBody() Gets the plain text body of this Outlook Message
void	guess7BitEncoding() Tries to identify the correct encoding for 7-bit (non-unicode) strings in the file.
boolean	has7BitEncodingStrings() Does this file contain any strings that are stored as 7 bit rather than unicode?
boolean	isReturnNullOnMissingChunk() Will you get a null on a missing chunk, or a ChunkNotFoundException (default is the exception).
void	set7BitEncoding(java.lang.String charset) Many messages store their strings as unicode, which is nice and easy.
void	set7BitEncoding(java.lang.String generalcharset, java.lang.String htmlbodycharset, java.lang.String bodycharset)
void	setReturnNullOnMissingChunk(boolean returnNullOnMissingChunk) Sets whether on asking for a missing chunk, you get back null or a ChunkNotFoundException (default is the exception).

Methods inherited from class org.apache.poi.POIReadOnlyDocument

write, write, write

Methods inherited from class org.apache.poi.POIDocument

clearDirectory, close, createInformationProperties, getDirectory, getDocumentSummaryInformation, getEncryptedPropertyStreamName, getEncryptionInfo, getPropertySet, getPropertySet, getSummaryInformation, initDirectory, readProperties, replaceDirectory, validateInPlaceWritePossible, writeProperties, writeProperties, writeProperties

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MAPIMessage

public MAPIMessage()

Constructor for creating new files.

MAPIMessage

public MAPIMessage(java.lang.String filename)
            throws java.io.IOException

Constructor for reading MSG Files from the file system.

Parameters:

filename - Name of the file to read

Throws:

java.io.IOException - on errors reading, or invalid data

MAPIMessage

public MAPIMessage(java.io.File file)
            throws java.io.IOException

Constructor for reading MSG Files from the file system.

Parameters:

file - The file to read from

Throws:

java.io.IOException - on errors reading, or invalid data

MAPIMessage

public MAPIMessage(java.io.InputStream in)
            throws java.io.IOException

Constructor for reading MSG Files from an input stream.

Note - this will buffer the whole message into memory in order to process. For lower memory use, use MAPIMessage(File)

Parameters:

in - The InputStream to buffer then read from

Throws:

java.io.IOException - on errors reading, or invalid data

MAPIMessage

public MAPIMessage(POIFSFileSystem fs)
            throws java.io.IOException

Constructor for reading MSG Files from a POIFS filesystem

Parameters:

fs - Open POIFS FileSystem containing the message

Throws:

java.io.IOException - on errors reading, or invalid data

MAPIMessage

public MAPIMessage(DirectoryNode poifsDir)
            throws java.io.IOException

Constructor for reading MSG Files from a certain point within a POIFS filesystem

Parameters:

poifsDir - Directory containing the message

Throws:

java.io.IOException - on errors reading, or invalid data

Method Detail

getStringFromChunk

public java.lang.String getStringFromChunk(StringChunk chunk)
                                    throws ChunkNotFoundException

Gets a string value based on the passed chunk.

Throws:

ChunkNotFoundException - if the chunk isn't there

getTextBody

public java.lang.String getTextBody()
                             throws ChunkNotFoundException

Gets the plain text body of this Outlook Message

Returns:

The string representation of the 'text' version of the body, if available.

Throws:

ChunkNotFoundException - If the text-body chunk does not exist and returnNullOnMissingChunk is set

getHtmlBody

public java.lang.String getHtmlBody()
                             throws ChunkNotFoundException

Gets the html body of this Outlook Message, if this email contains a html version.

Returns:

The string representation of the 'html' version of the body, if available.

Throws:

ChunkNotFoundException - If the html-body chunk does not exist and returnNullOnMissingChunk is set

getRtfBody

public java.lang.String getRtfBody()
                            throws ChunkNotFoundException

Gets the RTF Rich Message body of this Outlook Message, if this email contains a RTF (rich) version.

Returns:

The string representation of the 'RTF' version of the body, if available.

Throws:

ChunkNotFoundException - If the rtf-body chunk does not exist and returnNullOnMissingChunk is set

getSubject

public java.lang.String getSubject()
                            throws ChunkNotFoundException

Gets the subject line of the Outlook Message

Throws:

ChunkNotFoundException - If the subject-chunk does not exist and returnNullOnMissingChunk is set

getDisplayFrom

public java.lang.String getDisplayFrom()
                                throws ChunkNotFoundException

Gets the display value of the "FROM" line of the outlook message This is not the actual address that was sent from but the formated display of the user name.

Throws:

ChunkNotFoundException - If the from-chunk does not exist and returnNullOnMissingChunk is set

getDisplayTo

public java.lang.String getDisplayTo()
                              throws ChunkNotFoundException

Gets the display value of the "TO" line of the outlook message. If there are multiple recipients, they will be separated by semicolons. This is not the actual list of addresses/values that will be sent to if you click Reply in the email - those are stored in RecipientChunks.

Throws:

ChunkNotFoundException - If the to-chunk does not exist and returnNullOnMissingChunk is set

getDisplayCC

public java.lang.String getDisplayCC()
                              throws ChunkNotFoundException

Gets the display value of the "CC" line of the outlook message. If there are multiple recipients, they will be separated by semicolons. This is not the actual list of addresses/values that will be sent to if you click Reply in the email - those are stored in RecipientChunks.

Throws:

ChunkNotFoundException - If the cc-chunk does not exist and returnNullOnMissingChunk is set

getDisplayBCC

public java.lang.String getDisplayBCC()
                               throws ChunkNotFoundException

Gets the display value of the "BCC" line of the outlook message. If there are multiple recipients, they will be separated by semicolons. This is not the actual list of addresses/values that will be sent to if you click Reply in the email - those are stored in RecipientChunks. This will only be present in sent emails, not received ones!

Throws:

ChunkNotFoundException - If the bcc-chunk does not exist and returnNullOnMissingChunk is set

getRecipientEmailAddress

public java.lang.String getRecipientEmailAddress()
                                          throws ChunkNotFoundException

Returns all the recipients' email address, separated by semicolons. Checks all the likely chunks in search of the addresses.

Throws:

ChunkNotFoundException

getRecipientEmailAddressList

public java.lang.String[] getRecipientEmailAddressList()
                                                throws ChunkNotFoundException

Returns an array of all the recipient's email address, normally in TO then CC then BCC order. Checks all the likely chunks in search of the addresses.

Throws:

ChunkNotFoundException

getRecipientNames

public java.lang.String getRecipientNames()
                                   throws ChunkNotFoundException

Returns all the recipients' names, separated by semicolons. Checks all the likely chunks in search of the names. See also getDisplayTo(), getDisplayCC() and getDisplayBCC().

Throws:

ChunkNotFoundException

getRecipientNamesList

public java.lang.String[] getRecipientNamesList()
                                         throws ChunkNotFoundException

Returns an array of all the recipient's names, normally in TO then CC then BCC order. Checks all the likely chunks in search of the names. See also getDisplayTo(), getDisplayCC() and getDisplayBCC().

Throws:

ChunkNotFoundException

guess7BitEncoding

public void guess7BitEncoding()

Tries to identify the correct encoding for 7-bit (non-unicode) strings in the file.

Many messages store their strings as unicode, which is nice and easy. Some use one-byte encodings for their strings, but don't always store the encoding anywhere helpful in the file.

This method checks for codepage properties, and failing that looks at the headers for the message, and uses these to guess the correct encoding for your file.

Bug #49441 has more on why this is needed

set7BitEncoding

public void set7BitEncoding(java.lang.String charset)

Many messages store their strings as unicode, which is nice and easy. Some use one-byte encodings for their strings, but don't easily store the encoding anywhere in the file! If you know what the encoding is of your file, you can use this method to set the 7 bit encoding for all the non unicode strings in the file.

See Also:

guess7BitEncoding()

set7BitEncoding

public void set7BitEncoding(java.lang.String generalcharset,
                            java.lang.String htmlbodycharset,
                            java.lang.String bodycharset)

has7BitEncodingStrings

public boolean has7BitEncodingStrings()

Does this file contain any strings that are stored as 7 bit rather than unicode?

getHeaders

public java.lang.String[] getHeaders()
                              throws ChunkNotFoundException

Returns all the headers, one entry per line

Throws:

ChunkNotFoundException

getConversationTopic

public java.lang.String getConversationTopic()
                                      throws ChunkNotFoundException

Gets the conversation topic of the parsed Outlook Message. This is the part of the subject line that is after the RE: and FWD:

Throws:

ChunkNotFoundException - If the conversation-topic chunk does not exist and returnNullOnMissingChunk is set

getMessageClassEnum

public MAPIMessage.MESSAGE_CLASS getMessageClassEnum()
                                              throws ChunkNotFoundException

Gets the message class of the parsed Outlook Message. (Yes, you can use this to determine if a message is a calendar item, note, or actual outlook Message) For emails the class will be IPM.Note

Throws:

ChunkNotFoundException - If the message-class chunk does not exist and returnNullOnMissingChunk is set

getMessageDate

public java.util.Calendar getMessageDate()
                                  throws ChunkNotFoundException

Gets the date that the message was accepted by the server on.

Throws:

ChunkNotFoundException

getMainChunks

public Chunks getMainChunks()

Gets the main, core details chunks

getRecipientDetailsChunks

public RecipientChunks[] getRecipientDetailsChunks()

Gets all the recipient details chunks. These will normally be in the order of: * TO recipients, in the order returned by getDisplayTo() * CC recipients, in the order returned by getDisplayCC() * BCC recipients, in the order returned by getDisplayBCC()

getNameIdChunks

public NameIdChunks getNameIdChunks()

Gets the Name ID chunks, or null if there aren't any

getAttachmentFiles

public AttachmentChunks[] getAttachmentFiles()

Gets the message attachments.

isReturnNullOnMissingChunk

public boolean isReturnNullOnMissingChunk()

Will you get a null on a missing chunk, or a ChunkNotFoundException (default is the exception).

setReturnNullOnMissingChunk

public void setReturnNullOnMissingChunk(boolean returnNullOnMissingChunk)

Sets whether on asking for a missing chunk, you get back null or a ChunkNotFoundException (default is the exception).