General Operations Module

General operations and data. More...

Classes
struct	KRECMODULEINFO
	Module info. More...
struct	PROGRESSMONITOR
	Progress information. More...
Modules
	Error Handling Module
	Error information.
	Settings Manager Module
	This is the manager of settings at the KernelAPI level.
Typedefs
typedef KRECMODULEINFO *	LPKRECMODULEINFO
	Pointer to a structure KRECMODULEINFO.
typedef PROGRESSMONITOR *	LPPROGRESSMONITOR
	Pointer to a PROGRESSMONITOR.
typedef RECERR RECKRNCALL	PROGMON_CB (LPPROGRESSMONITOR mod, void *pContext)
	The user-written progress monitoring callback function.
typedef PROGMON_CB *	LPPROGMON_CB
	Pointer to a callback PROGMON_CB.
Enumerations
enum	KRECMODULES {   INFO_API = 0,   INFO_MOR,   INFO_DOT,   INFO_BAR,   INFO_OMR,   INFO_HNR,   INFO_DCM,   INFO_IMG,   INFO_IMF,   INFO_CHR,   INFO_DTXT,   INFO_SPL,   INFO_RSD,   INFO_RER,   INFO_MGR,   INFO_MTX,   INFO_MAT,   INFO_RESERVED_P,   INFO_PLUS2W,   INFO_FRX,   INFO_PLUS3W,   INFO_ASN,   INFO_XOCR,   INFO_LFR,   INFO_ASP,   INFO_SIZE }
	Module identifiers. More...
enum	PROCESSID {   PID_IMGINPUT = 0,   PID_IMGSAVE,   PID_IMGPREPROCESS,   PID_DECOMPOSITION,   PID_RECOGNITION1,   PID_RECOGNITION2,   PID_RECOGNITION3,   PID_SPELLING,   PID_FORMATTING,   PID_WRITEFOUTDOC,   PID_CONVERTIMG,   PID_SCANNER_WARMUP }
	Progress identifiers. More...
Functions
RECERR RECAPIKRN	kRecSetLibraryPath (LPCTSTR libpath)
	Setting the path of the library files.
RECERR RECAPIKRN	kRecSetDataPath (LPCTSTR datapath)
	Setting the path of the data files.
RECERR RECAPIKRN	kRecSetSandboxHomePath (const char *homepath)
	Setting the Sandbox path on MacOS.
RECERR RECAPIKRN	kRecSetSandboxTempPath (const char *temppath)
	Setting the Sandbox temporary path on MacOS.
RECERR RECAPIKRN	kRecSetLicense (LPCTSTR pLicenseFile, LPCTSTR pCode)
	Setting the OEM license information.
RECERR RECAPIKRN	kRecInit (LPCTSTR pCompanyName, LPCTSTR pProductName)
	Initializing KernelAPI.
RECERR RECAPIKRN	kRecQuit (void)
	Closing KernelAPI.
RECERR RECAPIKRN	kRecSetUILang (const char *lang)
	Setting the language of displayed information.
RECERR RECAPIKRN	kRecGetUILang (char *langbuff, size_t buffersize)
int RECAPIKRN	kRecCreateSettingsCollection (int sid)
	Creating a new Settings Collection.
RECERR RECAPIKRN	kRecDeleteSettingsCollection (int sid)
	Deleting a Settings Collection.
RECERR RECAPIKRN	kRecGetSerialNumber (LPTSTR pSn, size_t buflen)
int RECAPIKRN	kRecGetVersion (void)
	Getting version.
RECERR RECAPIKRN	kRecSetCBProgMon (int sid, LPPROGMON_CB pCallBack, void *pContext)
	Setting progress monitor.
RECERR RECAPIKRN	kRecSetTimeOut (int sid, DWORD TimeOut)
	Setting timeout period.
RECERR RECAPIKRN	kRecGetTimeOut (int sid, LPDWORD pTimeOut)
	Getting timeout period.
RECERR RECAPIKRN	kRecFree (void *pArray)
	Freeing memory objects.
RECERR RECAPIKRN	kRecGetModulesInfo (LPKRECMODULEINFO *ppModules, size_t *pSize)
	Getting module information.
RECERR RECAPIKRN	kRecLoadSettings (int sid, LPCTSTR pFileName)
	Loading settings.
RECERR RECAPIKRN	kRecSaveSettings (int sid, LPCTSTR pFileName)
	Saving settings of KernelAPI.
RECERR RECAPIKRN	kRecSetDefaults (int sid)
	Changing settings of KernelAPI to default.
RECERR RECAPIKRN	kRecSetIntSetting (int sid, LPCTSTR setting, int new_value)
	Setting the value of an STS_INT or STS_ENUM or STS_BOOL setting.
RECERR RECAPIKRN	kRecGetIntSetting (int sid, LPCTSTR setting, int *the_value)
	Accessing the current value of an STS_INT or STS_ENUM or STS_BOOL setting.
RECERR RECAPIKRN	kRecSetDoubleSetting (int sid, LPCTSTR setting, double new_value)
	Setting the value of an STS_DOUBLE setting.
