IDOL 24.2.2

# KeyView

KeyView 23.2 is a new major version of KeyView, released in the second quarter of 2023. It is the first new major version since KeyView 12.0 was released in June 2018. This section describes the changes in KeyView 23.2 that might affect your application code.

- Licensing
- Supported Platforms
- C API Error Code Unification
- Subfile File Sizes
- Removal of Format Category Numbers
- Removal of kpPDFrdr
- PST Handling without Outlook by default
- Removal of Obsolete and Deprecated Interfaces
- Removal of Memory Tracing
- Filter .NET API Default Output Character Encoding
- Filter .NET API 32-bit Extraction Interface
- Optional Changes

To help you upgrade, KeyView 23.2 includes the following python scripts:

- `23.2_identify_required_code_changes.py` scans your code base and identifies where code changes might be required.
- `23.2_update_keyview_configuration_files.py` updates your existing `formats.ini`, `formats_e.ini` or `kvsdk.ini` configuration files so that you can continue to use them, following the changes described in Removal of Format Category Numbers.

For releases not designated as major, we make every effort to ensure that you can upgrade by replacing the KeyView binaries, without changing or recompiling your code.

## Licensing

As usual for a major release, you must obtain a new license. KeyView 12.x licenses do not work with KeyView 23.2.

KeyView 23.2 uses the same licensing system as other IDOL products, so the format of the license key has changed. In addition, KeyView no longer reads license information from the file `kv.lic`, so you must pass your license key to the KeyView API. This will require the following changes in your application code.

Filter SDK

- In the C API, the functions `fpInit` and `fpInitWithLicenseData` (or `KV_Init` and `KV_InitWithLicenseData`) have been replaced by a new `fpInit` function that accepts an IDOL license.
- In the C++ API, the `Session` constructor has been changed to accept an IDOL license.
- In the .NET API, the `Filter` object constructor has been changed to accept an IDOL license.
- In the Java API, the `Filter` object constructor has been changed to accept an IDOL license.

Export SDK

- In the C API, the functions `fpInit` and `fpInitWithLicenseData` (or `KVHTML_INIT`, `KVXML_INIT`, `KVPDF_INIT`, `KVHTML_INIT_WITH_LICENSE_DATA`, `KVXML_INIT_WITH_LICENSE_DATA`, and `KVPDF_INIT_WITH_LICENSE_DATA`) have been replaced by a new `fpInit` function that accepts an IDOL license.
- In the Java API, the constructors for the `HtmlExport` and `XmlExport` objects have been changed to accept an IDOL license.

Viewing SDK

- If you are using the Viewing C API, you must pass in your license using the `VAPIMWP_INIT_SETLICENSE` parameter, immediately after creating the Viewing API window. For more information, see "Create a Viewing API Window" in the Viewing SDK Programming Guide.

Panopticon

- In the C API, the `init` (or `KV_PANOPTICON_INIT`) function has been changed to accept an IDOL license.
- In the Java API, the `Panopticon` constructor has been changed to accept an IDOL license.

## Supported Platforms

KeyView is no longer supported on the following platforms.

- AIX ppc32
- AIX ppc64
- Solaris SPARC
- Solaris SPARC64
- Solaris x86
- Solaris x86-64

## C API Error Code Unification

To simplify error handling, KeyView no longer distinguishes between errors and extended errors.

In earlier versions of the Filter and Export C APIs, functions could return one of 22 errors in the `KVErrorCode` enumeration. On receiving `KVError_General` you could call `fpGetKvErrorCodeEx` (or `KV_GetKvErrorCodeEx`) to get an "extended" error code that provided more information. In KeyView 23.2, the `KVErrorCode` enumeration includes the whole range of errors, including those that were previously considered "extended" errors.

Update your error handling to handle the new error codes in `KVErrorCode`, instead of calling `fpGetKvErrorCodeEx` and handing the errors at that point.

- In the Filter C API, `fpGetKvErrorCodeEx` has been deprecated and you only need to call it if you use the deprecated functions `fpGetDocInfoFile`, `fpGetDocInfoStream`, and `fpFilterConfig` which return `FALSE` to indicate an error, rather than returning an error code.
- In the Export C API, the function `fpGetKvErrorCodeEx` is no longer necessary and has been deleted.

If you are using the C++, Java, or .NET APIs no changes are required because no distinction was made between error codes and extended error codes in those APIs.

In future KeyView releases, `KVErrorCode` might be extended with new error codes.

## Subfile File Sizes

KeyView 23.2 reports the sizes of subfiles using unsigned 64-bit integers. This allows KeyView to report larger file sizes, but you might need to update your code to handle the larger values and guard against overflows.

- In the Filter C API, `KVSubFileInfo->subFileSize` is now a `uint64_t` (instead of a `long`).
- In the Filter C++ API, `Subfile::size()` returns a `uint64_t` (instead of an `int64_t`).
- In the Filter .NET API, `ExtractSubFileInfo.SubFileSize` is now a `UInt64` (instead of an `Int64`).

