Utilisation des objets connectables

Certains objets d’ABBYY FineReader Engine sont des « objets connectables ». Cela signifie qu’ils implémentent l’interface IConnectionPointContainer. Les objets connectables permettent la communication entre ABBYY FineReader Engine et ses clients.

Sous Linux, l’objet Engine chargé en tant que serveur hors processus ne prend pas en charge l’utilisation des callbacks.

Pour les utilisateurs Windows, chacun des objets connectables de FRE fournit des points de connexion de deux types : l’un utilisant une interface dispatch et l’autre utilisant l’interface dérivée d’IUnknown. L’interface dispatch est conçue pour une utilisation automatique dans Visual Basic et les environnements similaires, tandis que l’interface basée sur vtbl convient à une utilisation en C++.

Le tableau ci-dessous répertorie les objets connectables d’ABBYY FineReader Engine et les interfaces de callback correspondantes (dispinterfaces) :

Les dispinterfaces sont spécifiques à Windows.

Objet	Interface de callback (Dispinterface)
FRDocument	IFRDocumentEvents (DIFRDocumentEvents)
FRPages	IFRPagesEvents (DIFRPagesEvents)
FRPage	IFRPageEvents (DIFRPageEvents)
ImageDocument	IImageDocumentEvents (DIImageDocumentEvents)

Composants visuels Windows

Objet	Interface de callback (Dispinterface)
ImageViewer	IImageViewerEvents (DIImageViewerEvents)
ZoomViewer	IZoomViewerEvents (DIZoomViewerEvents)
DocumentViewer	IDocumentViewerEvents (DIDocumentViewerEvents)
TextEditor	ITextEditorEvents (DITextEditorEvents)
TextValidator	ITextValidatorEvents (DITextValidatorEvents)
ComponentSynchronizer	IComponentSynchronizerEvents (DIComponentSynchronizerEvents)
Commands	ICommandEvents (DICommandEvents)

Toute application cliente ABBYY FineReader Engine souhaitant recevoir des notifications relatives à certains événements dans ABBYY FineReader Engine doit implémenter des interfaces d’un type spécifique et « enregistrer » les objets implémentant ces interfaces auprès des objets connectables correspondants.

Pour Linux et macOS

Il existe deux méthodes globales permettant de se connecter et de se déconnecter de la source de notifications :

HRESULT AdviseFREngineObject( IUnknown* object, IUnknown* callback, DWORD* cookie );
HRESULT UnAdviseFREngineObject( IUnknown* object, DWORD cookie );
class CFRDocumentCallback: public IFRDocumentEvents {
public:
...
    // Fournir une implémentation simple des méthodes 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;
    }
}
// Fournir l'implémentation des méthodes 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; }
};
// Supposons que nous avons déjà reçu l'objet FRDocument
IFRDocument* document;
// Créer l'objet callback
CFRDocumentCallback callbackObject;
// Abonner l'écouteur à la source de notifications
DWORD cookie; // Variable pour stocker le cookie retourné par la méthode Advise
AdviseFREngineObject( frDocument, &callbackObject, &cookie );
// Traiter le document
...
// Après notification, l'écouteur n'est plus nécessaire et doit être désabonné
UnadviseFREngineObject( frDocument, cookie );

Ces méthodes doivent recevoir l’un des Connectable Objects comme argument object et l’interface de callback correspondante comme argument callback.Vous devez implémenter l’interface requise et « abonner » l’objet qui l’implémente aux Connectable Objects correspondants. Nous utiliserons l’objet FRDocument comme exemple.

Implémentez l’interface IFRDocumentEvents. Étant donné qu’elle est dérivée de l’interface IUnknown, l’objet client doit également implémenter les méthodes IUnknown :
La classe CFRDocumentCallback peut ensuite être utilisée pour recevoir des notifications de l’objet FRDocument. Abonnez cet objet à la source de notifications (la gestion des erreurs est omise) :

