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.

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.

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.