RECERR RECAPIKRN	kRecGetDoubleSetting (int sid, LPCTSTR setting, double *the_value)
	Accessing the current value of an STS_DOUBLE setting.
RECERR RECAPIKRN	kRecSetStringSetting (int sid, LPCTSTR setting, LPCTSTR new_value)
	Setting the value of an STS_STRING or STS_USTRING setting.
RECERR RECAPIKRN	kRecGetStringSetting (int sid, LPCTSTR setting, LPTSTR *the_value)
	Accessing the current value of an STS_STRING or STS_USTRING setting.

---

Detailed Description

General operations and data.

This module contains the basic types and functions necessary to use the general services of the KernelAPI. Initialization (kRecInit, kRecQuit) is an essential prerequisite for utilizing KernelAPI functionality. User authorization can also be performed in this module.

Useful information can be got about itself the Engine (e.g. accessible modules by kRecGetModulesInfo).

Most RecAPI operations work through Settings Collections. A Settings Collection acts as a kind of profile. It is a separate storage for operation settings (handled by Settings Manager Module). Distinct Settings Collections can store different values for given settings. A Settings Collection is authorized by an identifier. This identifier must be passed to all operations using that Settings Collection. The Collection with the ID 0 is cretaed automatically during the initialization of the Capture SDK. Settings Collections can be user-created or deleted, using the functions kRecCreateSettingsCollection, kRecDeleteSettingsCollection, respectively. You can also save or load settings here.

The same Settings Collections can be used from different threads. (Multi-threading is supported on: Windows.) Furthermore, one thread can use more than one Settings Collection. For more information, see the topic Multi-threading in RecAPI.

Timeout handling

Kernel.Timeout.Hard is an additional amount of time over the normal Kernel.Timeout time. The addition of the two values provides a hard timeout limit. This is designed this way in order to have a single kRecSetTimeOut call effectively change both the normal and hard timeout values. By default the hard timeout setting adds 10 seconds to the normal one.

Normally the timeout is checked at clean processing places inside recognition. If the engine detects that the normal timeout limit has been passed, it returns API_TIMEOUT_ERR if it can safely and cleanly return from the middle of a long recognition before the hard timeout is reached. If it cannot then a separate thread terminates the possible infinite loop when the additional hard timeout period is over and the engine returns API_HARDTIMEOUT_ERR. In this case the engine might be in an unstable state so further normal functioning is not guaranteed. We suggest that the user terminates and restarts the process to be in a clean state again.

See also timeout handling in the tutorial.

---

Typedef Documentation

typedef RECERR RECKRNCALL PROGMON_CB(LPPROGRESSMONITOR mod, void *pContext)

The user-written progress monitoring callback function.

This user-written callback procedure for progress monitoring must be registered by the kRecSetCBProgMon function. The Engine will continually invoke this registered callback procedure during different workflow processes (PROCESSID), providing a pointer to a PROGRESSMONITOR structure that contains the current processing stage and a percentage indicator value. The application can provide progress indication for this procedure.

Parameters:

[in]	mod	This variable holds the current state of the activated action (ProcessID, progress information etc).
[in]	pContext	User data passed to the callback function by the Engine. The data to be passed can be set with kRecSetCBProgMon.

Return values:

API_PROCESS_ABORTED_ERR	The user has requested the current processing to be aborted: processing will stop at the first suitable moment.
REC_OK	Process can be continued normally.

Note:

Enabling progress monitoring in the integrating application during the recognition process might cause significant speed decrease especially for zones on small images when they are recognized with the recognition module RM_OMNIFONT_MTX.

The callback function must not contain calls to any KernelAPI functions.

---

Enumeration Type Documentation

enum KRECMODULES

Module identifiers.

Use the kRecGetModulesInfo function to get information on the current Engine configuration.

Enumerator:

INFO_API	Main KernelAPI API module.
INFO_MOR	The multi-lingual MOR omnifont recognition module. See RECOGNITIONMODULE.RM_OMNIFONT_MOR. Supported on: Windows, Linux.
INFO_DOT	9-pin draft dot-matrix recognition module. See RECOGNITIONMODULE.RM_DOT. Supported on: Windows.
INFO_BAR	Barcode recognition module. See RECOGNITIONMODULE.RM_BAR.
INFO_OMR	Optical mark recognition module. See RECOGNITIONMODULE.RM_OMR.
INFO_HNR	Handprinted numeral recognition module. See RECOGNITIONMODULE.RM_HNR. Supported on: Windows.
INFO_DCM	Legacy Automatic page-layout decomposition module. All platforms.
INFO_IMG	Image handling module. All platforms.
INFO_IMF	Image file I/O module. All platforms.
INFO_CHR	Character Set and Code Page handling module. All platforms.
INFO_DTXT	Direct Text output module. All platforms.
INFO_SPL	Spell Checking module. All platforms.
INFO_RSD	Scanning module. Supported on: Windows.
INFO_RER	Handprinted character recognition module. See RECOGNITIONMODULE.RM_RER. Supported on: Windows, Linux, Mac OS X.
INFO_MGR	Engine manager module. All platforms.
INFO_MTX	M/TEXT omnifont recognition module. See RECOGNITIONMODULE.RM_OMNIFONT_MTX. Supported on: Windows.
INFO_MAT	Matrix matching recognition module. See RECOGNITIONMODULE.RM_MAT. Supported on: Windows.
INFO_RESERVED_P	Internal use only. Must NOT be selected.
INFO_PLUS2W	2-way voting recognition module. See RECOGNITIONMODULE.RM_OMNIFONT_PLUS2W. All platforms.
INFO_FRX	FRX recognition module. See RECOGNITIONMODULE.RM_OMNIFONT_FRX. All platforms.
INFO_PLUS3W	3-way voting recognition module. See RECOGNITIONMODULE.RM_OMNIFONT_PLUS3W. Supported on: Windows, Linux.
INFO_ASN	Asian recognition module. See RECOGNITIONMODULE.RM_ASIAN.
INFO_XOCR	XOCR module. The standard page parse module. All platforms.
INFO_LFR	The logical form recognition module. Supported on: Windows, Linux, Embedded Linux.
INFO_ASP	Reserved.
INFO_SIZE	Number of modules.

