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 existingformats.ini
,formats_e.ini
orkvsdk.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
andfpInitWithLicenseData
(orKV_Init
andKV_InitWithLicenseData
) have been replaced by a newfpInit
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
andfpInitWithLicenseData
(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 newfpInit
function that accepts an IDOL license. - In the Java API, the constructors for the
HtmlExport
andXmlExport
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
(orKV_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 functionsfpGetDocInfoFile
,fpGetDocInfoStream
, andfpFilterConfig
which returnFALSE
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 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.SubFileSize
is 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_OOPMEMTRACEON
andKVF_OOPMEMTRACEOFF
have been deleted (in earlier versions of KeyView these could be passed into thefpInit
,fpInitWithLicenseData
, orfpOpenStreamEx2
functions using thedwFlags
argument). - In the Filter Java API, the flags
Filter.FILTERFLAG_OOPMEMTRACEON
andFilter.FILTERFLAG_OOPMEMTRACEOFF
have been deleted (in earlier versions of KeyView these could be passed into theFilter
object constructor). - In the Filter .NET API, the flags
FilterConstant.FilterFlagsConstant.FILTERFLAG_OOPMEMTRACEON
andFilterConstant.FilterFlagsConstant.FILTERFLAG_OOPMEMTRACEOFF
have been deleted (in earlier versions of KeyView these could be passed into theFilter
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 theFilter
object. - set
ExtractSubFileMetaConfig.TargetCharset
toCharset.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
.