Skip to main content
This is a callback interface that is used for reporting events from the FRDocument object to the listeners. This interface is implemented on the client-side. See the detailed implementation advice for your development tool in Working with Connectable Objects. A brief description is below:
  • C++ users will need to implement the IFRDocumentEvents interface, obtain a connection point (Windows), and “advise” the object implementing the interface to the FRDocument object. As the interface is derived from the IUnknown interface, the client object should also implement the IUnknown methods.
  • Visual Basic users that want to receive notifications from the FRDocument object should declare it WithEvents and implement the procedures similar to the following:
Public WithEvents doc As FREngine.FRDocument
Private Sub doc_OnPageProcessed(ByVal sender As FRDocument, _
                                ByVal index As Integer, _
                                ByVal stage As PageProcessingStageEnum)
...
End Sub
An object receiving notifications through this interface’s methods may do the following inside the methods’ implementation:
  • Report percentage of image loading, document analysis, recognition, synthesis, and export performed.
  • Report information about document analysis, recognition, synthesis, and export completed.
  • In Windows: Process any system messages to help prevent the application from appearing unresponsive during long operations. This can be helpful in applications with a user interface.

​
Methods

NameDescription
OnPageProcessedDelivers to the client information about page processing completed.
OnProgressDelivers to the client information about approximate percentage of the current operation (image loading, analysis, recognition, etc.).
OnWarningDelivers to the client tips and warnings which occurred during processing.

​
Samples

This Windows C++ sample shows how to implement a timer that will abort processing if a method call is taking too long. 
class CFRDocumentCallback: public IFRDocumentEvents {
public:
    CFRDocumentCallback() : startTime( 0 ) {}
    // Implement the IUnknown methods
    ULONG STDMETHODCALLTYPE AddRef() { return 1; }
    ULONG STDMETHODCALLTYPE Release() { return 1; }
    HRESULT STDMETHODCALLTYPE QueryInterface( REFIID riid, void** ppObject );
    HRESULT STDMETHODCALLTYPE OnProgress( IFRDocument* document, int percentage, VARIANT_BOOL* ShouldContinue );
    HRESULT STDMETHODCALLTYPE OnWarning( IFRDocument* document, int pageNumber, BSTR recognizerTip, 
        VARIANT_BOOL* ShouldContinue );
    HRESULT STDMETHODCALLTYPE OnPageProcessed( IFRDocument* document, int pageNumber, PageProcessingStageEnum stage );
    void FlushTimer();
    void SetShouldTrackTime( bool _shouldTrackTime );
private:
    time_t startTime;
    bool shouldTrackTime = true;
};
 
// Call the FlushTimer method to reset the startTime
void CFRDocumentCallback::FlushTimer() {
    time( &startTime );
}
 
// This callback may be used in other methods, 
// so set shouldTrackTime to FALSE if you do not want to use the timeout anymore
void CFRDocumentCallback::SetShouldTrackTime( bool _shouldTrackTime ) {
    shouldTrackTime = _shouldTrackTime;
}
 
// If the difference between current time and "startTime" exсeeds a certain threshold, 
// the process will be aborted
HRESULT STDMETHODCALLTYPE CFRDocumentCallback::OnProgress( IFRDocument* frDocument, 
    int percentage, VARIANT_BOOL* shouldTerminate )
{
    if( shouldTrackTime ) {
        time_t currentTime;
        time( ¤tTime );
        double seconds = difftime( currentTime, startTime );
        printf( "%f\n", seconds );
        *shouldTerminate = ( seconds > 100 ? VARIANT_TRUE : VARIANT_FALSE );
    }
    return S_OK;
}
This object is used in the following code samples: EventsHandling (Windows and Linux).

​
Remarks

In Linux, this interface does not work if the Engine object is loaded as an out-of-process server.

​
See also

FRDocument Working with Connectable Objects