enum PROCESSID

Progress identifiers.

Identifiers of the most important internal processes of the Engine, such as image loading, image saving, recognizing, etc. Each process listed below represents one of the fundamental services provided by the Engine. Applications will use one or more of these processes. Each process can be initiated by the relevant function (see below). The PROGMON_CB callback function can be used to generate progress monitoring for any of these processes.

Note:

While all the processes above offer progress monitoring, many other API functions do not, since they are not primary processes. The functions without progress monitoring are typically used to:

• inquire or make settings (kRecSetXX and kRecGetXX),
• perform a separate image pre-processing step on the Engine's hPage page, such as kRecDeskewImg, kRecRotateImg, kRecInvertImgArea. (Use kRecPreprocessImg instead if you need progress monitoring),
• transform the hPage to a new one, such as kRecConvertImg2BW or kRecTransformImg,
• transfer an image line-by-line between the image management module of the Engine and the application, such as kRecWriteImg, kRecReadImg, etc.

A timeout mechanism has been implemented for some processes. For more information see the kRecSetTimeOut function.

Recognition modules typically activate the PID_RECOGNITION2 process. The PID_RECOGNITION1 process is activated by the RM_OMNIFONT_MOR recognition module; PID_RECOGNITION3 process is activated by the RM_OMNIFONT_PLUS3W recognition module.

Enumerator:

PID_IMGINPUT	Identifies the Image loading process. The source can be the scanner, image file or image stored in the application buffer (application memory); kRecLoadImg, kRecLoadImgF.
PID_IMGSAVE	Identifies the image saving process. During this process the image or a part of it is saved to an image file; kRecSaveImg.
PID_IMGPREPROCESS	Identifies the Image preprocessing process; kRecPreprocessImg.
PID_DECOMPOSITION	Identifies the page-layout decomposition process; kRecLocateZones.
PID_RECOGNITION1	Identifies the 1st pass of the Recognition process; kRecRecognize.
PID_RECOGNITION2	Identifies the 2nd pass of the Recognition process; kRecRecognize using recognition engine PLUS2W or PLUS3W.
PID_RECOGNITION3	3rd pass of the Recognition process using recognition engine PLUS3W.
PID_SPELLING	Identifies the Checking process.
PID_FORMATTING	Page and Document formatting.
PID_WRITEFOUTDOC	Identifies the process for writing the recognized text to the final output document (to file or to memory); RecConvert2Doc.
PID_CONVERTIMG	Identifies the image conversion process activated by the PID_WRITEFOUTDOC process for saving the image of a graphical image zone to the word processor output document; RecConvert2Doc.
PID_SCANNER_WARMUP	scanner is warming up.

---

Function Documentation

int RECAPIKRN kRecCreateSettingsCollection

(

int

sid

)

Creating a new Settings Collection.

A Settings Collection is a container of the values of all settings of all modules of KernelAPI/APIPlus. See the settings API in KrnStsApi.h. All functions that have an effect on settings or are affected by settings receive a Settings Collection ID in the parameter list.

Parameters:

[in]

sid

The parent collection. If it is -1, the new collection will contain the settings with their default values. If it is the ID of an already existing collection, the values will be copied from it.

Return values:

int	ID of the created Settings Collection. -1 means CSDK cannot create new Settings Collection. The upper limit of the number of Settings Collections is 1000, however CSDK cannot create a new one also after kRecQuit (or before kRecInit).

Note:

The specification of this function in C# is:

 int kRecCreateSettingsCollection(int sid); 

The specification of this function in Java is:

 int kRecCreateSettingsCollection(int sid) 

RECERR RECAPIKRN kRecDeleteSettingsCollection

(

int

sid

)

Deleting a Settings Collection.

The kRecDeleteSettingsCollection function deletes the specified collection.

Parameters:

[in]

sid

Settings Collection ID.

Return values:

RECERR

Note:

See the description of Settings Collections.

The specification of this function in C# is:

 RECERR kRecDeleteSettingsCollection(int sid); 

