Skip to main content
This function is used to get a pointer to the IEngine interface. It takes as an input parameter the Customer Project ID number, which is an alphanumeric string common to all the Developer and Runtime licenses your project uses.
For Linux and Windows users, this function provides easy access to online licensing if needed and also allows you to specify some additional parameters during initialization.

​
Syntax

​
C++

HRESULT __stdcall InitializeEngine(
  BSTR CustomerProjectID,
  BSTR LicensePath,
  BSTR LicensePassword,
  BSTR FREngineDataFolder,
  BSTR FREngineTempFolder,
  VARIANT_BOOL IsSharedCPUCoresMode,
  IEngine** Engine
);

​
C#

int InitializeEngine(
  string CustomerProjectID,
  string LicensePath,
  string LicensePassword,
  string FREngineDataFolder,
  string FREngineTempFolder,
  bool IsSharedCPUCoresMode,
  ref IEngine Engine
);

​
Visual Basic .NET

Private Declare Function InitializeEngine Lib "FREngine.dll" ( _
  CustomerProjectID As String, _
  LicensePath As String, _
  LicensePassword As String, _
  FREngineDataFolder As String, _
  FREngineTempFolder As String, _
  IsSharedCPUCoresMode As Boolean, _
  ByRef Engine As FREngine.IEngine) _
As Integer

​
Parameters

CustomerProjectID [in] A string containing the Customer Project ID.
During library initialization the list of all available licenses is searched for a Developer or Runtime License corresponding to this Customer Project ID. If no corresponding license is found, an error for the last checked license will occur. However, you may pass 0 for this parameter and select the license later, by calling the IEngine::SetCurrentLicense method before any other library methods.
LicensePath [in] The full file name of the Online License file. If you do not use an Online License, pass an empty string "" or a Null pointer instead. The empty string "" or Null pointer should be passed. For macOS users: This parameter is reserved for future use. LicensePassword [in] The Online License password. If you do not use an Online License, pass an empty string "" or a Null pointer instead. For macOS users: This parameter is reserved for future use. FREngineDataFolder [in] Contains the path to the folder in which ABBYY FineReader Engine should store user-specific data. By default, for automatic installation: %ProgramData%\ABBYY\SDK\12\FineReader Engine for auxiliary engine data In addition, for Linux and Windows: %ProgramData%\ABBYY\SDK\12\Licenses for license data If you set the FREngineDataFolder value, all auxiliary information will be written to a new data folder. You may need to change the default value, for example, if the interface language settings for your application must be different from other applications that use FineReader Engine. After changing the default, make sure you have full control permissions on the new data folder. FREngineTempFolder [in] Contains the path to the folder for ABBYY FineReader Engine temporary files. By default, it is %TEMP%\ABBYY FineReader Engine 12 folder. IsSharedCPUCoresMode [in] Specifies whether the CPU cores should be used in shared mode. There are two modes of CPU cores usage: separate and shared. In separate mode ABBYY FineReader Engine uses no more processes than it is allowed by the license. In shared mode any number of processes can be run, but all these processes will use only the CPU cores specified by the IMultiProcessingParams::SharedCPUCoresMask property.
This parameter is ignored in ABBYY FineReader Engine for Windows.
Engine [out, retval] A pointer to IEngine* pointer variable that receives the interface pointer to the resulting Engine object.

​
Return values

The function may return the standard return values of ABBYY FineReader Engine functions.

​
Remarks

Only one Engine object may be created using this function in a single instance of the application that uses ABBYY FineReader Engine. Repeated attempts to create the Engine object will return the same object.
Creating the Engine object may take noticeable time. During initialization, the engine loads the main library listed below along with a large number of additional dynamic libraries:
  • Linux: libFREngine.so
  • macOS: libFREngine.dylib
  • Windows: FREngine.dll
When using a network license, initialization in Linux and Windows may also take longer due to communication with the license server. Ensure the network connection meets the required performance; a bandwidth of at least 100 Kb/s is recommended for reliable operation with a network license.
It is possible to create and run the Engine object on a multi-processor system, but there can be only one Engine object in each process. A second call to InitializeEngine within the same process will return the reference to the existing object. Therefore, you should create a separate Engine object for each process by calling the InitializeEngine function.
For ABBY FineReader Engine for Windows implementations involving multi-processor systems, you may find useful other methods of loading the Engine object.
Do not initialize and deinitialize ABBYY FineReader Engine at the entry points of other dynamic libraries and also in constructors and destructors of static and global objects implemented in dynamic libraries, because they are called at the dynamic library entry points.
A user should initialize and deinitialize ABBYY FineReader Engine elsewhere. For example, in the main or WinMain function of an executable module.
: In Windows, this restriction is due to the fact that the Win32 LoadLibrary and FreeLibrary functions are not re-entrant.
During initialization ABBYY FineReader Engine will reset the LC_CTYPE setting to operating system defaults. This fact should be taken into account if your application depends upon locale-dependent services (specifically msvcrt.dll in Windows). Windows developers using .NET must make sure to specify [STAThread] (single-thread apartment model) as an attribute on the application main function; otherwise, an error may occur: 
[STAThread]
public static void Main()
{
  ...
}
You should pass a valid Customer Project ID number as an input parameter. However, you may choose the license which should be used for processing, by calling the SetCurrentLicense method of the Engine object before any of the processing methods. Use the GetAvailableLicenses method to look through the list of the available activated licenses you may use, and the CurrentLicense property of the Engine object to check which license is already selected for use.

​
Samples

