Skip to main content
The interfaces of ABBYY FineReader Engine objects have various properties and methods. In general, properties represent information about an object, whereas methods represent actions an object can take.
C# samples apply to Windows. C++ samples apply to all supported operating systems.
For C++, a property is a pair of methods (get and put for read-write properties) or a single get method (for read-only properties).The ABBYY FineReader Engine properties may be of the following types:
  • VARIANT_BOOL (with two values VARIANT_TRUE or VARIANT_FALSE)
  • int
  • double
  • BSTR, a pointer to Unicode string. Zero value specifies an empty string.
  • __int64
  • HANDLE*
  • IUnknown-derived interface
  • enum
C# and Visual Basic users are familiar with the notion of property.For a C++ user, a property is a pair of methods (get and put for read-write properties) or a single get method (for read-only properties).However, the “Native COM support” featured by Microsoft C++ makes the way the properties are handled more like the one used in C#.The ABBYY FineReader Engine properties may be of the following types:
IDLC++C#Visual Basic .NET
VARIANT\_BOOL (VARIANT\_TRUE or VARIANT\_FALSE)VARIANT\_BOOL (VARIANT\_TRUE or VARIANT\_FALSE)bool (true or false)Boolean (True or False)
intintintInteger
doubledoubledoubleDouble
BSTR, a pointer to Unicode string. Zero value specifies an empty string.BSTRstringString
\_\_int64\_\_int64Int64Int64
HANDLE\*void\*IntPtrIntPtr
IUnknown-derived interfaceIUnknown-derived interfaceobjectObject
enumenumenumEnum
See the details of working with different types of properties below:
We will use a Boolean property as an example of how simple properties are used. The property is described in the type library as follows:
interface IMyObject : IUnknown
{
  [propget]
  HRESULT MyProperty( [out, retval] VARIANT_BOOL* result );
  [propput]
  HRESULT MyProperty( [in] VARIANT_BOOL value );
};
if (MyObject.MyProperty != true)
 MyObject.MyProperty = true;
IMyObject* pMyObject;
VARIANT_BOOL res;
pMyObject->get_MyProperty(&res);
if( res != VARIANT_TRUE )
   pMyObject->put_MyProperty(VARIANT_TRUE);
IMyObjectPtr pMyObject;
if(pMyObject->MyProperty != VARIANT_TRUE)
   pMyObject->MyProperty = VARIANT_TRUE
If the type library only defines the “get” method for a simple property, this property is called read-only. Its value cannot be changed by the user, it may only be accessed for “reading.”A C# user handles a simple property as follows:A C++ user, on the other hand, uses two methods to work with this property. These methods have get_ and put_ prefixes. The respective C++ code should look as follows:However, the Native COM support in Windows makes the procedure simpler, and the respective code should look as follows:
Working with string properties is very similar to working with simple properties, but has its own specifics. A C++ user working with string properties must free the strings that are passed to set-methods, and also those that are returned by get-methods.
  • In Windows, this is done automatically in C#, Visual Basic, and in C++ with the Native COM support.
  • In Linux, use the FREngineAllocString and FREngineFreeString functions to allocate and free the memory for the strings.
Suppose MyObject also supports a string property called Name. This property is described in the type library as follows:
interface IMyObject : IUnknown
{
  [propget]
  HRESULT Name([out, retval]BSTR* result);
  [propput]
  HRESULT Name([in]BSTR value);
};
IMyObject* pMyObject;
// "get" method
BSTR res;
pMyObject->get_Name(&res);
// Now free the string allocated in ABBYY FineReader Engine
::SysFreeString(res);
// "put" method
BSTR str = ::SysAllocString(L"New Name");
pMyObject->put_Name(str);
// Now free the string that we allocated
::SysFreeString(str);
IMyObject* pMyObject;
// "get" method
BSTR res;
pMyObject->get_Name(&res);
// Now free the string allocated in ABBYY FineReader Engine
::FREngineFreeString(res);
// "put" method
BSTR str = ::FREngineAllocString(L"New Name");
pMyObject->put_Name(str);
// Now free the string that we allocated
::FREngineFreeString(str);
A C++ user works with this property like this:Windows:Linux:
A C++ user will say that the parameters of “get” methods of object properties are pointers to an object’s interface pointer. As the interfaces of the objects are derived from IUnknown, they may be passed as IUnknown pointers to the properties or methods which use objects of several types as input or output parameters (you may, however, get the interface you need by calling the QueryInterface method).A “put” method for an object property, if any, supports clear put, described by the propput keyword in the type library. This means that the object is copied (instead of passing a pointer to an existing object’s interface).Suppose again the MyObject object supports MyObjectProperty property that refers to an object of MyChildObject type.
interface IMyObject : IUnknown
{
  [propget]
  HRESULT MyObjectProperty([out, retval]IMyChildObject** result);
  [propput]
  HRESULT MyObjectProperty([in]IMyChildObject* value);
};
IMyObject* pMyObject;
IMyChildObject* pChildObj=0;
// get_ method may return 0 in certain cases
pMyObject->get_MyObjectProperty(&pChildObj);
// Do something with the object
...
pMyObject->put_MyObjectProperty(pChildObj);
pChildObj->Release();
A C++ user will write this code as follows:Note that in C++ you should call the Release method for an object got via a property. Native COM support in Windows calls AddRef and Release methods automatically using auto pointers.

​
Working with read-only object properties

Certain ABBYY FineReader Engine objects (for example, ILayout::Blocks) have read-only object properties. This does not mean that such properties cannot be changed, this only means that they cannot be changed by directly replacing the object property with another object, because “put” method is not supported. However, you can change the sub-properties of these objects. In C++ (raw C++ if Windows), if you want to change such a property, you need to pass a reference to the property object to a new variable, and then use this variable to change it. Below you can see a C++ sample for the ILayout::Blocks property which is represented by a read-only collection: 
// We assume that a page has been already opened
ILayout* pLayout = 0;
ILayoutBlocks* pLayoutBlocks = 0;
int blockIndex = 0;
// Receive the layout from the previously opened FRPage
pFRPage->get_Layout( &pLayout );
// The pLayoutBlocks variable receives a reference to the blocks collection from Layout
pLayout->get_Blocks( &pLayoutBlocks );
// Remove an element from the block collection
pLayoutBlocks->DeleteAt( blockIndex );
// Work with modified layout
...
// Release the objects
pLayoutBlocks->Release();
pLayout->Release();