Open topic with navigation

# Extract Subfiles from Outlook Personal Folders Files

KeyView can extract Outlook items such as messages, appointments, contacts, tasks, notes, and journal entries from a PST file. When a PST file is extracted to disk, the text and header information (`To`, `From`, `Sent`, and so on) from each Outlook item is extracted to a text file. (If you do not want the header information to appear in the text file, see Exclude Metadata from the Extracted Text File.)

You can also extract messages from PST files as MSG files, including all their attachments, by setting the `KVExtractionFlag_SaveAsMSG` flag in the KVExtractSubFileArg structure when you call `fpExtractSubFile()`.

If an Outlook item contains a non-mail attachment, the attachment is extracted in its native format to a subdirectory. If an Outlook item contains an Outlook attachment, the attached item’s text and any attachments are extracted to a subdirectory.

NOTE: The Microsoft Outlook Personal Folders (PST) reader is an advanced feature and is sold and licensed separately. To enable this reader in a KeyView SDK, you must obtain the appropriate license key from Micro Focus. See Update License Information for information on adding a new license key to an existing installation.

## Use the Native or MAPI-based Reader

KeyView accesses PST files in one of two ways:

- indirectly using the Microsoft Messaging Application Programming Interface (MAPI) reader named `pstsr`.

- directly using the native PST reader named `pstnsr`.

On UNIX platforms, the native reader is always used to process PST files because the MAPI-based reader only runs on Windows x86 and x64. On Windows, you can specify either reader; however, the MAPI-based reader is used by default.

The differences between the two readers are summarized in the following table:

Feature/Requirement | Native Reader (pstnsr) | MAPI-based Reader (pstsr)
--- | --- | ---
All platforms supported | Yes | Windows x86 and x64 only
Outlook client required | No | Yes
MAPI properties supported | Yes All properties defined in `mapitags.h`. Object properties are not supported. | Yes All properties defined in `mapitags.h`. Object properties are not supported.
Password protection supported | Yes | Yes (using `KVCredential` structure)
Compressible encryption supported | Yes | Yes
High encryption supported | No | Yes

To use the MAPI-based reader for PST files, change the PST entry in the `formats``_e``.ini` file as follows:

    297=pst

To use the native reader for PST files, change the PST entry in the `formats``_e``.ini` file as follows:

    297=pstn

NOTE: You must make sure that the PST that you are extracting is not open in the Outlook client, and that the Outlook process is not running.

### Use the Native PST Reader (pstnsr)

The native PST reader accesses PST files directly without relying on the Microsoft interface to the PST format. It runs on both Windows and UNIX, and does not require an Outlook client on the system processing the PST files. However, the native reader does not support password-protected PST files that use high encryption.

### Use the MAPI Reader (pstsr)

The `pstsr` reader accesses PST files indirectly by using Microsoft’s Messaging Application Programming Interface (MAPI). MAPI is a standard Windows message interface that enables different mail programs and other mail-aware applications (such as word processors and spreadsheets) to exchange messages and attachments with each other. MAPI allows KeyView to open a PST file, traverse the folders and Outlook items, and extract the items inside the PST file.

NOTE: When extracting subfiles from PST files, information on the distribution list used in an email is extracted to a file called `emailname``.dist`. This applies to the MAPI reader (`pstsr`) only.

#### System Requirements

Because MAPI is supported on Windows platforms only, you can convert PST files on Windows only. Because MAPI relies on functionality in Microsoft Outlook, a Microsoft Outlook client must be installed on the same machine as the application converting PST files, and must be the default email application. KeyView supports the following PST formats and Outlook clients:

- Outlook 97 or higher PST files

- Outlook 2002 or later clients

  NOTE: The Outlook client must be the same version as, or newer than, the version of Outlook that generated the PST file.

NOTE: The bit edition of Microsoft Outlook must match that of the KeyView software. For example, if 32-bit KeyView is used, 32-bit Outlook must be installed. If 64-bit KeyView is used, 64-bit Outlook must be installed.
If the bit editions do not match, an error message from Microsoft Office Outlook is displayed:
`Either there is a no default mail client or the current mail client cannot fulfill the messaging request. Please run Microsoft Outlook and set it as the default mail client.`
Additionally, KeyView displays the following return code:
`Error 32: KVError_PSTAccessFailed.`

## MAPI Attachment Methods

The way in which you can access the contents of a PST message attachment is determined by the MAPI attachment method applied to the attachment. For example, if the attachment is an embedded OLE object, it uses the `ATTACH_OLE` attachment method. KeyView can access message attachments that use the following attachment methods:

    ATTACH_BY_VALUE

    ATTACH_EMBEDDED_MSG

    ATTACH_OLE

    ATTACH_BY_REFERENCE

    ATTACH_BY_REF_ONLY

    ATTACH_BY_REF_RESOLVE

Attachments using the `ATTACH_BY_VALUE`, `ATTACH_EMBEDDED_MSG`, or `ATTACH_OLE` attachment methods are extracted automatically when the PST file is extracted. An "attach by reference" method means that the attachment is not in Outlook, but Outlook contains an absolute path to the attachment. Before you can extract these types of attachments, you must retrieve the path to access the attachment.

To extract "attach by reference" attachments

Determine whether the attachment uses an `ATTACH_BY_REFERENCE`, `ATTACH_BY_REF_ONLY`, or `ATTACH_BY_REF_RESOLVE` method by retrieving the MAPI property `PR_ATTACH_METHOD`.

If the attachment uses one of the "attach by reference" methods, get the fully qualified path to the attachment by retrieving the MAPI properties `PR_ATTACH_LONG_PATHNAME` or `PR_ATTACH_PATHNAME`.

You can then either copy the files from their original location to the path where the PST file is extracted, or use the Export API functions to convert the attachment.

## Open Secured PST Files

KeyView enables you to specify a user name and password to use to open a secured PST file for extraction.

NOTE: To open password-protected PST files that use high encryption, you must use the MAPI-based PST reader (`pstsr`).
The native PST reader (`pstnsr`) returns the error message `KVERR_PasswordProtected` if a PST is encrypted with high encryption.

## Detect PST Files While the Outlook Client is Running

If you are running an Outlook client while running the File Extraction API, the KeyView format detection module (`kwad`) might not be able to open the PST file to determine the file’s format because Outlook has the file locked. In this case, you can do one of the following:

- Close Outlook when using the Extraction API.

- Detect PST files by extension only and bypass the format detection module. To enable this option, add the following lines to the `formats``_e``.ini` file:

      [container_flags]
      detectPSTbyExtension=1

  NOTE: The `detectPSTbyExtension` option applies only when you are using the MAPI reader (`pstsr`).
  NOTE: If you use this option, you must make sure in your code that valid PST files are passed to KeyView, because the format detection module is not available to verify the file type and pass the file to the appropriate reader.

© 2006-2018 EntIT Software LLC, a Micro Focus company | Send documentation feedback to Micro Focus Close Send documentation feedback To open the configured email client on this computer, open an email window. Otherwise, copy the information below to a web mail client, and send this email to swpdl.idoldocsfeedback@microfocus.com. We appreciate your feedback! Product: Topic Title: Help Topic: Feedback:

_FT_HTML5_bannerTitle.htm