Working with Connectable Objects

ABBYY FineReader Engine의 일부 객체는 소위 “connectable objects”입니다. 즉, 이러한 객체는 IConnectionPointContainer 인터페이스를 구현합니다. connectable object는 ABBYY FineReader Engine과 클라이언트 간의 통신을 지원합니다.

Linux에서는 out-of-process server로 로드된 Engine 객체가 콜백 사용을 지원하지 않습니다.

Windows 사용자의 경우, 각 FRE connectable object는 두 가지 유형의 연결 지점을 제공합니다. 하나는 dispatch 인터페이스를 사용하고, 다른 하나는 IUnknown에서 파생된 인터페이스를 사용합니다. dispatch 인터페이스는 Visual Basic 및 유사한 환경에서 자동으로 사용되도록 설계되었으며, vtbl 기반 인터페이스는 C++에서 사용하기에 적합합니다.

아래 표에서 ABBYY FineReader Engine의 connectable object 목록과 해당 콜백 인터페이스(dispinterface)를 확인할 수 있습니다.

Dispinterface는 Windows 전용입니다.

객체	콜백 인터페이스(Dispinterface)
FRDocument	IFRDocumentEvents (DIFRDocumentEvents)
FRPages	IFRPagesEvents (DIFRPagesEvents)
FRPage	IFRPageEvents (DIFRPageEvents)
ImageDocument	IImageDocumentEvents (DIImageDocumentEvents)

Windows Visual Components

객체	콜백 인터페이스(Dispinterface)
ImageViewer	IImageViewerEvents (DIImageViewerEvents)
ZoomViewer	IZoomViewerEvents (DIZoomViewerEvents)
DocumentViewer	IDocumentViewerEvents (DIDocumentViewerEvents)
TextEditor	ITextEditorEvents (DITextEditorEvents)
TextValidator	ITextValidatorEvents (DITextValidatorEvents)
ComponentSynchronizer	IComponentSynchronizerEvents (DIComponentSynchronizerEvents)
Commands	ICommandEvents (DICommandEvents)

ABBYY FineReader Engine에서 특정 이벤트 알림을 받으려는 클라이언트 애플리케이션은 특정 유형의 인터페이스를 구현한 다음, 이러한 인터페이스를 구현하는 객체를 해당 connectable object에 “advise”해야 합니다.

Linux 및 macOS의 경우

알림 소스에 연결하거나 연결을 해제하는 데 사용하는 전역 메서드는 다음 두 가지입니다.

HRESULT AdviseFREngineObject( IUnknown* object, IUnknown* callback, DWORD* cookie );
HRESULT UnAdviseFREngineObject( IUnknown* object, DWORD cookie );
class CFRDocumentCallback: public IFRDocumentEvents {
public:
...
    // IUnknown 메서드의 간단한 구현 제공
    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;
    }
}
// IFRDocumentEvents 메서드 구현 제공
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; }
};
// 이미 FRDocument 객체를 받았다고 가정
IFRDocument* document;
// 콜백 객체 생성
CFRDocumentCallback callbackObject;
// 알림 소스에 리스너를 advise
DWORD cookie; // Advise 메서드에서 반환된 cookie를 저장하는 변수
AdviseFREngineObject( frDocument, &callbackObject, &cookie );
// 문서 처리
...
// 알림이 끝나면 리스너가 더 이상 필요하지 않으므로 unadvise해야 함
UnadviseFREngineObject( frDocument, cookie );

이 메서드에서는 object 인수로 Connectable Objects 중 하나를 받고, callback 인수로 해당 콜백 인터페이스를 받아야 합니다.필요한 인터페이스를 구현한 다음, 그 인터페이스를 구현하는 객체를 해당 Connectable Objects에 “advise”해야 합니다. 여기서는 FRDocument 객체를 예로 사용하겠습니다.

IFRDocumentEvents 인터페이스를 구현합니다. 이 인터페이스는 IUnknown 인터페이스에서 파생되므로 클라이언트 객체도 IUnknown 메서드를 구현해야 합니다.
그러면 CFRDocumentCallback 클래스를 사용해 FRDocument 객체의 알림을 받을 수 있습니다. 이 객체를 알림 소스에 advise합니다(오류 처리는 생략).

Linux 사용자는 EventsHandling sample도 참조할 수 있습니다.

이 항목의 나머지 내용은 Windows용 FRE 사용자에게 적용됩니다.

Windows의 경우:

Visual Basic .NET

Connectable Object를 WithEvents로 선언하고 해당 콜백 인터페이스의 메서드를 구현하면 됩니다. 또한 이벤트와 연결된 이벤트 핸들러를 명시적으로 지정해야 합니다.FRDocument 객체의 경우 절차는 다음과 같습니다.

FRDocument 객체를 WithEvents로 선언합니다.

Private WithEvents document As FREngine.FRDocument
Private Sub document_RecognitionOnProgress(ByVal sender As FREngine.FRDocument, _
                                           ByVal Percentage As Integer, _
                                           ByRef cancel As Boolean)
...
End Sub
Private Sub document_RecognitionOnProgress(ByVal sender As FREngine.FRDocument, _
                                           ByVal Percentage As Integer, _
                                           ByRef cancel As Boolean) Handles document.OnProgress