The specification of this function in Java is:

 int kRecDeleteSettingsCollection(int sid) 

RECERR RECAPIKRN kRecFree

(

void *

pArray

)

Freeing memory objects.

The kRecFree function frees the memory object previously made available to the application with the assistance of a KernelAPI function.

Parameters:

[in]

pArray

Pointer to the data to be released.

Return values:

RECERR

Note:

pArray could be a pointer retrieved by any of the following functions: kRecGetLetters, kRecGetChoiceStr, kRecGetSuggestionStr, kRecGetFontFaceStr, kRecGetLetterPalette, kRecGetOCRZoneText, kRecGetOCRTableCellText, kRecGetImgArea, kRecGetImgAreaEx, kRecRotateImgArea, kRecRemovePunchHoles, kRecGetZoneLayout, kRecGetOCRZoneLayout, kRecGetZoneNodeArray, kRecGetOCRZoneNodeArray, kRecGetHSplitters, kRecGetVSplitters, kRecGetZoneName, kRecGetOCRZoneName, kRecGetZoneAttribute, kRecGetOCRZoneAttribute, kRecGetNextZoneAttribute, kRecGetNextOCRZoneAttribute, kRecGetZoneFormFieldName, kRecGetOCRZoneFormFieldName, kRecGetFormTemplateName, kRecGetTemplateAttribute, kRecGetNextTemplateAttribute, kRecGetMatchingInfo, kRecGetStringSetting, kRecGetLastErrorEx.

There is no such function in C#

RECERR RECAPIKRN kRecGetDoubleSetting	(	int	sid,
		LPCTSTR	setting,
		double *	the_value
	)

Accessing the current value of an STS_DOUBLE setting.

This function gets the value of the named double setting in the given Settings Collection.

Parameters:

[in]	sid	Settings Collection ID.
[in]	setting	Name of the setting.
[out]	the_value	Address of a variable to get the value of the setting.

Return values:

RECERR

Note:

This function does the same as kRecSettingGetHandle followed by kRecSettingGetDouble.

The specification of this function in C# is:

 RECERR kRecGetDoubleSetting(int sid, string setting, out double the_value); 

The specification of this function in Java is:

 int kRecGetDoubleSetting(int sid, String setting, double[] the_value) 

RECERR RECAPIKRN kRecGetIntSetting	(	int	sid,
		LPCTSTR	setting,
		int *	the_value
	)

Accessing the current value of an STS_INT or STS_ENUM or STS_BOOL setting.

This function gets the value of the named integer, enum or boolean setting in the given Settings Collection.

Parameters:

[in]	sid	Settings Collection ID.
[in]	setting	Name of the setting.
[out]	the_value	Address of a variable to get the value of the setting.

Return values:

RECERR

Note:

This function does the same as kRecSettingGetHandle followed by kRecSettingGetInt.

The specification of this function in C# is:

 RECERR kRecGetIntSetting(int sid, string setting, out int the_value); 

The specification of this function in Java is:

 int kRecGetIntSetting(int sid, String setting, int[] the_value) 

RECERR RECAPIKRN kRecGetModulesInfo	(	LPKRECMODULEINFO *	ppModules,
		size_t *	pSize
	)

Getting module information.

The kRecGetModulesInfo function obtains information about the available modules of Engine.

Parameters:

[in]	ppModules	Address of a pointer to the module information array.
[in]	pSize	Address of a variable holding the number of module information structures.

Return values:

RECERR

Note:

You may want to invoke this function just after calling the kRecInit function to see if any module initialization failed AND/OR to get the module version numbers. When the application uses the Engine's scanning services, call this function after calling the kRecScanInit function in order to get correct module information for the RSD scanning module. (See also scanner usage.)

During the initialization call, the engine tries to initialize all the modules. There can be two reasons why a module is not reported as available: when the module is missing or not licensed on that particular computer. When a module or one of its important files is missing, the initialization of that module fails. When there is no license for a module, even if all its files are present in the Engine binary directory, the initialization of that module fails.

If there is a zone whose associated recognition module has not been initialized/loaded properly, the kRecRecognize function returns with NO_TXT_WARN, signaling that there is at least one zone on the image whose content could not be recognized due to a non-functioning recognition module.

Example for checking the availability of OMR and PLUS3W modules:

    LPKRECMODULEINFO pModules;
    size_t size;
    INTBOOL bOMR_available = FALSE;
    INTBOOL bPLUS_available = FALSE;
    RECERR rc;
    rc = kRecSetLicense(YOUR_LICENSE_FILE, YOUR_OEM_CODE);
    if (REC_OK)
        rc = kRecInit(YOUR_COMPANY, YOUR_PRODUCT);
    if ((rc != REC_OK) && (rc != API_INIT_WARN) && (rc != API_LICENSEVALIDATION_WARN)) {
        printf("Engine initialization failed: %d.\n", rc);
        return;
    } else if (rc == API_INIT_WARN) {
        printf("Warning. Module initialization problem.\n");
    } else if (rc == API_LICENSEVALIDATION_WARN) {
        printf("End of grace period is coming...\n");
    }
    rc = kRecGetModulesInfo(&pModules, &size);

    if (pModules[INFO_OMR].Version > 0) {
        bOMR_available = TRUE;
    }
    if (pModules[INFO_PLUS3W].Version > 0) {
        bPLUS_available = TRUE;
    }