## Removal of Format Category Numbers

In KeyView 12.x and earlier, each file format had an associated category number. The categories were used to map file formats to readers, in the `formats.ini` configuration file (Filter SDK), `formats_e.ini` configuration file (Export SDK), and either the `kvsdk.ini` configuration file or the Windows registry (Viewing SDK).

In KeyView 23.2, it is much easier to map file formats to readers. File formats no longer have an associated "category". The KeyView configuration files now identify file formats using the same format numbers that are returned by format detection. Document classes (such as `adWORDPROCESSOR` or `adVECTORGRAPHIC`) are unaffected.

If you use the configuration files that are provided in the SDK, then no further action is needed. If you want to keep using existing configuration files that you have customized, you must replace the format category numbers. KeyView 23.2 includes a Python script that can do this for you. The script is named `23.2_update_keyview_configuration_files.py`.

## Removal of kpPDFrdr

To simplify the range of options we provide for filtering, exporting, and viewing PDF files, we have removed the graphic-based reader `kpPDFrdr`. We believe that `pdfsr` and `pdf2sr` offer superior functionality.

If you have configured KeyView to use `kpPDFrdr`, change your configuration to use `pdfsr` or `pdf2sr` instead.

## PST Handling without Outlook by default

KeyView now uses `pstxsr` by default, which means you can extract PST files without needing to have Microsoft Outlook installed. You do not need to take any action, as this is a change to default behavior. If you want to use the old `pstsr` reader instead you can do so by editing the `formats.ini` configuration file to set `356=pst` in the `[Formats]` section.

## Removal of Obsolete and Deprecated Interfaces

We have deleted a range of undocumented and unsupported legacy interfaces from our APIs. We have also deleted some interfaces and functionality that were deprecated in earlier versions of KeyView. If you are using the latest documented APIs, no code changes are required.

To help you upgrade, KeyView 23.2 includes a Python script that you can use to check your code for usage of the deleted APIs.

More information (C APIs)

SDK | Deleted feature | Upgrade guidance
--- | --- | ---
Filter and Export | The Archive API has been deleted. Functions: fpIsArchiveFile fpIsArchiveFileSupported fpOpenArchiveFile fpGetNumFilesInArchiveFile fpGetArchiveFileInfo fpExtractArchiveFile fpCloseArchiveFile Types: TPArchiveFileInfo | Replace any use of the Archive API with the Extract API.
Filter and Export | The Container API has been deleted. Functions: fpCanFilterAsContainer fpOpenContainerStream fpCloseContainerStream fpGetNumFilesInContainer fpGetContainerSubFileInfo fpSetExtractionPath fpSetExtractionOverwrite fpExtractContainerSubFile fpGetContainerContent fpFreeSubFileMetadata Types: TPContainerSubFileInfo | Replace any use of the Container API with the Extract API.
Filter | The following flags have been deleted (in earlier versions of KeyView these could be passed into the `fpInit`, `fpInitWithLicenseData`, or `fpOpenStreamEx2` functions using the `dwFlags` argument). KVF_FILTERCONTAINERCONTENT KVF_METADATA | The `fpInit` and `fpInitWithLicenseData` functions have been replaced by a new `fpInit` function (see Licensing). If your code sets these flags, you must remove them.
Filter | `KVFilterInterface` | Replace with `KVFltInterfaceEx` and do not include `kvfilter.h`, which defined `KVFilterInterface`.
Filter | `KVMemoryStream` | Remove all usage. NOTE: If your application calls `fpFilterStream()`, ensure that you free the memory allocated for the `KVFilterOutput` structure by calling `fpFreeFilterOutput()`.
Filter | `KVDynLink` | Remove all usage and do not include `kvfilt2.h`, which was only used to define `KVDynLink`.
Filter | KV_CanFilterCharMap KV_AutoRecFile KV_AutoRecStream fpFilterVirtualFile fpIsVirtualFile fpGetDocInfoVirtualFile fpOpenVirtualStream fpCloseVirtualStream | Remove all usage.
Export | `fpValidateTemplate` | Remove all usage.
Export | `KVHTMLAnchorType` | Replace with `KVHTMLAnchorTypeEx`
Export | `KVHTMLCallbacks` | Replace with `KVHTMLCallbacksEx`
Export | `KVHTMLInterface` | Replace with `KVHTMLInterfaceEx2`
Export | `KVHTMLInterfaceEx` | Replace with `KVHTMLInterfaceEx2`
Export | `KVHTMLOptions` | Replace with `KVHTMLOptionsEx`
Export | `KVHTMLTemplate` | Replace with `KVHTMLTemplateEx`
Export | `KVXMLInterface` | Replace with `KVXMLInterfaceEx`
Export | HTML and XML Export: KVTEST_SETPIDZERO HTML Export: KVHTML_FORCEOUTPUTCHARSET KVHTML_ENABLEEMPTYROWS KVHTML_BOOKFORMAT KVHTML_BOOKPREP KVHTML_BOOKSUMMARY KVSA_RESERVED1 XML Export: KVXML_FORCEOUTPUTCHARSET KVXML_ENABLEEMPTYROWS KVXML_BOOKFORMAT KVXML_BOOKPREP KVXML_BOOKSUMMARY KVXML_GPPSTRINGMAXSIZE | Remove all usage.
Viewing | You should no longer include `kwcmfio.h` or `kwcnvmgr.h`.