...
End Sub
document = Engine.CreateFRDocument
document.AddImageFile("D:\Demo.tif")
AddHandler document.OnProgress, AddressOf Me.document_RecognitionOnProgress
document.Process()
RemoveHandler document.OnProgress, AddressOf Me.document_RecognitionOnProgress
or simply use the FRDocument object for processing if you define the event handling methods with Handles keyword:
document = Engine.CreateFRDocument
document.AddImageFile("D:\Demo.tif")
document.Process()

다음과 비슷한 Sub에서 DIFRDocumentEvents dispinterface의 필요한 메서드를 구현합니다.

프로그램 실행 중 언제든지 이벤트 처리를 시작하거나 중지하려면(AddHandler 및 RemoveHandler 문 사용):또는 이 프로시저가 특정 이벤트를 처리하도록 간단히 지정할 수도 있습니다(정의할 때 Handles 키워드 사용):

구현한 이벤트 핸들러를 이벤트 소스에 연결하고, FRDocument 객체를 사용해 처리한 다음, 핸들러 연결을 해제합니다.

C++

C++에서는 필요한 인터페이스를 구현하고 connection point를 가져온 다음, 해당 인터페이스를 구현하는 객체를 해당 connectable object에 “advise”해야 합니다. 여기서는 FRDocument 객체를 예로 사용하겠습니다.

IFRDocumentEvents 인터페이스를 구현합니다. 이 인터페이스는 IUnknown 인터페이스에서 파생되므로, 클라이언트 객체도 IUnknown 메서드를 구현해야 합니다:

class CFRDocumentEventsListener : public IFRDocumentEvents {
public:
...
    // IUnknown 메서드의 간단한 구현을 제공합니다. 이 메서드는
    // COM 지원이 있는 일부 표준 클래스를 상속하여 구현할 수도 있습니다
    ULONG AddRef();
    ULONG Release();
    HRESULT QueryInterface(REFIID riid, void** ppvObject)
    {
        if( ppvObject == 0 )
            return E_INVALIDARG;
        if( riid == __uuidof(IFRDocumentEvents) ) {
            *ppvObject = static_cast<IFRDocumentEvents*>( this );
        } else if( riid == IID_IUnknown ) {
            *ppvObject = static_cast<IUnknown*>( this );
        } else {
            *ppvObject = 0;
            return E_NOINTERFACE;
        }
        AddRef();
        return S_OK;
    }
    // IFRDocumentEvents 메서드를 구현합니다
 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; }
};
// 이미 FRDocument 객체를 받았다고 가정합니다
IFRDocument* document;
// FRDocument 객체에서 IConnectionPointContainer를 쿼리합니다
IConnectionPointContainer* pContainer=0;
document->QueryInterface(IID_IConnectionPointContainer, (void**)&pContainer);
// connectable object 내 connection point의 IConnectionPoint 인터페이스에 대한 포인터를 가져옵니다
IConnectionPoint* pPoint=0;
pContainer->FindConnectionPoint(__uuidof(IFRDocumentEvents),
                                &pPoint);
// CFRDocumentEventsListener 클래스와 connection point 사이에 연결을 설정합니다
CFRDocumentEventsListener listener;
IUnknown* listenerUnknown=0;
listener.QueryInterface(IID_IUnknown, (void**)&listenerUnknown);
// 알림 source에 listener를 advise합니다
DWORD cookie; // IConnectionPoint::Advise 메서드에서 반환된 cookie를 저장하는 변수
pPoint->Advise(listenerUnknown, &cookie);
// 문서를 처리합니다
...
// 알림이 끝나면 listener가 더 이상 필요하지 않으므로 unadvise해야 합니다
pPoint->Unadvise(cookie);

그런 다음 CFRDocumentEventsListener 클래스를 사용하여 FRDocument 객체의 알림을 받을 수 있습니다. 이 객체를 알림 source에 advise합니다(오류 처리는 생략됨):

C# 절차는 Visual Basic .NET과 비슷합니다. callback 인터페이스의 필요한 메서드를 구현하고, 구현한 이벤트 핸들러를 event source에 연결해야 합니다. 여기서는 FRDocument 객체를 예로 사용하겠습니다.

IFRDocumentEvents 인터페이스의 필요한 메서드를 구현합니다:

private void document_RecognitionOnProgress(FREngine.IFRDocument sender, int Percentage, ref bool cancel)
{
 ...
}
FREngine.DIFRDocumentEvents_OnProgressEventHandler recognizeOnProgressHandler =
 new FREngine.DIFRDocumentEvents_OnProgressEventHandler(
 document_RecognitionOnProgress );
document.OnProgress += recognizeOnProgressHandler;
document.Process( null, null, null );
document.OnProgress -= recognizeOnProgressHandler;

이벤트 핸들러를 event source에 연결하고, FRDocument 객체를 처리에 사용한 다음, handler 연결을 해제합니다:

Windows 사용자는 connectable object에 대한 자세한 내용은 COM 문서를 참조해야 합니다. 또한 Linux용 FRE의 C++, 그리고 Windows용 C#, Native COM 지원이 포함된 C++, raw C++, Visual Basic .NET용으로 제공되는 EventsHandling sample도 참조할 수 있습니다.

개요

기본 사용 시나리오 구현

고급 기법

개요

기본 사용 시나리오 구현

고급 기법

Documentation Index