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.
- 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; } };
- 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 );
7/3/2024 8:50:10 AM