The specification of this function in C# is:

 RECERR kRecGetModulesInfo(out KRECMODULEINFO[] ppModules); 

The specification of this function in Java is:

 int kRecGetModulesInfo(ModuleInfoArray ppModules) 

RECERR RECAPIKRN kRecGetSerialNumber	(	LPTSTR	pSn,
		size_t	buflen
	)

The kRecGetSerialNumber function is used to learn the serial number string of the OmniPage CSDK v21. The Serial number is unique for each OmniPage CSDK v21 package.

Parameters:

[out]	pSn	Pointer to a buffer containing the serial number string.
[in]	buflen	Size of the buffer.

Return values:

RECERR

Note:

The Serial number is a 23-character long string including the terminating zero.

This function can only be used to learn the Serial number of the base toolkit - but not those of add-ons.

The specification of this function in C# is:

 RECERR kRecGetSerialNumber(out string sn); 

The specification of this function in Java is:

 int kRecGetSerialNumber(String[] pSn) 

RECERR RECAPIKRN kRecGetStringSetting	(	int	sid,
		LPCTSTR	setting,
		LPTSTR *	the_value
	)

Accessing the current value of an STS_STRING or STS_USTRING setting.

This function gets the value of the named string setting in the given Settings Collection.

Parameters:

[in]	sid	Settings Collection ID.
[in]	setting	Name of the setting.
[out]	the_value	Address of a pointer to a string which is allocated and filled by this function. The allocated memory must be released with kRecFree.

Return values:

RECERR

Note:

This function is similar to kRecSettingGetHandle followed by kRecSettingGetString or kRecSettingGetUString. The main difference is that this function allocates memory for the returned string. This memory must be released with kRecFree when it is no longer needed.

This function can accept both STS_STRING (UTF-8) and STS_USTRING (UTF-16) settings. The returned string is automatically converted to ANSI or Unicode, if needed.

The specification of this function in C# is:

 RECERR kRecGetStringSetting(int sid, string setting, out string the_value); 

The specification of this function in Java is:

 int kRecGetStringSetting(int sid, String setting, String[] the_value) 

RECERR RECAPIKRN kRecGetTimeOut	(	int	sid,
		LPDWORD	pTimeOut
	)

Getting timeout period.

The kRecGetTimeOut function gets the timeout period.

Parameters:

[in]	sid	Settings Collection ID.
[out]	pTimeOut	Time out period in milliseconds.

Return values:

RECERR

Note:

This function gets the value of the setting Kernel.Timeout. This setting can be changed by kRecSetTimeOut.

The specification of this function in C# is:

 RECERR kRecGetTimeOut(int sid, out uint TimeOut); 

The specification of this function in Java is:

 int kRecGetTimeOut(int sid, long[] pTimeOut) 

RECERR RECAPIKRN kRecGetUILang	(	char *	langbuff,
		size_t	buffersize
	)

The kRecGetUILang function gets the language of message strings.

Parameters:

[out]	langbuff	Contains the ISO/DIS 639-3 3-letter language ID of the UI language with a terminating zero. The default value is the machine's UI language.
[in]	buffersize	Size of the langbuff buffer. Should be 4 or more.

Return values:

RECERR

Note:

This function gets the value of the setting Global.UILanguage. This setting can be changed by kRecSetUILang.

The specification of this function in C# is:

 RECERR kRecGetUILang(out string lang); 

The specification of this function in Java is:

 int kRecGetUILang(String[] langbuff) 

int RECAPIKRN kRecGetVersion

(

void

)

Getting version.

The kRecGetVersion function gets the version of RecAPI.

Return values:

int	The version number.

Note:

The specification of this function in C# is:

 int kRecGetVersion(); 

The specification of this function in Java is:

 int kRecGetVersion() 

RECERR RECAPIKRN kRecInit	(	LPCTSTR	pCompanyName,
		LPCTSTR	pProductName
	)

Initializing KernelAPI.

The kRecInit function initializes the OmniPage CSDK. Except for (kRecSetLicense, kRecGetVersion) the functions of KernelAPI should not be called before initialization. This function enumerates the modules installed in the Engine Binary directory, determines the configuration of the Engine and initializes its modules. Use this function to implicitly bind the Engine to the application. When this function is used for the Engine initialization, the KernelAPI.lib (on Windows), libkernelapi.so (on Linux), or libkernelapi.dylib (on Macintosh) import library must be linked to the application.

Parameters:

[in]	pCompanyName	Name of the User's Company. It can be NULL. Default value: on Windows systems is OmniPage, on Linux systems is omnipage, on Mac OS X is OmniPage. It is used for creating a company-specific working folder for temporary and other files generated by KernelAPI.
[in]	pProductName	Name of the Product or Application. It can be NULL. Default value: on Windows systems is CSDK21, on Linux systems is csdk-21.0, on Mac OS X is CSDK-21.0. It is used for creating an application-specific working folder for temporary and other files generated by KernelAPI.

