Programming Aspects

This section describes the main aspects of using ABBYY FineReader Engine in applications written in different programming languages and provides references to articles that discuss related topics.

The FRE for Windows application programming interface conforms to the COM standard and can be used in C/C++, .NET, Java or any development tool supporting COM components. The Engine can also be adapted for use in scripting languages like VBS, JS, Perl.

FRE for Linux can be used in C/C++ and Java programming languages.

Loading, initialization, and deinitialization

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 the operating system defaults. This fact should be taken into account if your application depends upon locale-dependent services.

In Windows , FRE resets the LC_CTYPE setting of msvcrt.dll.

The “Engine deinitialization failed” exception can be thrown during the deinitialization of the Engine object if not all of the objects which were created and used by the application have been deleted before the Engine object deinitialization. If you work with programming languages which do not have garbage collection (for example, C++), you must either use smart pointer classes (For Windows, see the samples in C++ (COM)) or release objects that were created by creation methods when they are no longer needed. If all the objects have been deleted, the exception may be caused by the garbage collector operation. If the application is developed in Windows with Visual Basic .NET, all objects with the Nothing value are only marked for deletion but not deleted.

The exact moment when the garbage collector deletes the object is not known. Therefore, Linux and macOS users should call the garbage collector explicitly before the deinitialization of the Engine object. Windows users should call the following methods before the deinitialization of the Engine object so that the garbage collector deletes the object:

GC.Collect()
GC.WaitForPendingFinalizers()

If you are using the log (it can be turned on with the StartLogging method of the Engine object), the message “Warning: DeinitializeEngine() has detected external references to FREngine objects. It can indicate a leak if programming platform without automatic garbage collection is used.” can also appear in this situation. Even if you are explicitly calling the garbage collector (In FRE for Windows, this is GC.Collect), it does not always mean that the objects are deleted immediately. When working in the environments with garbage collectors, you can disregard this message.

When working in the environments without garbage collection (such as C++), these exception and message can indicate a problem in your source code. Some objects can be incorrectly handled, causing a memory leak. However, after Engine deinitialization, all FineReader Engine objects will be deleted in any case, so the memory leak can occur in the client part of the code, i.e., if you create your own wrappers for the FineReader Engine objects and fail to release them before the deinitialization.

Consider using the TotalObjectsCount property of the Engine object, which returns the number of unreleased objects and can help you track down the memory leak.

Also in this section

• Different Ways to Load the Engine Object for Windows

  The detailed description of loading and unloading ABBYY FineReader Engine.

• Using ABBYY FineReader Engine in Multi-Threaded Server Applications for Windows

  Peculiarities of using in server applications.

• Error Handling

  Information about error handling.

• Handling Errors During PDF/XPS Export

  Describes how to handle errors that may occur during export to PDF/XPS format.

• Working with Properties

  The interfaces of ABBYY FineReader Engine objects have various properties and methods. The way the properties are handled in different languages is discussed in this article.

• Working with Collections

  There are three major types of collections in ABBYY FineReader Engine. See how to work with these collections in this section.

• Working with Connectable Objects

  Some of the objects in ABBYY FineReader Engine are so-called “connectable objects.” Here you can find useful recommendations on working with such objects.

• Working with COM Interfaces from a Scripting Language for Windows

  The detailed description of how to use FineReader Engine in a scripting language.

• Using ABBYY FineReader Engine in Java for Linux and Windows

  The description of how to use FineReader Engine in Java.

• Cross-platform development in Java for Linux and Windows

  Peculiarities of Java programming for all platforms.

• Using ABBYY FineReader Engine in .NET Core for Windows

  The description of how to use FineReader Engine in .NET Core.

• Using ABBYY FineReader Engine in C (Objective-C) for Windows

  Loading and unloading FineReader Engine in C (Objective-C).

• Out-of-Process Server Implementaion for Linux

  The detailed description of how to work with ABBYY FineReader Engine loaded as an out-of-process server.