public class PersonalStorage extends Object implements IDisposable, Closeable
Represents Personal Storage Table (.pst) file.
Modifier and Type | Field and Description |
---|---|
Event<ItemMovedEventHandler> |
ItemMoved
Occurs when an item is moved to the another folder.
|
Event<StorageProcessedEventHandler> |
StorageProcessed
Occurs in splitting and merging operations when a new chunk of pst
is created or the next file is processed and is to be merged.
|
Constructor and Description |
---|
PersonalStorage(TraversalExceptionsCallback callback)
Initializes a new instance of the
PersonalStorage class. |
Modifier and Type | Method and Description |
---|---|
boolean |
canWrite()
Gets a value indicating whether
the current pst supports writing.
|
void |
changeMessage(String entryId,
MapiPropertyCollection updatedProperties)
Changes the message properties.
|
void |
close() |
void |
convertTo(int format)
Converts the current object to the specified format.
|
static PersonalStorage |
create(OutputStream stream,
int version)
Creates the PST in a stream.
|
static PersonalStorage |
create(OutputStream stream,
int version,
boolean leaveStreamOpen)
Creates the PST in a stream.
|
static PersonalStorage |
create(OutputStream stream,
int blockSize,
int version)
Creates the PST in a stream.
|
static PersonalStorage |
create(Stream stream,
int version)
Creates the PST in a stream.
|
static PersonalStorage |
create(Stream stream,
int version,
boolean leaveStreamOpen)
Creates the PST in a stream.
|
static PersonalStorage |
create(String fileName,
int version)
Creates the new PST file with the specified file name.
|
FolderInfo |
createPredefinedFolder(String name,
int defaultFolder)
Creates the standard interpersonal message (IPM) folder.
|
FolderInfo |
createPredefinedFolder(String name,
int defaultFolder,
boolean createHierarchy)
Creates the standard interpersonal message (IPM) folder.
|
void |
dispose()
Performs application-defined tasks associated with freeing,
releasing, or resetting unmanaged resources.
|
protected void |
dispose(boolean disposing)
Releases unmanaged and - optionally - managed resources.
|
IGenericEnumerable<MessageInfo> |
enumerateMessages(String entryId)
Exposes the enumerator, which supports an iteration of messages in folder.
|
IGenericEnumerable<MessageInfo> |
enumerateMessages(String entryId,
int startIndex,
int count)
Exposes the enumerator, which supports an iteration of messages in folder.
|
MapiAttachmentCollection |
extractAttachments(MessageInfo messageInfo)
Extracts the attachments.
|
MapiAttachmentCollection |
extractAttachments(String entryId)
Extracts the attachments.
|
MapiMessage |
extractMessage(byte[] entryId)
Get the message from PST.
|
MapiMessage |
extractMessage(MessageInfo messageInfo)
Get the message from PST.
|
MapiMessage |
extractMessage(String entryId)
Get the message from PST.
|
MapiProperty |
extractProperty(byte[] entryId,
long tag)
Gets the specified property of item, without extract the item fully.
|
IGenericList<String> |
findMessages(String parentEntryId)
Finds the identifiers of messages for for the current folder.
|
IGenericList<String> |
findSubfolders(String parentEntryId)
Finds the identifiers of subfolders for for the current folder.
|
static PersonalStorage |
fromFile(String fileName)
Load PST from file.
|
static PersonalStorage |
fromFile(String fileName,
boolean writable)
Load PST from file.
|
static PersonalStorage |
fromFile(String fileName,
PersonalStorageLoadOptions loadOptions)
Load PST from file.
|
static PersonalStorage |
fromStream(InputStream stream)
Load PST from stream.
|
static PersonalStorage |
fromStream(InputStream stream,
boolean writable)
Load PST from stream.
|
static PersonalStorage |
fromStream(InputStream stream,
PersonalStorageLoadOptions loadOptions)
Load PST from stream.
|
static PersonalStorage |
fromStream(Stream stream)
Load PST from stream.
|
static PersonalStorage |
fromStream(Stream stream,
boolean writable)
Load PST from stream.
|
static PersonalStorage |
fromStream(Stream stream,
PersonalStorageLoadOptions loadOptions)
Load PST from stream.
|
FolderInfo |
getFolderById(byte[] entryId)
Gets the personal folder from PST.
|
FolderInfo |
getFolderById(String entryIdString)
Gets the personal folder from PST.
|
int |
getFormat()
Gets the file format.
|
FolderInfo |
getParentFolder(byte[] entryId)
Gets the parent folder of message.
|
FolderInfo |
getParentFolder(String entryIdString)
Gets the parent folder of message.
|
FolderInfo |
getPredefinedFolder(int defaultFolder)
Gets the standard interpersonal message (IPM) folder from PST.
|
FolderInfo |
getRootFolder()
Gets the root folder of PST.
|
MessageStore |
getStore()
Gets the PST message store.
|
boolean |
isUnicode()
Gets a value indicating whether the PST file format is Unicode.
|
boolean |
load(InputStream stream)
Load PST from stream.
|
boolean |
load(Stream stream)
Load PST from stream.
|
boolean |
load(String fileName)
Load PST from file.
|
void |
mergeWith(InputStream[] sourceStreams)
Merges the pst storage with one or more other pst streams.
|
void |
mergeWith(String[] sourceFileNames)
Merges the pst storage with one or more other pst files.
|
void |
moveItem(FolderInfo folder,
FolderInfo newFolder)
Moves a specified folder to a new parent folder within the current pst.
|
void |
moveItem(MessageInfo message,
FolderInfo newFolder)
Moves a specified message to a new folder within the current pst.
|
void |
saveAs(OutputStream stream,
int format)
Saves the current object to a specified file format in a stream.
|
void |
saveAs(String fileName,
int format)
Saves the current object to a specified file format in a different file.
|
void |
saveMessageToFile(String entryId,
String fileName)
saveMessageToFile.
|
void |
saveMessageToStream(String entryId,
OutputStream stream)
Saves the message, with specified entryID, to a stream.
|
void |
splitInto(IGenericList<MailQuery> criteria,
String path)
Splits the pst storage based on criteria.
|
void |
splitInto(long chunkSize,
String path)
Splits the pst storage into less sized parts.
|
boolean |
tryToGetFolderById(String entryIdString,
FolderInfo[] folder)
Gets the folder associated with the specified entry ID.
|
SaveResult |
tryToSaveMessage(String entryId,
OutputStream stream)
Saves the message, with specified entryID, to a stream.
|
public final Event<ItemMovedEventHandler> ItemMoved
Occurs when an item is moved to the another folder.
public final Event<StorageProcessedEventHandler> StorageProcessed
Occurs in splitting and merging operations when a new chunk of pst is created or the next file is processed and is to be merged.
public PersonalStorage(TraversalExceptionsCallback callback)
Initializes a new instance of the PersonalStorage
class.
Allows setting a callback method for handling exceptions that occur during PST traversal.
callback
- The exception callback.public final FolderInfo getRootFolder()
Gets the root folder of PST.
Value:FolderInfo
that represents a root folder.public final MessageStore getStore()
Gets the PST message store.
Value: TheMessageStore
which
is the rough equivalent of the top of a Mailbox.public final int getFormat()
Gets the file format.
Value:FileFormat
that specifies file format.
public final boolean canWrite()
Gets a value indicating whether the current pst supports writing.
public final boolean isUnicode()
Gets a value indicating whether the PST file format is Unicode. There are two versions of the PST file format: Unicode and ANSI.
public static PersonalStorage fromFile(String fileName)
Load PST from file.
fileName
- Name of .pst file.
public static PersonalStorage fromFile(String fileName, boolean writable)
Load PST from file.
fileName
- Name of .pst file.writable
- if set to true
then the the pst file will support writing,
otherwise it will be opened in read-only mode.public static PersonalStorage fromFile(String fileName, PersonalStorageLoadOptions loadOptions)
Load PST from file.
fileName
- Name of .pst file.loadOptions
- The load options.ArgumentNullException
- fileName - File name can not be null or emptyArgumentException
- PersonalStorageLoadOptions.LeaveStreamOpen can not be true.public static PersonalStorage fromStream(InputStream stream, boolean writable)
Load PST from stream.
stream
- The System.IO.Stream.writable
- if set to true
then the the pst will support writing,
otherwise it will be opened in read-only mode.public static PersonalStorage fromStream(Stream stream, boolean writable)
Load PST from stream.
stream
- The System.IO.Stream.writable
- if set to true
then the the pst will support writing,
otherwise it will be opened in read-only mode.public final boolean load(String fileName)
Load PST from file. This method is used when a PersonalStorage object is created using the constructor.
fileName
- The name of .pst file.ArgumentNullException
- fileName - File name can not be null or emptypublic final boolean load(InputStream stream)
Load PST from stream. This method is used when a PersonalStorage object is created using the constructor.
stream
- The System.IO.Stream.public final boolean load(Stream stream)
Load PST from stream. This method is used when a PersonalStorage object is created using the constructor.
stream
- The System.IO.Stream.public static PersonalStorage fromStream(InputStream stream, PersonalStorageLoadOptions loadOptions)
Load PST from stream.
stream
- The System.IO.Stream.loadOptions
- The load options.public static PersonalStorage fromStream(Stream stream, PersonalStorageLoadOptions loadOptions)
Load PST from stream.
stream
- The System.IO.Stream.loadOptions
- The load options.public static PersonalStorage fromStream(InputStream stream)
Load PST from stream.
stream
- The System.IO.Stream.
public static PersonalStorage fromStream(Stream stream)
Load PST from stream.
stream
- The System.IO.Stream.
public static PersonalStorage create(String fileName, int version)
Creates the new PST file with the specified file name.
fileName
- The full name of the file.version
- The PST file version.
NotImplementedException
- throws if ANSI file version is createdArgumentNullException
- throws if file name is null or emptypublic static PersonalStorage create(Stream stream, int version)
Creates the PST in a stream.
stream
- The stream in which PST is created.version
- The PST file version.
NotImplementedException
- throws if ANSI file version is createdArgumentNullException
- throws if stream is nullpublic static PersonalStorage create(Stream stream, int version, boolean leaveStreamOpen)
Creates the PST in a stream.
stream
- The stream in which PST is created.version
- The PST file version.leaveStreamOpen
- Leave stream open when PersonalStorage is disposed.
NotImplementedException
- throws if ANSI file version is createdArgumentNullException
- throws if stream is nullpublic static PersonalStorage create(OutputStream stream, int version)
Creates the PST in a stream.
stream
- The stream in which PST is created.version
- The PST file version.
NotImplementedException
- throws if ANSI file version is createdArgumentNullException
- throws if stream is nullpublic static PersonalStorage create(OutputStream stream, int version, boolean leaveStreamOpen)
Creates the PST in a stream.
stream
- The stream in which PST is created.version
- The PST file version.leaveStreamOpen
- Leave stream open when PersonalStorage is disposed.
NotImplementedException
- throws if ANSI file version is createdArgumentNullException
- throws if stream is nullpublic static PersonalStorage create(OutputStream stream, int blockSize, int version)
Creates the PST in a stream.
stream
- The stream in which PST is created.blockSize
- The optimal block size to expand cache buffer(in bytes).version
- The PST file version.
NotImplementedException
- throws if ANSI file version is createdArgumentNullException
- throws if stream is nullpublic final void saveAs(String fileName, int format)
Saves the current object to a specified file format in a different file.
fileName
- The name of the file to be saved.format
- The FileFormat
is to be used when saving a file.public final void saveAs(OutputStream stream, int format)
Saves the current object to a specified file format in a stream.
stream
- The stream to be saved.format
- The FileFormat
is to be used.public final void convertTo(int format)
Converts the current object to the specified format.
format
- The FileFormat to convert the current object to.public final MapiProperty extractProperty(byte[] entryId, long tag)
Gets the specified property of item, without extract the item fully.
entryId
- The entry id of item.tag
- The property tag.
public final MapiMessage extractMessage(MessageInfo messageInfo)
Get the message from PST.
messageInfo
- A MessageInfo object that
represents information about message.public final MapiMessage extractMessage(byte[] entryId)
Get the message from PST.
entryId
- EntryId of message.public final MapiMessage extractMessage(String entryId)
Get the message from PST.
entryId
- String representation of EntryId.public final void saveMessageToStream(String entryId, OutputStream stream)
Saves the message, with specified entryID, to a stream.
entryId
- The entry id.stream
- The stream for writing.public final IGenericEnumerable<MessageInfo> enumerateMessages(String entryId)
Exposes the enumerator, which supports an iteration of messages in folder.
entryId
- The string that represents a parent folder entry ID.System.Collections.Generic.IEnumerableltTgt
,
that represents an enumerator that iterates through a messages in folder.public final IGenericEnumerable<MessageInfo> enumerateMessages(String entryId, int startIndex, int count)
Exposes the enumerator, which supports an iteration of messages in folder.
entryId
- The string that represents a parent folder entry ID.startIndex
- The start message index.count
- The number of messages that will be retrieved.System.Collections.Generic.IEnumerableltTgt
,
that represents an enumerator that iterates through a messages in folder.public final SaveResult tryToSaveMessage(String entryId, OutputStream stream)
Saves the message, with specified entryID, to a stream.
entryId
- The entry id.stream
- The stream for writing.SaveResult
that represents the result of item saving.public final MapiAttachmentCollection extractAttachments(MessageInfo messageInfo)
Extracts the attachments.
messageInfo
- The message information.MapiAttachmentCollection
that represents the collection of attachments.public final MapiAttachmentCollection extractAttachments(String entryId)
Extracts the attachments.
entryId
- The message entryId.MapiAttachmentCollection
that represents the collection of attachments.public final FolderInfo getFolderById(byte[] entryId)
Gets the personal folder from PST.
entryId
- The Entry id.public final boolean tryToGetFolderById(String entryIdString, FolderInfo[] folder)
Gets the folder associated with the specified entry ID.
entryIdString
- The string that represented the entry ID.folder
- When this method returns true, contains the FolderInfo
object associated with the specified ID.public final FolderInfo getFolderById(String entryIdString)
Gets the personal folder from PST.
entryIdString
- String representation of entry ID.public final IGenericList<String> findSubfolders(String parentEntryId)
Finds the identifiers of subfolders for for the current folder. It might be useful in case of reading corrupted pst when the GetSubfolders and EnumerateFolders methods could throw an exception.
parentEntryId
- Entry id of the parent folder.public final IGenericList<String> findMessages(String parentEntryId)
Finds the identifiers of messages for for the current folder. It might be useful in case of reading corrupted pst when the GetContents and EnumerateMessages methods could throw an exception.
parentEntryId
- Entry id of the parent folder.public final FolderInfo getParentFolder(String entryIdString)
Gets the parent folder of message.
entryIdString
- String representation of Entry Id of message or folder.FolderInfo
of message.public final FolderInfo getParentFolder(byte[] entryId)
Gets the parent folder of message.
entryId
- Entry Id of message or folder.FolderInfo
of message.public final FolderInfo getPredefinedFolder(int defaultFolder)
Gets the standard interpersonal message (IPM) folder from PST. Outlook can create a number of default folders, such as Outbox, Deleted Items, Sent Items etc.
defaultFolder
- The value of StandardIpmFolder
enumeration.FolderInfo
object that represents a standard IPM folder.public final FolderInfo createPredefinedFolder(String name, int defaultFolder, boolean createHierarchy)
Creates the standard interpersonal message (IPM) folder.
name
- The name of folder.defaultFolder
- The value of StandardIpmFolder
enumeration.createHierarchy
- if set to true
, it is possible to create a folder hierarchy using string notation.
Backslash ('\') is used as path separator.FolderInfo
object that represents a standard IPM folder.public final FolderInfo createPredefinedFolder(String name, int defaultFolder)
Creates the standard interpersonal message (IPM) folder.
name
- The name of folder.defaultFolder
- The value of StandardIpmFolder
enumeration.FolderInfo
object that represents a standard IPM folder.public final void moveItem(MessageInfo message, FolderInfo newFolder)
Moves a specified message to a new folder within the current pst.
message
- The message to move.newFolder
- The new folder for the message.public final void moveItem(FolderInfo folder, FolderInfo newFolder)
Moves a specified folder to a new parent folder within the current pst.
folder
- The folder to move.newFolder
- The new parent folder.public final void mergeWith(String[] sourceFileNames)
Merges the pst storage with one or more other pst files. Thus, the combined files are sources.
sourceFileNames
- The source file names.ArgumentNullException
- "Throws when the filename collection is null."ArgumentException
- "Throws when the filename in collection is null or empty."public final void mergeWith(InputStream[] sourceStreams)
Merges the pst storage with one or more other pst streams. Thus, the combined stream are sources.
sourceStreams
- The source streams.ArgumentNullException
- "Throws when the stream collection is null."ArgumentException
- "Throws when the stream in collection is null."public final void splitInto(long chunkSize, String path)
Splits the pst storage into less sized parts.
chunkSize
- The approximate size of a chunk in bytes.path
- The folder path where chunks will be created.ArgumentException
- Throws when the path parameter is null or empty.ArgumentException
- Throws when the chunk size is less then the minimum size of pst file.public final void splitInto(IGenericList<MailQuery> criteria, String path)
Splits the pst storage based on criteria.
criteria
- The collection of MailQuery
that represents criteria of pst splitting.path
- The folder path where chunks will be created.ArgumentException
- Throws when the path parameter is null or empty.public final void changeMessage(String entryId, MapiPropertyCollection updatedProperties)
Changes the message properties.
entryId
- The entry identifier of message.updatedProperties
- The updated properties.NotImplementedException
- The ANSI file version editing is not implemented.InvalidOperationException
- The PST is open for reading only.
or
The entryId is incorrect.ArgumentNullException
- entryIdCollection;The collection of entry ids cannot be null.
or
updatedProperties;The collection of properties cannot be null.public final void dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
dispose
in interface IDisposable
public void close()
close
in interface Closeable
close
in interface AutoCloseable
protected void dispose(boolean disposing)
Releases unmanaged and - optionally - managed resources.
disposing
- true
to release both managed
and unmanaged resources; false
to release only unmanaged resources.