Working with Connectable Objects

Some of the objects in ABBYY FineReader Engine are so-called "connectable objects." This means that they implement the IConnectionPointContainer interface. Connectable objects support communication between ABBYY FineReader Engine and its clients.

In the table below, you can find the list of connectable objects in ABBYY FineReader Engine and corresponding callback interfaces:

Object Callback Interface (Dispinterface)
FRDocument IFRDocumentEvents
FRPages IFRPagesEvents
FRPage IFRPageEvents
ImageDocument IImageDocumentEvents

ABBYY FineReader Engine client application that wants to receive notifications of certain events in ABBYY FineReader Engine should implement interfaces of a specific type and "advise" the objects implementing these interfaces to the corresponding connectable objects. There are two global methods used for connecting and disconnecting to the notification source:

HRESULT AdviseFREngineObject( IUnknown* object, IUnknown* callback, DWORD* cookie );
    HRESULT UnAdviseFREngineObject( IUnknown* object, DWORD cookie );
    

These methods should receive one of the connectable objects as the object argument and the corresponding callback interface as the callback argument.

You need to implement the necessary interface and "advise" object implementing the interface to the corresponding connectable objects. We will use the FRDocument object as an example.

  1. Implement the IFRDocumentEvents interface. As it is derived from the IUnknown interface, the client object should also implement the IUnknown methods:
class CFRDocumentCallback: public IFRDocumentEvents {
public:
...
    // Provide IUnknown methods simple implementation
    ULONG STDMETHODCALLTYPE AddRef() { return 1; }
    ULONG STDMETHODCALLTYPE Release() { return 1; }
    HRESULT STDMETHODCALLTYPE QueryInterface( REFIID riid, void** ppObject )
    {
        if( ppObject == 0 ) {
            return E_POINTER;
        }
    *ppObject = 0;
    if( riid == IID_IUnknown || riid == IID_IFRDocumentEvents )
    {
        *ppObject = this;
        AddRef();
        return S_OK;
    } else {
        return E_NOINTERFACE;
    }
}
// Provide IFRDocumentEvents methods implementation
HRESULT STDMETHODCALLTYPE OnProgress(
IFRDocument* sender, int percentage, VARIANT_BOOL* cancel );
HRESULT STDMETHODCALLTYPE OnWarning(
IFRDocument* sender, int index, BSTR tip, VARIANT_BOOL* cancel );
HRESULT STDMETHODCALLTYPE OnPageProcessed(
    IFRDocument* sender, int index, PageProcessingStageEnum stage ) { return S_OK; }
};
    
  1. Then the CFRDocumentCallback class can be used to receive notifications from the FRDocument object. Advise this object to the notifications source (error handling is omitted):
// Suppose that we have already received the FRDocument object
IFRDocument* document;
// Create callback object
CFRDocumentCallback callbackObject;
// Advise listener to the notifications source
DWORD cookie; // A variable to store the cookie returned from the Advise method
AdviseFREngineObject( frDocument, &callbackObject, &cookie );
// Process the document
...
// After notification, the listener is no longer needed and should be unadvised
UnadviseFREngineObject( frDocument, cookie );
    
  

03.07.2024 8:50:10

Usage of Cookies. In order to optimize the website functionality and improve your online experience ABBYY uses cookies. You agree to the usage of cookies when you continue using this site. Further details can be found in our Privacy Notice.