Les utilisateurs Linux peuvent également consulter l’exemple EventsHandling.

La suite de cette rubrique s’applique aux utilisateurs de FRE pour Windows.

Pour Windows :

Visual Basic .NET

Déclarez simplement l’objet connectable WithEvents et implémentez les méthodes de l’interface de callback correspondante. Vous devrez également spécifier explicitement le gestionnaire d’événements associé à l’événement.Pour l’objet FRDocument, la procédure est la suivante :

Déclarez l’objet 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()

Implémentez les méthodes nécessaires de la dispinterface DIFRDocumentEvents dans la Sub, de manière similaire à ce qui suit.

Si vous souhaitez démarrer et arrêter la gestion des événements à tout moment pendant l’exécution du programme (à l’aide des instructions AddHandler et RemoveHandler) :ou indiquez simplement que cette procédure gère un événement particulier (utilisez le mot-clé Handles lors de la définition) :

Connectez le gestionnaire d’événements implémenté à la source d’événements, utilisez l’objet FRDocument pour le traitement, puis déconnectez le gestionnaire :

C++

En C++, vous devez implémenter l’interface nécessaire, obtenir un point de connexion et « enregistrer » l’objet implémentant l’interface auprès des Connectable Objects correspondants. Nous utiliserons le FRDocument object comme exemple.

Implémentez l’interface IFRDocumentEvents. Comme elle est dérivée de l’interface IUnknown, l’objet client doit également implémenter les méthodes IUnknown :

class CFRDocumentEventsListener : public IFRDocumentEvents {
public:
...
    // Fournir une implémentation simple des méthodes IUnknown. Elles peuvent aussi être
    // implémentées par héritage d'une classe standard avec support 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;
    }
    // Fournir l'implémentation des méthodes 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; }
};
// Supposons que nous avons déjà reçu le FRDocument object
IFRDocument* document;
// Interroger IConnectionPointContainer sur le FRDocument object
IConnectionPointContainer* pContainer=0;
document->QueryInterface(IID_IConnectionPointContainer, (void**)&pContainer);
// Obtenir un pointeur vers l'interface IConnectionPoint sur un point de connexion dans l'objet connectable
IConnectionPoint* pPoint=0;
pContainer->FindConnectionPoint(__uuidof(IFRDocumentEvents),
                                &pPoint);
// Établir une connexion entre la classe CFRDocumentEventsListener et le point de connexion
CFRDocumentEventsListener listener;
IUnknown* listenerUnknown=0;
listener.QueryInterface(IID_IUnknown, (void**)&listenerUnknown);
// Enregistrer le listener auprès de la source de notifications
DWORD cookie; // Variable pour stocker le cookie retourné par la méthode IConnectionPoint::Advise
pPoint->Advise(listenerUnknown, &cookie);
// Traiter le document
...
// Après notification, le listener n'est plus nécessaire et doit être désenregistré
pPoint->Unadvise(cookie);

La classe CFRDocumentEventsListener peut ensuite être utilisée pour recevoir des notifications du FRDocument object. Enregistrez cet objet auprès de la source de notifications (la gestion des erreurs est omise) :

La procédure en C# est similaire à celle de Visual Basic .NET. Vous devez implémenter les méthodes nécessaires de l’interface de rappel et connecter les gestionnaires d’événements implémentés à la source d’événements. Nous utiliserons le FRDocument object comme exemple.

Implémentez les méthodes nécessaires de l’interface 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;

Connectez le gestionnaire d’événements à la source d’événements, utilisez le FRDocument object pour le traitement, puis déconnectez le gestionnaire :

Les utilisateurs Windows doivent consulter la documentation COM pour une description plus détaillée des Connectable Objects. Vous pouvez également consulter l’exemple EventsHandling fourni dans FRE pour Linux en C++ et Windows en C#, C++ avec Native COM Support, C++ brut et Visual Basic .NET.