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	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.

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 sessions 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.

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 100, 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);

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);

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, kRecGetLastErrorEx.; There is no such function in C#

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);

RECERR RECAPIKRN kRecGetSerialNumber	(	LPTSTR	pSn,
		size_t	buflen
	)

The kRecGetSerialNumber function is used to learn the serial number string of the OmniPage CSDK v20. The Serial number is unique for each OmniPage CSDK v20 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);

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);

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);

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();

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 `Nuance`, on Linux systems is `nuance`, on Mac OS X is `Nuance`. 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 `OmniPageCSDK20`, on Linux systems is `omnipage-csdk-20.0`, on Mac OS X is `OmniPage-CSDK-20.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);

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);

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:

save the required setting values from the required Settings Collections,

After kRecInit:

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

The specification of this function in C# is:

 RECERR 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);

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);

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);

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 the Nuance Licensing Tool (NLT), 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 kRecInit kRecQuit 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.

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.)
Fixed Volume Licensing: this function must not be called.
OEM Licensing: The license file itself and a C header file containing the OEM Code string are generated by the NLT or OPLicMgr. This type of licensing enables pre-activated licensing. It eliminates the need for on-site license activation that is necessary with Fixed Volume 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:

Next to the application itself (exe file in Windows).
Next to the Engine libraries (dll files in Windows). In several cases this is the same as the previous path.
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 paths will change to reflect the actual version.)

The specification of this function in C# is:

 RECERR 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 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);

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. 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);

Classes

Modules

Typedefs

Enumerations

Functions

Detailed Description

Timeout handling

Typedef Documentation

Enumeration Type Documentation

Function Documentation