InitializeEngine Function
This function is used to get a pointer to the IEngine interface. It provides easy access to online licensing if needed and also allows you to specify some additional parameters during initialization. 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.
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.
-
Note: 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.
- LicensePassword
- [in] The Online License password. If you do not use an Online License, pass an empty string "" or a Null pointer instead.
- 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
%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.
- 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.
Important! Please notice that the process of creation of the Engine object takes rather long time because it requires loading not only the FREngine.dll, but a whole set of other DLLs. Intensive networking with the license server can take long in case you use network license. Make sure that your network performance meets requirements: for sufficiently rapid work with network license speed 100 Kb/s and more is required.
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 multi-processor systems, you may find useful other methods of loading the Engine object.
It is prohibited to initialize and deinitialize ABBYY FineReader Engine at the entry points of other DLLs, and also in constructors and destructors of static and global objects implemented in DLLs, because they are called at the DLL entry points. This restriction is due to the fact that the Win32 LoadLibrary and FreeLibrary functions are not re-entrant. A user should initialize and deinitialize ABBYY FineReader Engine elsewhere, for example, in WinMain function of an EXE module.
During initialization ABBYY FineReader Engine will reset the LC_CTYPE setting of msvcrt.dll to operating system defaults. This fact should be taken into account if your application depends upon the msvcrt.dll locale-dependent services.
.NET developers 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
C++ (COM) code
C# code
The function is used in all code samples except EnginesPool.
See also
17.09.2024 15:14:41