GetNextImageDocument Method of the IImageSource Interface

GetNextImageDocument method of the IImageSource Interface in the ABBYY FineReader Engine API — This method is implemented on the client-side.

This method is implemented in FRE for Linux and Windows.

This method is implemented on the client-side. The method returns the next image document from the image processing queue of the source.

For Windows, this method should be used only if you open images that were already loaded into memory — for example, using the OpenBitmap or OpenDib methods of the Engine object. If you get images from files on disk, implement GetNextImageFile.

An implementation of the GetNextImageDocument method may include time to wait for the next image document. However, we do not recommend implementing long waiting times, as FineReader Engine is not multithreaded. While waiting for the next document, the Engine will not be able to process messages from the recognition processes and receive notifications about page processing completed. If you do need to specify a long waiting time, the GetNextImageDocument method may return 0. In this case, the Engine will continue processing messages from the recognition processes and providing recognized images and after a while will check if the image queue is empty. If the queue is not empty (i.e., if IImageSource::IsEmpty returns FALSE), the Engine will call the GetNextImageDocument method again. However, if the GetNextImageDocument method returns 0 and there are no more pages to process, FineReader Engine will return control to the user: the IBatchProcessor::GetNextProcessedPage method will return 0.

• All the ImageDocument objects in the queue must be valid till the end of processing. For correct operation the ImageDocument objects should be created via the Engine object. If they are created via the FRDocument object an error may occur because of the FRDocument object being destroyed during the call to the GetNextImageDocument method.
• As the method is implemented on the client-side there are the following restrictions:
  • all password-protected files should be opened manually on the client-side;
  • the attributes specified in the PrepareImageMode object during the initialization of the BatchProcessor object will not affect the ImageDocument objects in the queue.

Syntax

C++

HRESULT GetNextImageDocument( IImageDocument** Result );

C#

IImageDocument GetNextImageDocument();

Visual Basic .NET

Function GetNextImageDocument() As IImageDocument

Parameters

Result

[out, retval] A pointer to IImageDocument* pointer variable that provides access to the next image document in the queue.

Return values

[C++ only] If this method returns a value other than S_OK, it indicates that an error occurred on the client-side.

Remarks

The client implementation of this method must assure that all exceptions thrown inside the method are caught and handled and no exceptions are propagated outside the method. Propagation of an exception outside the method may lead to unpredictable results (such as program termination).

Samples

C# code

// Sample implementation of a custom image source which maintains a queue of image files
public class ImageSourceCallback : FREngine.IImageSource
{
   public ImageSourceCallback( string imageFilesDirectory )
   {
       imageFiles = ImageSourceHelper.LoadFilesNames( imageFilesDirectory );
       nextFileIndex = 0;
   }
   public bool IsEmpty()
   {
       return nextFileIndex >= imageFiles.Length;
   }
   public FREngine.IFileAdapter GetNextImageFile()
   {
       if( !IsEmpty() ) {
           return new FileAdapterCallback( imageFiles[nextFileIndex++] );
       }
       return null;
   }
   public FREngine.IImageDocument GetNextImageDocument()
   {
       ...
   }
   private string[] imageFiles;
   private int nextFileIndex;
}
public class FileAdapterCallback : FREngine.IFileAdapter
{
    ...
}
public class ImageSourceHelper
{
    ...
}

See also

IImageSource

GetNextImageFile

IsEmpty

ImageDocument