Working with Connectable Objects

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

Each of the ABBYY FlexiCapture SDK connectable objects provides connection points of two types – one that uses a dispatch interface, and one that uses interface derived from IUnknown. The dispatch interface is designed for automatic use in Visual Basic and similar environments, while the vtbl-based interface is suitable for use in C++.

In the table below you can find the list of connectable objects in ABBYY FlexiCapture SDK and corresponding callback interfaces (dispinterfaces):

Object	Callback Interface (Dispinterface)
Project Batch	IBatchEvents (DIBatchEvents)
AssemblingErrors Batches BatchTypes Blocks Documents FieldInstances Fields Pages RuleErrors TableColumns	ICollectionEvents (DICollectionEvents)
ClassificationTrainer FieldsExtractionTrainer	IProcessingEvents (DIProcessingEvents)

Object

Callback Interface (Dispinterface)

Project

Batch

IBatchEvents (DIBatchEvents)

ICollectionEvents (DICollectionEvents)

ClassificationTrainer

FieldsExtractionTrainer

IProcessingEvents (DIProcessingEvents)

ABBYY FlexiCapture SDK client application that wants to receive notifications of certain events in ABBYY FlexiCapture SDK, should implement interfaces of specific type, and "advise" objects implementing these interfaces to the corresponding connectable objects. See details for your development tool below.

Visual Basic .NET

For the Batch object the procedure will be the following:

Declare the event source object of the IBatchEvents_Event type WithEvents:

Public WithEvents eventsSource As FCEngine.IBatchEvents_Event

Implement the necessary methods of the IBatchEvents interface in the Sub similar to one of the following.

If you want to start and stop event handling at any time during program execution (using AddHandler and RemoveHandler statements):

Private Sub eventsSource_OnBatchProgress(ByVal Batch As FCEngine.IBatch, _
                                         ByVal ProcessedItemsCount As Integer, _
                                         ByVal RemainingItemsCount As Integer)
...
End Sub

or simply specify that this procedure handles a particular event (use the Handles keyword when defining):

Private Sub eventsSource_OnBatchProgress(ByVal Batch As FCEngine.IBatch, _
                                         ByVal ProcessedItemsCount As Integer, _
                                         ByVal RemainingItemsCount As Integer) Handles eventsSource.OnBatchProgress
...
End Sub

Initialize the event source with the Batch object:

Dim project As FCEngine.IProject
project = Engine.OpenProject("D:\Sample.fcproj")
Dim batch As FCEngine.IBatch
batch = project.Batches.AddNew("TestBatch")
eventsSource = batch

Connect the implemented event handler to the event source, use the Batch object for processing, then disconnect the handler:

AddHandler eventsSource.OnBatchProgress, AddressOf Me.eventsSource_OnBatchProgress
batch.Recognize(Nothing, FCEngine.RecognitionModeEnum.RM_ReRecognizeMinimal, Nothing)
RemoveHandler eventsSource.OnBatchProgress, AddressOf Me.eventsSource_OnBatchProgress

or simply use the Batch object for processing if you define the event handling methods with Handles keyword:

batch.Recognize(Nothing, FCEngine.RecognitionModeEnum.RM_ReRecognizeMinimal, Nothing)

C++ (COM)

In C++ you need to implement necessary interface, obtain a connection point, and "advise" object implementing the interface to the corresponding connectable objects. We will use the Batch object as an example.

Implement the IBatchEvents interface. As it is derived from the IUnknown interface, the client object should also implement the IUnknown methods:

class CProjectEventsListener : public IBatchEvents {
public:
...
    // Provide IUnknown methods simple implementation. They may also be
    // implemented by inheritance from some standard class with COM support
    ULONG AddRef();
    ULONG Release();
    HRESULT QueryInterface(REFIID riid, void** ppvObject)
    {
        if( ppvObject == 0 )
            return E_INVALIDARG;
        if( riid == __uuidof(IBatchEvents) ) {
            *ppvObject = static_cast<IBatchEvents*>( this );
        } else if( riid == IID_IUnknown ) {
            *ppvObject = static_cast<IUnknown*>( this );
        } else {
            *ppvObject = 0;
            return E_NOINTERFACE;
        }
        AddRef();
        return S_OK;
    }
    // Provide IBatchEvents methods implementation
    HRESULT OnBatchProgress(IBatch*, int, int);
    HRESULT OnPageProgress(IPage*, int);
    HRESULT OnPageRectProcessed(IPage*, int, int, int, int, int);
    HRESULT OnProcessMessages(VARIANT_BOOL*);
    HRESULT OnRecognizerTip(IPage*, BSTR);
    HRESULT OnError(IPage*, BSTR, VARIANT_BOOL*);
    HRESULT OnWarning(IPage*, BSTR, BSTR, int, int*);
};

Then the CProjectEventsListener class may be used to receive notifications from the Batch object. Advise this object to the notifications source (error handling is omitted):

// Suppose that we have already received the Batch object
IBatch* batch;
// Query for IConnectionPointContainer on the Batch object
IConnectionPointContainer* pContainer=0;
batch->QueryInterface(IID_IConnectionPointContainer, (void**)&pContainer);
// Obtain a pointer to the IConnectionPoint interface on a connection point within the connectable object
IConnectionPoint* pPoint=0;
pContainer->FindConnectionPoint(__uuidof(IBatchEvents),
                                &pPoint);
// Establish a connection between the CProjectEventsListener class and the connection point
CProjectEventsListener listener;
IUnknown* listenerUnknown=0;
listener.QueryInterface(IID_IUnknown, (void**)&listenerUnknown);
// Advise listener to the notifications source
DWORD cookie; // A variable to store the cookie returned from the IConnectionPoint::Advise method
pPoint->Advise(listenerUnknown, &cookie);
// Process the batch
...
// After notification, the listener is no longer needed and should be unadvised
pPoint->Unadvise(cookie);

C#

Refer to documentation on COM for a more detailed description of connectable objects.

Your use of this site is conditioned on Your continued compliance with the Terms of Use.

Terms of Use

Disclaimer of Warranty

Limitation of Liability

Transmission and Submission of Information

Downloads

Use of Content

Trademarks

Links to Third-Party Sites

Foreign Legislation

Subscription Terms

Partner Subscription Terms

Working with Connectable Objects

Visual Basic .NET

C++ (COM)

C#

See also