# View Container Files

A container file has a main file (parent) and subfiles (children) embedded in the main file. The following are examples of container files:

- Compressed files such as ZIP, TAR, and RAR

- Mail messages such as Outlook (MSG) and Outlook Express (EML)

- Mail stores such as Microsoft Outlook Personal Folders (PST), Mailbox (MBX), and Lotus Notes database (NSF)

The subfiles might also be container files, creating a file hierarchy of multiple levels. For example, an MSG file (the root parent) might contain three attachments:

- a Microsoft Word document containing an embedded Microsoft Excel spreadsheet.

- an AutoCAD drawing file (DWG).

- an EML file with an attached ZIP file, which in turn contains four archived files.

Example Container File Tree Structure

NOTE: The parent MSG file contains four first-level children. The body text of a message file, although not a standalone file within the container, is considered a child of the parent file.

## Microsoft Outlook Personal Folders (PST) Files

NOTE: The Microsoft Outlook Personal Folders (PST) readers are an advanced feature and are sold and licensed separately. To enable these readers in a KeyView SDK, you must obtain an appropriate license key from Micro Focus. For information about adding a new license key to an existing installation, see Pass License Information to KeyView.

## Choose the Reader to use for PST Files

KeyView provides the following ways of processing PST files:

- Indirectly, using the Microsoft Messaging Application Programming Interface (MAPI). MAPI is a Microsoft interface that enables different applications to exchange messages and attachments with each other. MAPI allows KeyView to open a PST file, traverse the folders and extract items. The `pstsr` reader uses MAPI, but requires that Microsoft Outlook is installed.
- Directly, without relying on the Microsoft interface to the PST format. Accessing the file directly does not require Microsoft Outlook. The `pstxsr` reader uses this approach.

The MAPI-based reader is used by default but you can choose `pstxsr` if you prefer.

The differences between the readers are summarized in the following table.

Feature | Native Reader (pstxsr) | MAPI-based Reader (pstsr)
--- | --- | ---
Outlook required | No | Yes
MAPI properties 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 native reader for PST files, change the PST entry in either the registry file or the initialization file as follows:

In the `kvsdk.ini` file

1. Open the `kvsdk.ini` file with a text editor. The file is installed in the root of the Windows directory.

2. In the `[KVMAILVE]` section of the `kvsdk.ini` file, change the parameter `297=pstsr.dll` to `297=pstxsr.dll`.

In the registry file

1. Open `install.reg.txt` in a text editor. The file is installed in the `install\redist` directory, where `install` is the directory in which you installed Viewing SDK.

2. Under the `[HKEY_LOCAL_MACHINE\Software\Verity\Viewing SDK\KVMAILVE` key, change the parameter `"297"="pstsr.dll"` to `"297"="pstxsr.dll"`.

3. Save the file as `install.reg`.

4. Import the file into your Windows system registry.

### System Requirements

MAPI is supported on Windows platforms only and relies on functionality in Outlook. If you want to use the MAPI-based reader, `pstsr`, Microsoft Outlook must be installed on the same machine as your application. Outlook must also be the default email application. KeyView supports the following PST formats and Outlook clients:

- Outlook 97 or later PST files

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

