Initialization

Any operation of the Capture SDK is accessible only after an initialization step, performed by kRecInit (on this layer), which determines the available modules of the Engine, initializes them and starts all the modules, which are licensed and found in the Engine Binary directory.

The initialization step has a quitting pair kRecQuit.

Having successfully initialized the Engine, the next step is to check the availability of the required modules of the Engine. A module is reported as not available if either there is no license on the computer for it, or when one or more files belonging to the particular module are not present in the current Engine configuration. To check the availability of the modules, use the kRecGetModulesInfo function, which gives information about the given module and the result error code of its initialization. If the kRecInit routine finds a partially installed system, some functions may later return an error code.

If the integrating application uses scanners it also has to initialize the Scanning Module calling kRecScanInit, which has a quitting pair kRecScanQuit. Only the Scanner Module requires additional initialization from the modules of the Engine.

The Scanning Module is supported on: Windows.

An alternative way to use the page-level API of the Capture SDK is dynamic linking using the module KernelAPIS.

Note:: The following example shows a typical initialization section:

    // Initialize engine.
    RECERR rc = kRecInit(YOUR_COMPANY, YOUR_PRODUCT);

    // Test for errors.
    if ((rc != REC_OK) && (rc != API_INIT_WARN) && (rc != API_LICENSEVALIDATION_WARN))
    {
        // Error occured.
        printf("Error in initialization.\n");
        printf("Error code = %X\n", rc);
        kRecQuit();
        return;
    }
    else if (rc == API_INIT_WARN)
    {
        // There are some not initialized modules.
        printf("Module initialization warning. One or more\n");
        printf("recognition modules have not been initialized properly.\n");

        // Get module information.
        LPKRECMODULEINFO pModules;
        size_t size;
        kRecGetModulesInfo(&pModules, &size);

        // Test whether the needed module is initialized or not.
        if(pModules[INFO_BAR].InitError)
        {
            printf("BAR module is not initialized.\n");
            kRecQuit();
            return;
        }
    }
    else if (rc == API_LICENSEVALIDATION_WARN)
    {
        printf("End of grace period is coming...\n");
    }

Error handling

Each function call in the Capture SDK returns with REC_OK (zero) on successful completion, otherwise the returned value is an error code of RECERR. The application program should always check the return values of the RecAPI functions to ensure that each function has successfully completed its operation.

For the sake of brevity, the sample code fragments presented in this tutorial (and also in this documentation) typically do not contain any error handling; only the presence of the return code assignments reminds you that you should implement some error handling.

Threading

The Engine of the Capture SDK is thread-safe since version 16 (supported on: Windows).

RecAPI functions can be called from different threads. For more information, see the topic Multi-threading in RecAPI.

Timeout

The Capture SDK provides an Engine-wide module timeout setting. This implements a watch-dog feature for avoiding rare but annoying dead-lock situations (infinite loops).

It can be set through the function kRecSetTimeOut. In the current release this feature is applied for 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 timeout setting can be set to a value in milliseconds or INFINITE. Specifying the INFINITE timeout value disables the watch-dog mechanism in the Engine. Disabling the timeout feature may speed up the recognition a little bit. The slowing could become significant only when recognizing a lot of small-size images successively.

The supported modules will be allowed to process an image for no longer than the time specified. When the limit 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 calling application. This signals that the processing of the image could not be successfully completed.

If this function is not called to specify the module timeout setting, the default value of this setting, 180000 milliseconds (3 minutes) is used.

The description of timeout handling gives more information e.g. about hard timeout.

Setting handling

Only a small set of API functions perform real actions in the Engine, like image loading, recognizing, etc. The majority of the function entries are used to set or retrieve the value of Engine settings used to customize Engine behavior.

From CSDK v15, there is an individual module (Settings Manager Module - StsMan) for handling all the settings of the Engine, but there are many functions (partly for backward compatibility) for modifying or retrieving the value of these settings as well (kRecSetXX, kRecGetXX).

The settings are collected in a setting tree, in which any setting can be found by its name. After getting a setting, it can be accessed through a handle HSETTING, which is required for any operation of StsMan. Each setting has a symbolic name (also defining its location in the tree), a type, flags (for determining its working), a default value (which is a permanent, non-changeable property) and a current value (which is changeable).

The CSDK v15 introduced the notion of Settings Collections (SC). A SC is like a profile, it contains a state of the set of all the settings, more precisely their current values. There can be more than one SC in use at the same time, and different SC's may contain different current values of the same settings. A SC can be identified by a Settings Collection ID (SID). All API functions modifying or retrieving settings has a SID parameter that defines the SC they relate to.