Return values:

RECERR

Note:

Calling the kRecInit from a DllMain function of a DLL is prohibited.

The return value may be API_INIT_WARN, which means an error in initialization of one of the modules. The kRecGetModulesInfo can give information about the initialization of each module. This is not an error, because the User's application may not require the module in question.

The return value may be API_LICENSEVALIDATION_WARN, which means the license validation cannot be checked and grace period will be expired in less than 30 days.

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. Supported on: Windows.

An alternative way for binding and initializing the Engine can be the module KernelAPIS. Supported on: Windows.

The specification of this function in C# is:

 RECERR kRecInit(string companyName, string productName); 

The specification of this function in Java is:

 int kRecInit(String pCompanyName, String pProductName) 

RECERR RECAPIKRN kRecLoadSettings	(	int	sid,
		LPCTSTR	pFileName
	)

Loading settings.

This function loads settings from a settings file into StsMan.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFileName	Filename of the setting file to be loaded.

Return values:

RECERR

Note:

This function sets all the settings to default and after this, it does the same as kRecSettingLoad.

The specification of this function in C# is:

 RECERR kRecLoadSettings(int sid, string pFileName); 

The specification of this function in Java is:

 int kRecLoadSettings(int sid, String pFileName) 

RECERR RECAPIKRN kRecQuit

(

void

)

Closing KernelAPI.

The kRecQuit function stops the OmniPage CSDK. It frees all the resources allocated by the Engine.

Return values:

RECERR

Note:

If the scanning module was also initialized, it requires a separate kRecScanQuit call.

The return value may be API_INIT_WARN, which means the OmniPage CSDK is not initialized.

The function kRecQuit removes all the Settings Collections, pending and user settings, and sets the remaining settings to default, so the setting states are the same after every subsequent kRecQuit - kRecInit pair. In previous versions of CSDK the kRecQuit did not perform these steps, thus after a subsequent kRecInit all the settings existed and had the same value as before the previous kRecQuit. This behaviour can be simulated in CSDK v16 or later doing a workaround: Before kRecQuit:

1. save the required setting values from the required Settings Collections,

After kRecInit:

1. create all the required user settings,
2. create the required Settings Collections,
3. load the proper setting files into the proper Settings Collections.

The specification of this function in C# is:

 RECERR kRecQuit(); 

The specification of this function in Java is:

 int kRecQuit() 

RECERR RECAPIKRN kRecSaveSettings	(	int	sid,
		LPCTSTR	pFileName
	)

Saving settings of KernelAPI.

This function saves the settings.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pFileName	File name of the setting file to be saved.

Return values:

RECERR

Note:

This function does the same as kRecSettingSave, when latter gets NULL for root HSETTING with a FALSE save-all and a FALSE append parameter. kRecSaveSettings is only for compatibility.

The specification of this function in C# is:

 RECERR kRecSaveSettings(int sid, string pFileName); 

The specification of this function in Java is:

 int kRecSaveSettings(int sid, String pFileName) 

RECERR RECAPIKRN kRecSetCBProgMon	(	int	sid,
		LPPROGMON_CB	pCallBack,
		void *	pContext
	)

Setting progress monitor.

The kRecSetCBProgMon functions sets the progress monitor callback function. The callback function is implemented by the application.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pCallBack	Pointer to a function. This function will be called for every progress indication.
[in]	pContext	This pointer value will be passed to the callback function as the 2nd parameter.

Return values:

RECERR

Note:

If the application is sensitive to processing time it may be more useful to avoid the usage of progress callback.

// A callback function for progress monitoring
RECERR RECKRNCALL ProgressIndi(LPPROGRESSMONITOR mon, void *pContext)
{
  int id = (int)mon->ProcessId;
  wsprintf(buff, "PROCESSID: %d %d%%",id, mon->Percent);
  // Update progress monitoring status on the screen here!
  if (USER_ABORT) {
    return API_PROCESS_ABORTED_ERR;
  }
  ...
  return REC_OK;
}

Note:

The specification of this function in C# is:

 RECERR kRecSetCBProgMon(int sid, PROGMON_CB callback); 

The specification of this function in Java is:

 int kRecSetCBProgMon(int sid, ProgressMonitorCallback pCallback) 

RECERR RECAPIKRN kRecSetDataPath

(

LPCTSTR

datapath

)

Setting the path of the data files.

There may be some cases, when the library files and the data files cannot be in the same folder (e.g. on Android platform). In such a case this function can be used for specifying the path of the data files.

• On Android platform this has to be set by the User.
• On Mac OS X platform this is automatically found inside the framework by the OP CSDK. So this fucntion is typically not necessary to be called.
• On Linux and Embedded Linux platforms the default of this path is the library path.
• On Windows this function is not supported.

  Parameters:

  [in]

  datapath

  absolute path name of the data path.

  Return values:

  RECERR

  Note:

  This function is available only on Linux, Embedded Linux, Mac OS X and Android.

  See also kRecSetLibraryPath.

  The specification of this function in C# is:

   RECERR kRecSetDataPath(string dataPath); 
  

  The specification of this function in Java is:

   int kRecSetDataPath(String datapath) 
  

