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.pyscans your code base and identifies where code changes might be required.23.2_update_keyview_configuration_files.pyupdates your existingformats.ini,formats_e.iniorkvsdk.iniconfiguration 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
fpInitandfpInitWithLicenseData(orKV_InitandKV_InitWithLicenseData) have been replaced by a newfpInitfunction that accepts an IDOL license. - In the C++ API, the
Sessionconstructor has been changed to accept an IDOL license. - In the .NET API, the
Filterobject constructor has been changed to accept an IDOL license. - In the Java API, the
Filterobject constructor has been changed to accept an IDOL license.
Export SDK
- In the C API, the functions
fpInitandfpInitWithLicenseData(orKVHTML_INIT,KVXML_INIT,KVPDF_INIT,KVHTML_INIT_WITH_LICENSE_DATA,KVXML_INIT_WITH_LICENSE_DATA, andKVPDF_INIT_WITH_LICENSE_DATA) have been replaced by a newfpInitfunction that accepts an IDOL license. - In the Java API, the constructors for the
HtmlExportandXmlExportobjects 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_SETLICENSEparameter, 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(orKV_PANOPTICON_INIT) function has been changed to accept an IDOL license. - In the Java API, the
Panopticonconstructor 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,
fpGetKvErrorCodeExhas been deprecated and you only need to call it if you use the deprecated functionsfpGetDocInfoFile,fpGetDocInfoStream, andfpFilterConfigwhich returnFALSEto indicate an error, rather than returning an error code. - In the Export C API, the function
fpGetKvErrorCodeExis 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->subFileSizeis now auint64_t(instead of along). - In the Filter C++ API,
Subfile::size()returns auint64_t(instead of anint64_t). - In the Filter .NET API,
ExtractSubFileInfo.SubFileSizeis now aUInt64(instead of anInt64).
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.
| SDK | Deleted feature | Upgrade guidance |
|---|---|---|
| Filter and Export |
The Archive API has been deleted. Functions:
Types:
|
Replace any use of the Archive API with the Extract API. |
| Filter and Export |
The Container API has been deleted. Functions:
Types:
|
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
|
The 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 |
| Filter | KVDynLink
|
Remove all usage and do not include kvfilt2.h, which was only used to define KVDynLink. |
| Filter |
|
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:
HTML Export:
XML Export:
|
Remove all usage. |
| Viewing | You should no longer include kwcmfio.h or kwcnvmgr.h. |
|
| SDK | Deleted feature | Upgrade guidance |
|---|---|---|
| Filter | ArchivedFileInfo class. |
The archive API has been removed. Use the extract API instead. |
| Filter |
|
The container API has been removed. Use the extract API instead. |
| 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_OOPMEMTRACEONandKVF_OOPMEMTRACEOFFhave been deleted (in earlier versions of KeyView these could be passed into thefpInit,fpInitWithLicenseData, orfpOpenStreamEx2functions using thedwFlagsargument). - In the Filter Java API, the flags
Filter.FILTERFLAG_OOPMEMTRACEONandFilter.FILTERFLAG_OOPMEMTRACEOFFhave been deleted (in earlier versions of KeyView these could be passed into theFilterobject constructor). - In the Filter .NET API, the flags
FilterConstant.FilterFlagsConstant.FILTERFLAG_OOPMEMTRACEONandFilterConstant.FilterFlagsConstant.FILTERFLAG_OOPMEMTRACEOFFhave been deleted (in earlier versions of KeyView these could be passed into theFilterconstructor).
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_UNKNOWNto the constructor of theFilterobject. - set
ExtractSubFileMetaConfig.TargetCharsettoCharset.KVCS_UNKNOWNwhen 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.