RecAPI
Functions
KernelAPIS
KernelAPI

Dynamic linking of KernelAPI. This module is supported on: Windows. More...

Functions

RECERR RECAPIKRN kRecInitS (LPCTSTR pRecPath, LPCTSTR pCompanyName, LPCTSTR pProductName)
 Initializing KernelAPIS.
RECERR RECAPIKRN kRecQuitS (void)
 Closing KernelAPIS.
RECERR RECAPIKRN kRecSetLicenseS (LPCTSTR pLicenseFile, LPCTSTR pCode)
 Setting the OEM license information.

Detailed Description

Dynamic linking of KernelAPI. This module is supported on: Windows.

There may be a general problem with DLL's that they must be located on one of some predetermined pathes. It may constrain the distribution of the integrating application. The KernelAPIS module solves this problem.

KernelAPIS is a wrapper on the module KernelAPI, which makes possible to separate the integrating application from the files of the OmniPage CSDK 20 without putting the folder of the CSDK into the environment variable PATH. In fact, this may be one of some little static libraries. Depending on how the release version of the integrating application uses the C run-time libraries, one of the following KernelAPIS static libraries should be linked to the application:

The debug version of the integrating application requires a static library to be linked as follows:

It is a thin interface layer for binding the Engine at run-time. It loads the KernelAPI from a specified path and gets all the entry points of the KernelAPI.DLL (kRecInitS). Unloading also can be controlled by the integrating application (kRecQuitS).

Function Documentation

RECERR RECAPIKRN kRecInitS ( LPCTSTR  pRecPath,
LPCTSTR  pCompanyName,
LPCTSTR  pProductName 
)

Initializing KernelAPIS.

This function initializes the module KernelAPIS, which includes the initialization of KernelAPI. Except for kRecSetLicenseS, the functions of KernelAPI should not be called before initialization. This function allows the integrating application to bind the Engine by enumerating the modules installed in the Engine Binary directory, determining the configuration of the Engine and initializing its modules (i.e. by calling kRecInit from inside).

Parameters:
[in]pRecPathFull path to the Engine Binary directory, i.e. where the Engine files are located. NULL kRecInitS searches Engine files beside the application process EXE. Relative path from the application process EXE where the Engine files are located.
[in]pCompanyNameName of the User's Company. It can be NULL. Default value: Nuance. It can be used for creating a company-specific working folder for temporary and other files generated by KernelAPI.
[in]pProductNameName of the Product or Application. It can be NULL. Default value: OmniPageCSDK20. It can be used for creating an application-specific working folder for temporary and other files generated by KernelAPI.
Return values:
RECERR
Note:
This function is an alternative call to the kRecInit function, use one of these for Engine initialization.
To close KernelAPIS and also the Engine, the application has to call the kRecQuitS function.
If the specified directory is invalid, or exists but does not contain the Engine files, an API_INIT_ERR value is returned.
This function DOES NOT initialize the scanning module, its initialization requires a separate kRecScanInit function call.
You can speed up Engine initialization by removing superfluous modules from the Engine Binary directory.
RECERR RECAPIKRN kRecQuitS ( void  )

Closing KernelAPIS.

This function closes the module KernelAPIS, which includes the closing of KernelAPI. This function should be called only when the initialization used by the integrating application calls kRecInitS.

Return values:
RECERR
RECERR RECAPIKRN kRecSetLicenseS ( LPCTSTR  pLicenseFile,
LPCTSTR  pCode 
)

Setting the OEM license information.

The kRecSetLicenseS function sets the OEM license information. In the case of an OEM distribution this function must be called before kRecInitS.

Parameters:
[in]pLicenseFileName of the license file or the fully qualified path to the license file (an LCX or LCXZ file). On Windows this parameter is usually NULL. In this case the Nuance License Service is running and the OEM license file is already loaded by the Nuance License Tool.
[in]pCodeOEM Code string. (It's a pointer to the string itself, not a pointer to the file name containing the OEM Code!)
Return values:
RECERR
Note:
If the integrating application calls more than one kRecInitS kRecQuitS pair subsequently, this function is required to be called only before the first kRecInitS.
The return value may be API_INIT_WARN, which means that OmniPage CSDK has been already initialized.
This function does not relate to development licensing or to distribution done by Fixed Volume Licenses.
The license file itself and a C header file containing the OEM Code string are generated by the Nuance License Tool. This type of licensing enables pre-activated licensing. It eliminates the need for the distribution of the Nuance License Tool component and on-site license activation that is necessary with Fixed Volume licensing. Licensing on Windows is fully described in the General Information help system.
On Windows the license file is usually loaded by the Nuance License Tool in a separate step at installation time. In that case the first parameter (pLicenseFile) of kRecSetLicenseS must be NULL. Note that the OEM Code (pCode) parameter must be non-NULL and must correspond to the installed license file even this case!
If pLicenseFile is neither NULL nor a full path filename but a relative path or just a file name without any path components then the Engine searches for the license file in different directories in the following order:
  1. Next to the application itself (exe file in Windows)
  2. Next to the Engine libraries (dll files in Windows). In several cases this is the same as the previous path.
  3. In a common Nuance CSDK directory inside the COMMON_APPDATA folder. This folder depends on the OS:
    • Windows: the "Nuance\\\productname\\" subdirectory under the path returned by SHGetFolderPath(NULL, CSIDL_COMMON_APPDATA, NULL, 0, folderBuffer);
    • Linux: $HOME/.nuance-omnipage-csdk-20.0
    • Mac OS X: $HOME/.Nuance-OmniPage-CSDK-20.0
    (The current working directory is not searched as that is likely to be unsuitable!) (In later versions of the Engine the numeric value in the above pathes will change to reflect the actual version.)