RECERR RECAPIKRN kRecSetDefaults

(

int

sid

)

Changing settings of KernelAPI to default.

This function changes the settings of the KernelAPI (i.e. the subtree under the node "Kernel" of the setting tree) to their default values.

Parameters:

[in]

sid

Settings Collection ID.

Return values:

RECERR

Note:

This function does the same as kRecSettingSetToDefault, when latter gets the HSETTING of node "Kernel" with a TRUE whole-subtree parameter. It is only for compatibility.

The specification of this function in C# is:

 RECERR kRecSetDefaults(int sid); 

The specification of this function in Java is:

 int kRecSetDefaults(int sid) 

RECERR RECAPIKRN kRecSetDoubleSetting	(	int	sid,
		LPCTSTR	setting,
		double	new_value
	)

Setting the value of an STS_DOUBLE setting.

This function sets the value of the named double setting in the given Settings Collection.

Parameters:

[in]	sid	Settings Collection ID.
[in]	setting	Name of the setting.
[in]	new_value	The new value to be set.

Return values:

RECERR

Note:

This function does the same as kRecSettingGetHandle followed by kRecSettingSetDouble.

The specification of this function in C# is:

 RECERR kRecSetDoubleSetting(int sid, string setting, double new_value); 

The specification of this function in Java is:

 int kRecSetDoubleSetting(int sid, String setting, double new_value) 

RECERR RECAPIKRN kRecSetIntSetting	(	int	sid,
		LPCTSTR	setting,
		int	new_value
	)

Setting the value of an STS_INT or STS_ENUM or STS_BOOL setting.

This function sets the value of the named integer, enum or boolean setting in the given Settings Collection.

Parameters:

[in]	sid	Settings Collection ID.
[in]	setting	Name of the setting.
[in]	new_value	The new value to be set.

Return values:

RECERR

Note:

This function does the same as kRecSettingGetHandle followed by kRecSettingSetInt.

The specification of this function in C# is:

 RECERR kRecSetIntSetting(int sid, string setting, int new_value); 

The specification of this function in Java is:

 int kRecSetIntSetting(int sid, String setting, int new_value) 

RECERR RECAPIKRN kRecSetLibraryPath

(

LPCTSTR

libpath

)

Setting the path of the library files.

There may be some cases, when the library files and the data files cannot be in the same folder (e.g. on Android platform). In such a case this function may be used for specifying the path of the library files.

• On Android platform this has to be set by the User.
• On Linux, Embedded Linux and Mac OS X platforms this is automatically found by the OP CSDK, so this function is not suggested to be called.
• On Windows this function is not supported.

  Parameters:

  [in]

  libpath

  absolute path name of the library path.

  Return values:

  RECERR

  Note:

  This function is available only on Linux, Embedded Linux, Mac OS X and Android.

  See also kRecSetDataPath.

  The specification of this function in C# is:

   RECERR kRecSetLibraryPath(string libPath); 
  

  The specification of this function in Java is:

   int kRecSetLibraryPath(String libpath) 
  

RECERR RECAPIKRN kRecSetLicense	(	LPCTSTR	pLicenseFile,
		LPCTSTR	pCode
	)

Setting the OEM license information.

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

Parameters:

[in]	pLicenseFile	Name of the license file or the fully qualified path to the license file (an LCX or LCXZ file). This parameter can be NULL if the OEM license file is loaded by OPLicMgr or OmniPage License Agent used, but this functioning is not suggested.
[in]	pCode	OEM Code string. (It is a pointer to the string itself, not to the file name containing the OEM Code!)

Return values:

RECERR

Note:

If the integrating application calls more than one kRecInitkRecQuit pair subsequently, this function is required to be called only before the first kRecInit.

The return value may be API_INIT_WARN, which means that OmniPage CSDK has been already initialized.

Licensing is fully described in the General Information help system.

1. Development Licensing on Windows: this function must not be called.
   (Note that in case of other operating systems development licenses are OEM-type ones that are processed by this function. See Platforms.)
2. Seat Licensing: this function must not be called.
3. OEM Licensing: The license file itself and a C header file containing the OEM Code string are generated by the OPLicMgr. This type of licensing enables pre-activated licensing. It eliminates the need for on-site license activation that is necessary with Seat Licensing.

If pLicenseFile is neither NULL nor a full path file name but a relative path or simply 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 OmniPage CSDK directory inside the COMMON_APPDATA folder. This folder depends on the OS:
   • Windows: the "OmniPage\\\productname\\" subdirectory under the path returned by SHGetFolderPath(NULL, CSIDL_COMMON_APPDATA, NULL, 0, folderBuffer);
   • Linux: $HOME/.omnipage-csdk-21.0
   • Mac OS X: $HOME/.OmniPage-CSDK-21.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 paths will change to reflect the actual version.)

The specification of this function in C# is:

 RECERR kRecSetLicense(string pLicenseFile, string pCode); 

The specification of this function in Java is:

 int kRecSetLicense(String pLicenseFile, String pCode) 