When the engine is initialized, these settings will be set to their default values and exactly one SC is created (with 0 ID). The integrating application can create its own SC's by kRecCreateSettingsCollection and delete them by kRecDeleteSettingsCollection.

After changing the value of a setting in a given SC, the new value remains in effect in that SC until it is changed again.

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.

Most kRecGetXX functions have minimal documentation, because the description of their pair (kRecSetXX) contains the information.

The full range of current settings can be saved to file at any time from any SC through kRecSaveSettings or kRecSettingSave. Any number of such setting files can be stored and can be loaded later by kRecLoadSettings or kRecSettingLoad into a specified SC. The setting file is an ASCII file, it can be modified manually, but it is recommended to avoid this and to use the API functions for changing setting values, because there are some setting types whose values are specially converted to string format.

The kRecSetDefaults and kRecSettingSetToDefault functions can be used to re-initialize all settings of the Engine to their default values.

IMPORTANT NOTE: Loading a settings file changes only the value of the settings that are in the file. Thus if a setting missing from the file was changed before loading, its value is not affected by the loading operation. If the settings file does not contain all the settings, the setting status as it was at saving time can be fully reproduced by calling kRecSettingSetToDefault before kRecSettingLoad. See kRecSettingLoad and kRecSettingSave for details.

Note:: The following sample code demonstrates the most important operations of the settings.

    int MySpecialInit ()
    {
        HSETTING hdtxt_outformat, hmy_output_name;
        RECERR err = REC_OK;
        DTXTOUTPUTFORMATS dtxt_outformat = DTXT_TXTS;
        int my_session = kRecCreateSettingsCollection(0);

        //Creating a string setting (the NULL root is equal to the root of the whole
        //tree). This setting will not be saved into a file (DONTSAVE flag).
        err = kRecSettingCreateString(&hmy_output_name, NULL, "MyIni.Output.Name",
            STSFLG_DONTSAVE, "path/out.txt");
        ...
        //Loading a setting file.
        err = kRecSettingLoad(my_session, "last_opt.sts");
        ...
        //Getting the handle of a setting. The passed name must be relative to the
        //root of the query, which is equal to the root of the whole tree here. The INTBOOL parameter
        //has_setting (here NULL) indicates whether the node has a setting or not.
        err = kRecSettingGetHandle(NULL, "Kernel.DTXT.DirectTxtFormat", &hdtxt_outformat, NULL);
        if (err == REC_OK)
            //Getting the value of an enum (int) setting.
            err = kRecSettingGetInt(my_session, hdtxt_outformat, (int *)&dtxt_outformat);
        ...
        //Setting the value of our own string setting created above.
        switch (dtxt_outformat)
        {
        case DTXT_TXTF:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/rtf/out.txt");
            break;
        case DTXT_TXTCSV:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/html/out.csv");
            break;
        case DTXT_PDFIOT:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/pdf/out.pdf");
            break;
        case DTXT_XMLCOORD:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/xml/out.xml");
        break;
        case DTXT_BINARY:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/html/out.bin");
            break;
        default:
            //Setting the value to default. (FALSE is for indicating that only the given
            //setting must be set to default and not the whole subtree, whose root is the given
            //setting.)
            err = kRecSettingSetToDefault(my_session, hmy_output_name, FALSE);
        }
        ...
        //Every initialisation step of this function is done in the session created
        //above. Thus it must be retrieved to a location outside this function.
        return my_session;
    }

Note:

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 do these steps, thus after a subsequent kRecInit all the settings existed and had the same value as before the previous kRecQuit. We think, the integrating applications generally want the situation after any kRecInit to be the same, that is why this change of operation was performed. If the integrating application expect the v15 behavior (e.g. it was developed under CSDK 15), this can be simulated also in CSDK v16 or later doing the next 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.

Progress indication

Typically the most time-consuming processes invoked by the Engine are the recognition processes and the final output document generation. In some particular cases, other processes like image loading or image preprocessing might also take considerable time.

Sometimes it is advisable to provide the application user with feedback about these processes. The application can register callback procedures for progress monitoring with the kRecSetCBProgMon function. The Engine will invoke the registered callback procedure during processing with a pointer to a PROGRESSMONITOR structure containing information about the current process. The application can provide progress indication with this procedure. If the callback function returns a value other than REC_OK, it signals an interruption of the current process. This can be used to provide the application user with a cancel button.