- Outlook 2002 or later clients

  NOTE: You must install an edition of Microsoft Outlook (32-bit or 64-bit) that matches the KeyView software. For example, if you use 32-bit KeyView, install 32-bit Outlook. If you use 64-bit KeyView, install 64-bit Outlook.

  If the editions do not match, KeyView returns `Error 32: KVError_PSTAccessFailed` and 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.`

## Lotus Notes Database (NSF)

The NSF 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 License Information for information on adding a new license key to an existing installation.

A Lotus Notes database is a single file that contains multiple documents called notes. Notes include design notes (such as forms, views, folders, navigators, outlines, pages, framesets, agents, and resources), data document notes, profile document notes, access control list notes, and collection (index) notes. KeyView can display text items, attachments, and OLE objects from data document notes only. Data document notes include emails, journal entries, discussion threads, documents (Microsoft Office and Lotus SmartSuite), and so on.

### System Requirements

The NSF format is proprietary. Therefore, KeyView accesses NSF files indirectly by using the Lotus Notes API. Because the NSF reader relies on functionality in Lotus Notes, a Lotus Notes client or Lotus Domino server must be installed and configured on the same machine as the application that displays the NSF files.

KeyView supports Lotus Notes client version 6.5.1, Lotus Domino 6.5.1, and NSF files on the same platforms supported by Lotus Notes and Lotus Domino:

- Windows XP x86 (Service Pack 1 and 2)

- Windows 2000 x86 (Service Pack 2)

### Installation and Configuration

Before KeyView can display NSF files, you must set up the Lotus Notes client or Lotus Domino server. Full configuration is not required. The following steps outline the minimal setup for NSF viewing:

1. Install the Lotus Notes client or Lotus Domino server. You do not need to configure the client or server.

2. Make sure that the file `notes.ini` is in the `install``\lotus\notes` directory, where `install` is the directory where Lotus Notes is installed. If the file does not exist, create an ASCII file named `notes.ini`, and add the following text:

       [Notes]

3. Add the `install``\lotus\notes` and KeyView `bin` directories to the `PATH` environment variable. Micro Focus recommends that you add the KeyView `bin` directory because the Lotus Notes installation might contain older KeyView OEM libraries.

### Format Notes

The KeyView NSF reader uses XML templates to format Lotus notes. You can customize the templates as required to approximate the look and feel of the original notes as closely as possible. For more information, see Extract and Format Lotus Notes Subfiles.

## View Mail Messages and Mail Stores

You can display mail messages and mail stores in one of two ways:

- The Viewing window displays the file's hierarchy—showing all the children of the parent file—by using the archive format viewing engine, `kvarve.dll`. See View Archive Files for more information.

- The Viewing windows displays the file as it would appear in a Microsoft Outlook Client. This display uses the mail format viewing engine, `kvmailve.dll`.

By default, mail messages and mail stores are displayed with the mail format viewing engine. To use the archive format viewing engine to display the complete file hierarchy, follow these steps:

In the `kvsdk.ini` file

1. Open the `kvsdk.ini` file with a text editor. The file is installed in the root of the Windows directory.

2. Remove the comments from the beginning of the following lines:

       297=zip 0 kvarcve.dll; PST
       295=zip 0 kvarcve.dll; MSG MS Outlook
       208=zip 0 kvarcve.dll; EML
       299=zip 0 kvarcve.dll; Lotus Notes NSF

3. In the `[VAPI]` section of the `kvsdk.ini` file, insert comments at the beginning of the following lines:

       ; Mail formats
       ;kvmailve.dll=kvMAILVIEW;
       ;297=mail 0 kvmailve.dll;    PST
       ;295=mail 0 kvmailve.dll;    MSG MS Outlook
       ;208=mail 0 kvmailve.dll;    EML
       ;299=mail 0 kvmailve.dll;    Lotus Notes NSF

In the registry file

1. Open the `install.reg.txt` ``in a text editor. The file is installed in the `install\redist` directory, where `install` is the directory in which you installed Viewing SDK.

2. Remove the comments from the beginning of the following lines:

       297=zip 0 kvarcve.dll; PST
       295=zip 0 kvarcve.dll; MSG MS Outlook
       208=zip 0 kvarcve.dll; EML
       299=zip 0 kvarcve.dll; Lotus Notes NSF

3. Under the `[HKEY_LOCAL_MACHINE\Software\Verity\Viewing SDK\VAPI]` key, insert comments at the beginning of the following lines:; Mail formats

       ; Mail formats
       ;kvmailve.dll=kvMAILVIEW;
       ;297=mail 0 kvmailve.dll;    PST
       ;295=mail 0 kvmailve.dll;    MSG MS Outlook
       ;208=mail 0 kvmailve.dll;    EML
       ;299=mail 0 kvmailve.dll;    Lotus Notes NSF

4. Save the file as `install.reg`.

5. Import the file into your Windows system registry.

The following figure shows a PST file displayed in the Viewing API sample program with the mail format viewing engine:

Display mail files with the mail format viewing engine

To extract the main message and its attachments to disk, select the main message and send an Unzip message or method (`VAPIMWP_FILE_UNZIP` or `UnZip`). See the implementation of the Extract menu in the View API Demo program (`vapidemo`).

To view an attachment, double-click the file in the Attachments field. The file is displayed in a separate window that can be closed.

## View Archive Files

The Viewing window displays an archive file's hierarchy—showing all the children of the parent file—by using the archive format viewing engine `kvarve.dll`. (You can also display mail files by using the archive format viewing engine. This is optional, and must be configured in the initialization file or registry file. See View Mail Messages and Mail Stores.)

When an archive file is opened for viewing, the archive's folders and subfiles are listed in one pane (the file list pane). When a user selects a subfile, the subfile is displayed in another pane (the preview pane). When a user double-clicks a selected subfile, the file's text is displayed in the entire application window. When a subfile is extracted to disk, the user is prompted for a target directory. If the file already exists on disk, a dialog box asks the user whether the file can be overwritten.

The following figure shows a ZIP file displayed in the Viewing API sample program.

Display an archive file with the archive viewing engine

## Extract Subfiles to a Viewing Window or Disk

To extract a subfile or files from a container file to a Viewing window or disk

1. Open the container file. See Open and View a Document.

2. Use the VAPIMWP_FILE_CANUNZIP message to determine whether the selected subfile or files can be extracted.

3. Use the following VAPIMWP_FILE_UNZIP message to extract the selected subfile or files to a Viewing window or to disk. If you extract the files to disk, Viewing prompts you for the target directory and overwrite permission.

   See the implementation of the Extract menu in the View API Demo program (`vapidemo`).

## Display Subfiles in the Preview Pane

NOTE: The preview pane messages apply to the Archive Viewing Engine (`kvarcve`) only. The Mail Viewing Engine (`mailve`) does not use these settings.

To display a subfile in the preview pane

1. Use the VAPIMWP_VIEW_CANPREVIEWPANE message to determine whether a subfile can be displayed in a preview pane.

2. Use the VAPIMWP_VIEW_GETPREVIEWPANE message to determine whether the preview pane is currently being used.

3. If required, set the size and location of the preview pane using the `ARCHIVE_OPTIONS` structure. This structure is described in `kwoption.h`. See Change Document Options.

4. Use the VAPIMWP_VIEW_SETPREVIEWPANE message to specify the subfile is displayed in the preview pane.

The View API Demo program (`vapidemo`) demonstrates this functionality.

## Set a Password for a Container File

For password-protected ZIP, PST, or NSF files, use the VAPIMWP_INIT_SETPASSWORD message to set the password before the file is opened.

_FT_HTML5_bannerTitle.htm