// Initialize these variables with the path to FREngine.dll, your FineReader Engine customer project ID,
// and, if applicable, the path to the Online License token and Online License password
wchar_t* FreDllPath;
wchar_t* CustomerProjectId;
wchar_t* LicensePath;  // if you don't use an Online License, assign empty strings to these variables
wchar_t* LicensePassword;
// HANDLE to FREngine.dll
static HMODULE libraryHandle = 0;
// Global FineReader Engine object.
FREngine::IEnginePtr Engine;
void LoadFREngine()
{
    if( Engine != 0 ) {
    // Already loaded
    return;
    }
    // First step: load FREngine.dll
    if( libraryHandle == 0 ) {
        libraryHandle = LoadLibraryEx( FreDllPath, 0, LOAD_WITH_ALTERED_SEARCH_PATH );
        if( libraryHandle == 0 ) {
            throw L"Error while loading ABBYY FineReader Engine";
        }
    }
    // Second step: obtain the Engine object
    typedef HRESULT ( STDAPICALLTYPE* InitializeEngineFunc )( BSTR, BSTR, BSTR, BSTR, 
        BSTR, VARIANT_BOOL, FREngine::IEngine** );
    InitializeEngineFunc pInitializeEngine =
    ( InitializeEngineFunc )GetProcAddress( libraryHandle, "InitializeEngine" );
    if( pInitializeEngine == 0 || pInitializeEngine( CustomerProjectId, LicensePath, 
        LicensePassword, L"", L"", VARIANT_FALSE, &Engine ) != S_OK ) {
    UnloadFREngine();
    throw L"Error while loading ABBYY FineReader Engine";
    }
}

public class EngineLoader : IDisposable
{
    public EngineLoader()
    {
        // Initialize these variables with the full path to FREngine.dll, your Customer Project ID,
        // and, if applicable, the path to your Online License token file and the Online License password
        string enginePath = "";
        string customerProjectId = "";
        string licensePath = "";
        string licensePassword = "";
        // Load the FREngine.dll library
        dllHandle = LoadLibraryEx(enginePath, IntPtr.Zero, LOAD_WITH_ALTERED_SEARCH_PATH);
           
        try
        {
            if (dllHandle == IntPtr.Zero)
            {
                throw new Exception("Can't load " + enginePath);
            }
            IntPtr initializeEnginePtr = GetProcAddress(dllHandle, "InitializeEngine");
            if (initializeEnginePtr == IntPtr.Zero)
            {
                throw new Exception("Can't find InitializeEngine function");
            }
            IntPtr deinitializeEnginePtr = GetProcAddress(dllHandle, "DeinitializeEngine");
            if (deinitializeEnginePtr == IntPtr.Zero)
            {
                throw new Exception("Can't find DeinitializeEngine function");
            }
            IntPtr dllCanUnloadNowPtr = GetProcAddress(dllHandle, "DllCanUnloadNow");
            if (dllCanUnloadNowPtr == IntPtr.Zero)
            {
                throw new Exception("Can't find DllCanUnloadNow function");
            }
            // Convert pointers to delegates
            initializeEngine = (InitializeEngine)Marshal.GetDelegateForFunctionPointer(
                initializeEnginePtr, typeof(InitializeEngine));
            deinitializeEngine = (DeinitializeEngine)Marshal.GetDelegateForFunctionPointer(
                deinitializeEnginePtr, typeof(DeinitializeEngine));
            dllCanUnloadNow = (DllCanUnloadNow)Marshal.GetDelegateForFunctionPointer(
                dllCanUnloadNowPtr, typeof(DllCanUnloadNow));
            // Call the InitializeEngine function 
            // passing the path to the Online License file and the Online License password
            int hresult = initializeEngine(customerProjectId, licensePath, licensePassword, 
                "", "", false, ref engine);
            Marshal.ThrowExceptionForHR(hresult);
        }
        catch (Exception)
        {
            // Free the FREngine.dll library
            engine = null;
            // Deleting all objects before FreeLibrary call
            GC.Collect();
            GC.WaitForPendingFinalizers();
            GC.Collect();
            FreeLibrary(dllHandle);
            dllHandle = IntPtr.Zero;
            initializeEngine = null;
            deinitializeEngine = null;
            dllCanUnloadNow = null;
            throw;
        }
    }
    // Kernel32.dll functions
    [DllImport("kernel32.dll")]
    private static extern IntPtr LoadLibraryEx(string dllToLoad, IntPtr reserved, uint flags);
    private const uint LOAD_WITH_ALTERED_SEARCH_PATH = 0x00000008;
    [DllImport("kernel32.dll")]
    private static extern IntPtr GetProcAddress(IntPtr hModule, string procedureName);
    [DllImport("kernel32.dll")]
    private static extern bool FreeLibrary(IntPtr hModule);
    // FREngine.dll functions
    [UnmanagedFunctionPointer(CallingConvention.StdCall, CharSet = CharSet.Unicode)]
    private delegate int InitializeEngine(string customerProjectId, string licensePath, 
        string licensePassword, string tempFolder, string dataFolder, bool isSharedCPUCoresMode, 
        ref FREngine.IEngine engine);
    [UnmanagedFunctionPointer(CallingConvention.StdCall)]
    private delegate int DeinitializeEngine();
    [UnmanagedFunctionPointer(CallingConvention.StdCall)]
    private delegate int DllCanUnloadNow();
    // private variables
    private FREngine.IEngine engine = null;
    // Handle to FREngine.dll
    private IntPtr dllHandle = IntPtr.Zero;
    private InitializeEngine initializeEngine = null;
    private DeinitializeEngine deinitializeEngine = null;
    private DllCanUnloadNow dllCanUnloadNow = null;
}
The function is used in all code samples except EnginesPool (Win).

​
See also

Licensing Modules DeinitializeEngine Different Ways to Load the Engine Object (Win)