RECERR RECAPIKRN kRecSetSandboxHomePath

(

const char *

homepath

)

Setting the Sandbox path on MacOS.

The kRecSetSandboxHomePath function sets the Sandbox Home path. This function must be called before any other functions.

Parameters:

[in]

homepath

The application's Home path as returned by the NSHomeDirectory function. The string must be converted to UTF-8 by the UTF8String message.

Return values:

RECERR

Note:

In most cases the OmniPage CSDK finds the Sandbox home path correctly by reading the HOME environment variable, but sometimes this variable is missing. For correct operations you have to use this function for example this way in Objective-C:

        kRecSetSandboxHomePath([NSHomeDirectory() UTF8String]);

This function is available on Mac OS X only

RECERR RECAPIKRN kRecSetSandboxTempPath

(

const char *

temppath

)

Setting the Sandbox temporary path on MacOS.

The kRecSetSandboxTempPath function sets the Sandbox Temporary path. This function must be called after kRecSetSandboxHomePath and before any other functions.

Parameters:

[in]

temppath

The application's Temporary path as returned by the NSTemporaryDirectory function. The string must be converted to UTF-8 by the UTF8String message.

Return values:

RECERR

Note:

In most cases the OmniPage CSDK finds the Sandbox temporary path correctly by reading the TMPDIR environment variable, but sometimes this variable is missing. For correct operations you have to use this function for example this way in Objective-C:

        kRecSetSandboxTempPath([NSTemporaryDirectory() UTF8String]);

This function is available on Mac OS X only

RECERR RECAPIKRN kRecSetStringSetting	(	int	sid,
		LPCTSTR	setting,
		LPCTSTR	new_value
	)

Setting the value of an STS_STRING or STS_USTRING setting.

This function sets the value of the named string setting in the given Settings Collection.

Parameters:

[in]	sid	Settings Collection ID.
[in]	setting	Name of the setting.
[in]	new_value	The new value to be set. It will be copied into an internal buffer in StsMan.

Return values:

RECERR

Note:

This function does the same as kRecSettingGetHandle followed by kRecSettingSetString.

This function can accept both STS_STRING and STS_USTRING settings. The given new_value is automatically converted to either UTF-8 or Unicode, if needed.

The specification of this function in C# is:

 RECERR kRecSetStringSetting(int sid, string setting, string new_value); 

The specification of this function in Java is:

 int kRecSetStringSetting(int sid, String setting, String new_value) 

RECERR RECAPIKRN kRecSetTimeOut	(	int	sid,
		DWORD	TimeOut
	)

Setting timeout period.

The kRecSetTimeOut function sets the time out period for different tasks.

Parameters:

[in]	sid	Settings Collection ID.
[in]	TimeOut	Timeout period in milliseconds. The suggested minimum limit of this setting is 50 milliseconds, but it may be useful to set the timeout higher on server operating systems.

Return values:

RECERR

Note:

The value specified here allows a module to process an image for no longer than the time specified. When the TimeOut value is reached, the Engine terminates the running of the appropriate module and resets it. The calling function returns with the API_TIMEOUT_ERR return code to the integrating application signaling that the processing of the image could not be successfully completed.

This feature is applied to the following processes:

• image pre-processing (PID_IMGPREPROCESS process),
• page-layout decomposition, also known as auto-zoning or page parsing (PID_DECOMPOSITION), and
• recognition (PID_RECOGNITION1, PID_RECOGNITION2 and PID_RECOGNITION3 processes).

The description of timeout handling gives more information e.g. about hard timeout. See also the tutorial.

Though disabling the Engine timeout feature (by calling this function with the INFINITE parameter) may speed up the Engine's initialization, it is recommended to enable the watch-dog mechanism.

If this function is not called to specify the module timeout setting, the default value of this setting, 180000 milliseconds (3 minutes), is applied, i.e. no internal process will be allowed to continue for more than three minutes.

If the application is sensitive to processing time, set the time-out to -1 (INFINITE). In this case, no watch-dog thread will be started and there will not be thread context switches in progress callbacks.

This function sets the value of the setting Kernel.Timeout. This setting can be retrieved by kRecGetTimeOut.

The specification of this function in C# is:

 RECERR kRecSetTimeOut(int sid, uint TimeOut); 

The specification of this function in Java is:

 int kRecSetTimeOut(int sid, long TimeOut) 

RECERR RECAPIKRN kRecSetUILang

(

const char *

lang

)

Setting the language of displayed information.

The kRecSetUILang function sets the language of message strings.

Parameters:

[in]

lang

ID of the language. This is any language description string accepted by kRecFindLanguage or kRecFindLanguageEx. Use NULL to reset to the default UI language of the user's machine.

Return values:

RECERR

Note:

This function sets the value of the setting Global.UILanguage. This setting can be retrieved by kRecGetUILang.

If the specified language is illegal then the function returns an error and English is used. See also the kRecGetErrorUIText function.

The specification of this function in C# is:

 RECERR kRecSetUILang(string lang); 

The specification of this function in Java is:

 int kRecSetUILang(String lang)