Handle Object (IHandle Interface)

Handle object (IHandle interface) in the ABBYY FineReader Engine API — Provides access to the handle of a resource in memory (bitmap or memory block), managing memory allocation and avoiding leaks; not available out-of-process.

This object provides access to the handle of a resource in memory. It is returned by some methods which provide access to a bitmap image or a memory block. The object manages memory allocation and allows you to avoid memory leaks while working with these resources.

This interface does not support automation. This means that it does not work in Linux and Windows if FineReader Engine is loaded as an out-of-process server.

The object is used in the following situations:

• If you plan to work with the resource outside FineReader Engine

You can get the handle of the resource via the Handle property and work with it. In this case, if you release the Handle object, the resource is released too. Or you can get the handle and detach Handle object from it (use the Detach method). In this case, you are responsible for releasing the resource.

• If you plan to pass the resource to other methods of FineReader Engine

You can get the handle of the resource as __int64 via the HandleAsInt64 property. Later you can pass the value of this property to a method of FineReader Engine that requires it. If you release the Handle object, the resource is released too. You can release the resource manually by calling CloseHandle method.

Properties

Name	Type	Description
Application	Engine, read-only	Returns the Engine object.
Handle	HANDLE\*, read-only	Returns the handle of the resource. You can obtain the handle via this property and work with the resource.
HandleAsInt64	\_\_int64, read-only	Returns the handle of the resource as \_\_int64. You can pass the return value of this property to a method of FineReader Engine as an input parameter.

Methods

Name	Description
CloseHandle	Releases the resource.
Detach	Returns the handle and detaches the object from it.

Output parameter

This object is the output parameter of the following methods:

• GetBitmap method of the Image object
• SaveToMemory method of a number of objects (Windows)

Samples

C# code

FREngine.IEngine engine;
FREngine.IFRDocument frdoc;
// We presume that the document have been created and images have been added to it
// Get bitmap handle of a color image plane of a document page
FREngine.IFRPage page = frDoc.Pages[0];
FREngine.IImageDocument imageDoc = page.ImageDocument;
FREngine.IImage image = imageDoc.ColorImage;
FREngine.IHandle hBitmap = image.GetBitmap( null );
// Work with the bitmap
System.Drawing.IImage preprocessedImage = System.Drawing.Image.FromHbitmap( hBitmap.Handle );
...
Gdi32.DeleteObject( hBitmap );

The object is used in the following Windows demo tools: Engine Predefined Processing Profiles.

See also

Working with Properties