More information (Java APIs)

SDK | Deleted feature | Upgrade guidance
--- | --- | ---
Filter | `ArchivedFileInfo` class. | The archive API has been removed. Use the extract API instead.
Filter | `ContainerSubFileInfo` class `FILTERFLAG_FILTERCONTAINERCONTENT` constant. | The container API has been removed. Use the extract API instead.

More information (.NET APIs)

SDK | Deleted feature | Upgrade guidance
--- | --- | ---
Filter | `FILTERFLAG_FILTERCONTAINERCONTENT` constant. | The container API has been removed. Use the extract API instead.
Filter | `ExtractOpenDocument` method. | Use `ExtractOpenDocumentEx` instead. You must store its return value as a `long`, not an `int`.

## Removal of Memory Tracing

The memory tracing feature has been removed from the all of the Filter APIs.

- In the Filter C API, the flags `KVF_OOPMEMTRACEON` and `KVF_OOPMEMTRACEOFF` have been deleted (in earlier versions of KeyView these could be passed into the `fpInit`, `fpInitWithLicenseData`, or `fpOpenStreamEx2` functions using the `dwFlags` argument).
- In the Filter Java API, the flags `Filter.FILTERFLAG_OOPMEMTRACEON` and `Filter.FILTERFLAG_OOPMEMTRACEOFF` have been deleted (in earlier versions of KeyView these could be passed into the `Filter` object constructor).
- In the Filter .NET API, the flags `FilterConstant.FilterFlagsConstant.FILTERFLAG_OOPMEMTRACEON` and `FilterConstant.FilterFlagsConstant.FILTERFLAG_OOPMEMTRACEOFF` have been deleted (in earlier versions of KeyView these could be passed into the `Filter` constructor).

The environment variable `KVOOPMT` no longer has any effect.

## Filter .NET API Default Output Character Encoding

The Filter .NET API now produces UTF-8 output by default, because this is the desired behavior for most use cases. In earlier versions of KeyView, the default output character encoding was the local Windows code page.

If you prefer output in the local Windows code page and your code does not specify a target character set, you will need to:

- pass `Charset.KVCS_UNKNOWN` to the constructor of the `Filter` object.
- set `ExtractSubFileMetaConfig.TargetCharset` to `Charset.KVCS_UNKNOWN` when extracting subfile metadata.

## Filter .NET API 32-bit Extraction Interface

In earlier versions of KeyView, the Filter .NET API exposed a set of extraction functions that would work only with a 32-bit installation of KeyView, and another set that would work with both 32 and 64-bit installations. The 32-bit-only version has been removed.

Your code will fail to compile if it calls `Filter.ExtractOpenDocument`. Instead, call `Filter.ExtractOpenDocumentEx` and store the result in a `long` rather than an `int`.

## Optional Changes

This section describes optional changes that you might want to make in your application.

### New Metadata API

KeyView 23.2 introduces a new metadata API that:

- reduces the number of function calls you need to make to retrieve all metadata.
- performs field standardization. Field standardization returns metadata using a standard set of field names, so that the same metadata is returned in the same field regardless of the source file format. The new metadata API allows for the introduction of further standardization, in future releases, without breaking backwards compatibility.

The new metadata API is available in KeyView Filter (C and C++). The new metadata API can also be used through KeyView Export (C), but only when extracting subfile metadata.

No code changes are required because the old metadata interfaces are still present. However, the old interfaces are deprecated and will be removed in a future major version.

### KVFilterSession (Filter C API)

Some of the functions in the KeyView Filter C API require a Filter session context as their first argument. In previous versions of KeyView, the session context was a `void*` pointer. A new `KVFilterSession` type has been introduced and all of the Filter API functions that require a session context now accept a `KVFilterSession`. Where a Filter session context is required, you can still pass a `void*` pointer but this behavior is deprecated. OpenText recommends that you switch to using the `KVFilterSession` type instead.

### KVDocument (Filter C API)

KeyView 23.2 introduces the concept of a `KVDocument` to the C API. This allows for future performance improvements through caching of data between calls to KeyView for the same file. No code changes are required because the old interface functions are still present. To benefit from future performance improvements through caching, OpenText recommends that you switch to the new API functions that take a `KVDocument`.

Copyright 2024 Open Text
Version 24.2.2 | Last updated March 2024

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: IDOL 24.2.2

Topic Title: KeyView