Automation interface of OmniPage Pro 12

Automation interface of OmniPage Pro 12

Last revision date: July 24, 2002

Automation interface of OmniPage Pro 12

Table of Contents

Automation interface of OmniPage Pro 12 .................................................. 1

Table of Content ........................................................................................................................................ 2 Introduction ............................................................................................................................................... 4 IApplication interface ................................................................................................................................ 4 AppName property........................................................................................................................... 5 Version property............................................................................................................................... 5 AppBusy property ............................................................................................................................ 5 AppInitialized property .................................................................................................................... 5 Login method ................................................................................................................................... 5 SilentMode property......................................................................................................................... 5 ParentWindow property ................................................................................................................... 6 IProcess interface....................................................................................................................................... 6 Document management ........................................................................................................................ 6 CreateDocument method.................................................................................................................. 6 OpenDocument method ................................................................................................................... 7 SaveDocument method .................................................................................................................... 7 PrintImages method ......................................................................................................................... 7 PrintText method.............................................................................................................................. 7 ReadDocument method .................................................................................................................... 8 StopReading method ........................................................................................................................ 8 TTSStatus property .......................................................................................................................... 8 TTSEnabled property ....................................................................................................................... 8 PageCount property.......................................................................................................................... 8 AutoSave property ........................................................................................................................... 9 DocumentModifiedFlag property..................................................................................................... 9 Image capture........................................................................................................................................ 9 ImportImage method........................................................................................................................ 9 LoadImages method ......................................................................................................................... 9 ImageSource property .................................................................................................................... 10 InsertMode property....................................................................................................................... 10 StartAddImage method .................................................................................................................. 11 AddImageData method .................................................................................................................. 11 StopAddImage method................................................................................................................... 12 Layout decomposition......................................................................................................................... 12 LayoutFormat property .................................................................................................................. 12 TemplateFilename property ........................................................................................................... 13 AutoZoneState property ................................................................................................................. 13 ZoneImage method......................................................................................................................... 13 Recognition......................................................................................................................................... 13 RejectChar property ....................................................................................................................... 13 Languages property........................................................................................................................ 14 UserDictionary property................................................................................................................. 15 TrainingFile property ..................................................................................................................... 15 Recognize method.......................................................................................................................... 15 Proof method.................................................................................................................................. 16 ProcessImage method..................................................................................................................... 16 Processing options .............................................................................................................................. 16 AutoOrientation property ............................................................................................................... 16 RetainColor property...................................................................................................................... 17 AutoProof property ........................................................................................................................ 17 Text export.......................................................................................................................................... 17 ExportDocument method ............................................................................................................... 17

Automation interface of OmniPage Pro 12

ExportTarget property.................................................................................................................... 17 ExportTextFormat property............................................................................................................ 18 FormattingLevel property .............................................................................................................. 18 TextSeparation property................................................................................................................. 19 LaunchOnExport property.............................................................................................................. 19 IExportTextFormats and IExportTextFormat interfaces..................................................................... 19 Image export ....................................................................................................................................... 21 ExportImageFiles method .............................................................................................................. 22 ExportImageFormat property......................................................................................................... 22 ImageSeparation property .............................................................................................................. 22 IImageFormats and IImageFormat interfaces ..................................................................................... 22 Settings ............................................................................................................................................... 24 LoadSettings method...................................................................................................................... 24 SaveSettings method ...................................................................................................................... 24 OptionsDialog method ................................................................................................................... 24 IScanner interface ............................................................................................................................... 27 Scanner capabilities ............................................................................................................................ 28 IsScannerAvailable method............................................................................................................ 28 IsTWAINBasicMode method ........................................................................................................ 28 BrightnessCap property.................................................................................................................. 28 ContrastCap property ..................................................................................................................... 28 PaperSizeCap property................................................................................................................... 28 ADFCap property........................................................................................................................... 29 ScanModeCap property.................................................................................................................. 29 Scanner settings .................................................................................................................................. 29 Brightness property ........................................................................................................................ 29 Contrast property............................................................................................................................ 29 Resolution property........................................................................................................................ 29 Scanmode property......................................................................................................................... 30 Papersize property.......................................................................................................................... 30 PageOrientation property ............................................................................................................... 30 Error handling ..................................................................................................................................... 30 LastError property.......................................................................................................................... 30 Progress indication.............................................................................................................................. 31 Localization issues................................................................................................................................... 32 Error codes............................................................................................................................................... 32

Automation interface of OmniPage Pro 12

Introduction
OmniPage Pro provides an automation interface for OLE clients to reach its functionality. This covers almost all main features of OmniPage, including scanning, loading images, OCR, text and image export and setting many processing parameters. The functionality is implemented through several interfaces in hierarchical order. These are dual interfaces. The base interface is the IApplication interface. This interface allows authorized users to get the IProcess interface that implements OmniPages functionality. The different processing properties can also be set through this interface. This interface also contains a few collections (languages, export formats, etc.) to enumerate the different lists. The scanner capabilities and parameters can also be reached through this interface. The following figure represents the hierarchy of the mentioned interfaces. IApplication IProcess

IExportTextFormats IExportTextFormat IOPLanguages

IOPLanguage

IImageFormats IImageFormat

IOPScanner The typical usage of the automation interface is 1. Create an Application object with the IApplication interface 2. Call Login method of the IApplication interface to get the IProcess interface. The Office edition of OmniPage provides these interfaces for any users without any authorization. In other product versions, this method performs an authorization requiring a special key and only authorized users can retrieve the IProcess interface. The detailed login procedure is described below.

IApplication interface
The main feature of the IApplication interface is to authorize OLE clients and return the IProcess interface for authorized users. Some global properties can be retrieved or set through this interface.

Automation interface of OmniPage Pro 12

AppName property*
HRESULT get_AppName(BSTR *pAppName); CString GetAppName(); Description: Returns the name of the current version of OmniPage. Currently it can be one of three values: 1. OmniPage Pro 2. OmniPage SE 3. OmniPage Office Edition

Version property
HRESULT get_Version(LONG *pAppVersion); LONG GetVersion(); Description: Returns the current OmniPage version

AppBusy property
HRESULT get_AppBusy(VARIANT_BOOL *Busy); BOOL GetAppBusy(); Description: The value of this property is true when OmniPage is performing some process.

AppInitialized property
HRESULT get_AppInitialized(VARIANT_BOOL *pbInit); BOOL GetAppInitialized(); Description: See also: This Boolean property indicates whether the OLE automation interface is initialized properly or not. It is true after a successful login. method Login

Login method
HRESULT Login(BSTR Key, LPDISPATCH *lpIProcess); LPDISPATCH Login(LPCTSTR Key); Description: This method initializes OmniPage for automation. It verifies the Key passed to the method in OmniPage Pro and SE editions. If the Key is not valid the method fails and return a NULL pointer as IProcess interface. This verification process is not performed in the Office Edition. Key is an encrypted character string that authorizes the client to use the interface in any edition of OmniPage. The return value is a IDispatch interface to the Process object. This interface is used to further document processing. If the login procedure fails, the return interface pointer is a NULL pointer.

Parameter: Return value:

SilentMode property
HRESULT get_SilentMode(VARIANT_BOOL *pbSilent); HRESULT put_SilentMode(VARIANT_BOOL bSilent);
*

We provide the definition of interface members according to the rules of dual at first and then dispatch interfaces

Automation interface of OmniPage Pro 12 BOOL GetSilentMode(); void SetSilentMode(BOOL Value); Description: This Boolean property controls the display of OmniPage progress indication. When this parameter is TRUE, progress windows are suppressed. Some methods e.g. zoning images or proof reading involve user interface elements anyway. The SilentMode property has no effect on these functions. ParentWindow property

See also:

ParentWindow property
HRESULT put_ ParentWindow(LONG Window); void SetParentWindow(LONG Window); Description: The methods of different interfaces involve user interface elements (windows, dialog boxes); the parent window of these elements can be controlled with this property. The parameter must be a valid window handle that becomes the parent of the displayed OmniPage windows or progress indicators. This parameter is typically the handle of the main window of the client application.

IProcess interface
The client can get the IProcess interface through a Login method of the IApplication, as described above. The IProcess is designed to perform the main functionality of OmniPage and to set and retrieve different processing parameters. The functionality can be arranged into the following topics. - Document management - Image capture - Layout decomposition - Recognition - Image and text export - Handling of settings - Scanner capabilities and settings The documentation is arranged according to these topics.

Document management
OmniPage Pro is a document-based (SDI) application. When users launch it, a new, empty document is created automatically. When the client application connects to OmniPage through the automation interface, a new document is similarly created. Like any other SDI applications, OmniPage allows to only one document file to be open at a time. Whenever a new document is created or an existing one is opened, the currently opened document is closed. The recognized pages from documents can be saved to file in a variety of formats (file types). The images from documents can also be saved to image files. It is also possible to save both recognized pages and images, along with the links between them, to a proprietary file type known as an OmniPage Document, with an extension *.opd. These OPD files can be reopened through this automation interface or by standalone installations of OmniPage Pro. The following group of methods manages document files within OmniPage and OmniPage Documents.

CreateDocument method
HRESULT CreateDocument(LONG *Errorcode) LONG CreateDocument()

Automation interface of OmniPage Pro 12

Description:

Closes the currently loaded document and creates a new, empty one. If the current document has unsaved changes, it is automatically saved or the creation of a new document is refused, depending on the AutoSave property.

OpenDocument method
HRESULT OpenDocument(BSTR OPDFilename, LONG *Errorcode) LONG OpenDocument(LPCTSTR DocumentName) Description: OpenDocument is used to open an existing OmniPage Document (*.opd) for processing. If the currently open document has unsaved changes, it is automatically saved or the opening of the new document is refused, depending on AutoSave property. DocumentName Identifies the OmniPage Document to be processed. This should contain the full path and name of the document. The document must be in OmniPage OPD format for this function to succeed.

Parameters:

See Also

SaveDocument, PutImage

SaveDocument method
HRESULT SaveDocument(BSTR DocumentName, LONG *Errorcode) LONG SaveDocument(LPCTSTR DocumentName) Description: SaveDocument is used to save an open document as an OmniPage Document on disk. If the goal is to save an open document in a different format, then ExportDocument should be used. DocumentName Specifies the name to be assigned to the OmniPage Document. This should contain the full path and name of the OPD. At least one image must have entered the document for this to be successful. If the document name is a NULL string (not recommended), the open document will be saved using its current name. If it has no name, an error will be returned. ExportDocument, OpenDocument

Parameters:

See Also

PrintImages method
HRESULT PrintImages(short FirstPage, short LastPage, LONG *Errorcode) LONG PrintImages(short FirstPage, short LastPage) Description: Parameter: See also: PrintImages is used to print images from the currently opened document. All pages or a range of pages can be printed depending on the input parameters. FirstPage and LastPage parameters specify the range of pages. If their value is 1 then all pages are printed. PrintText method

PrintText method
HRESULT PrintText(short FirstPage, short LastPage, LONG *Errorcode) LONG PrintText(short FirstPage, short LastPage)

Automation interface of OmniPage Pro 12

Description: Parameter: See also:

PrintText is used to print recognized pages from the currently opened document. All pages or a range of pages can be printed depending on the input parameters. FirstPage and LastPage parameters specify the range of pages. If their value is 1 then all pages are printed. PrintImages method

ReadDocument method
HRESULT ReadDocument (LONG PageNumber, LONG *Errorcode) LONG ReadDocument (LONG PageNumber); Description: Parameter: See Also: ReadDocument is used to read the specified page of the currently opened document out, using the currently installed text-to-speech system. PageNumber specifies the page to be read out. Use one-based index of the page. TTSStatus property, TTSEnabled property, PageCount property, StopReadOut method

StopReading method
HRESULT StopReading(LONG *Errorcode) LONG StopReading() Description: StopReading method is used to cancel reading page out.

TTSStatus property
HRESULT get_TTSStatus(VARIANT_BOOL *State) BOOL GetTTSStatus() Description: TTSStatus is a read-only Boolean property that indicates whether a text-to-speech system is installed or not.

TTSEnabled property
HRESULT get_TTSEnabled(VARIANT_BOOL * Enabled) HRESULT put_TTSEnabled(VARIANT_BOOL Enabled) BOOL GetTTSStatus() BOOL SetTTSStatus(BOOL Enabled) Description: TTSEnabled is a Boolean property to indicate whether a currently installed text-to-speech system is enabled or disabled. When set to TRUE the ReadingDocumentOut method can be used.

PageCount property
HRESULT get_PageCount(LONG *NumPages) LONG GetPageCount() Description: PageCount property indicates the number of pages in the currently open document. Use this property during printing or reading the document out.

Automation interface of OmniPage Pro 12

AutoSave property
HRESULT get_AutoSave(VARIANT_BOOL *Modified) HRESULT put_AutoSave(VARIANT_BOOL Modified) BOOL GetAutoSave () void SetAutoSave (BOOL) Description: AutoSave Boolean property is used to save the currently opened document without explicit calls to the SaveDocument method whenever a new document is created or an existing one is opened. The automatic save does not work on newly created documents that still have no filename. The CreateDocument and SaveDocument functions fail when the current document has been changed and the AutoSave property has a Boolean FALSE value. CreateDocument method, OpenDocument method.

See also:

DocumentModifiedFlag property
HRESULT get_DocModifiedFlag(VARIANT_BOOL *Modified) BOOL GetDocModifiedFlag () Description: DocModifiedFlag read-only property indicates whether the currently open document has been changed or not. The document is changed if a new image has been loaded or scanned into it; zones on pages are changed; any recognition has taken place or the OCR result has been corrected during proof-reading. Saving or exporting the document clears this flag. The client application should use this flag before closing any document containing unsaved modifications. AutoSave property

Comment: See also:

Image capture

ImportImage method
HRESULT ImportImage(BSTR Filename) void ImportImage(LPCTSTR Filename) Description: OmniPage maintains an internal file-list for image file names to be loaded. The client can append a file name to this list. This list is used by the LoadImages method when the value of the ImageSource property is SOURCE_DISK. Filename the full path of the image file to be appended to the internal file list. LoadImage method

Input parameters: See also:

LoadImages method
HRESULT LoadImages(LPCTSTR Filename, LONG *Errorcode) LONG LoadImages(LPCTSTR Filename) Description: LoadImages method is used to add images to the current document. a.) When the Filename input parameter contains a valid image file name, the image(s) are added to the current document independently

Automation interface of OmniPage Pro 12

10

Input parameters: Return value: See also:

from the specified ImageSource property. The behavior of the method depends on the value of the ImageSource property in other cases. b.) When the ImageSource property is SOURCE_DISK (and the Filename parameter has a NULL value), files are loaded from the internal list filled up by the ImportImage method. If the internal image list is empty, the Load Image File dialog is opened to locate the required image file. c.) When the ImageSource is SOURCE_SCANNER (and Filename parameter has NULL value), OmniPage starts scanning one page from the scanners flatbed or pages from the ADF until it is empty OmniPage provides progress monitoring during image loading. It can display its own progress monitor window or it can fire events to the client application through a Connection Point (callback) interface described later. Filename specifies an image file to be loaded optionally. It can have a NULL value. ImportImage method, ImageSource property, IOPScanner interface, Chapter Progress monitors

ImageSource property
HRESULT get_ImageSource(IMGSRC *Value) HRESULT put_ImageSource(IMGSRC Value) LONG GetImageSource() void SetImageSource(LONG ImageSource) Description: ImageSource property is used to define the source of images to be added to the currently opened document by the LoadImages method. The property can have the following enumerated values: SOURCE_DISK (0) - the next image will be loaded from disk. The user will be presented with the Open Image File dialog when LoadImage is called. SOURCE_SCANNER (1) - the next image will be loaded from the scanner. An image will be scanned using the current scanner settings when LoadImage is called. LoadImages method

See also:

InsertMode property
HRESULT get_InsertMode(INSERTMODE *pInsertPage) HRESULT put_InsertMode(INSERTMODE InsertPage) LONG GetInsertMode() LONG SetInsertMode(LONG PageInsert) Description: PageInsert property is used to control the order of loaded images within the document. The property can have the following enumerated values: INSERT_LAST the new pages are appended to the document INSERT_AFTERCURRENT insert the new pages after the current page INSERT_BEFORECURRENT - insert the new pages before the current page INSERT_FIRST insert the new pages at the start of the document. LoadImage method

See also:

Automation interface of OmniPage Pro 12

11

StartAddImage method
HRESULT StartAddImage(short w, short h, short bpp, short xres, short yres,short align, LONG *Errorcode) LONG StartAddImage(short w, short h, short bpp, short xres, short yres,short align) Description: Parameters AddIMageInit will set up for image download in strips, and initialize image parameters. w width of the image, in pixels h height of the image, in pixels bpp bits per pixel of the image xres x-resolution of the image, in dots per inch yres y-resolution of the image, in dots per inch align alignment of the image. Possible values are: 0 - BYTE alignment 1 - WORD alignment 2 - DWORD alignment If the function succeeds, the return value is 0; otherwise it is a negative error value. This call should be followed by AddImageData, to download the image to [OmniPage or OPLE], and completed by a call to StopAddImage. To OCR the page(s), call the method Recognize. AddImageData and StopAddImage methods

Return Value Comments

See also:

AddImageData method
HRESULT AddImageStart(short lineStart, short lineLen, const VARIANT vSafeArray, short dataSize, long *pError) LONG AddImageStart(short lineStart, short lineLen, const VARIANT vSafeArray, short dataSize) Description: AddImageData will download chunks of an image to OmniPage. The process should be started by a call to AddImageStart, and should be finished by StopAddImage. lineStart - the current line of data lineLen - number of scan lines vSafeArray - a VARIANTARG which contains the image data in its parray member dataSize - unused If the function succeeds, the return value is 0; otherwise it is a negative error value. vSafeArray should contain a SAFEARRAY of the image data in its parray member. Use the array manipulation functions to create the SAFEARRAY.

Parameters

Return Value Comments Example:

void HUGEP *pvData; SAFEARRAY FAR *psa = NULL; SAFEARRAYBOUND rgsabound[1]; VARIANT vaResult; // Initialize the VARIANT - this will be passed down as the VARIANTARG // parameter

Automation interface of OmniPage Pro 12 VariantInit( &vaResult ); rgsabound[0].lLbound = 0; rgsabound[0].cElements = (dataSize + 3) >> 2; // Create a SafeArray psa = SafeArrayCreate( VT_I4, 1, rgsabound ); // retrieve a pointer to the array data SafeArrayAccessData( psa, &pvData ); // copy the image data (pData) to the safearray memcpy( pvData, pData, dataSize ); // set the variable type to SafeArray V_VT( &vaResult ) = VT_ARRAY; // set the SafeArray member to our SafeArray V_ARRAY( &vaResult ) = psa; // Invoke the OLE call using vaResult as the VARIANTARG parameter // don't forget to free the data and destroy the SafeArray SafeArrayUnaccessData( psa ); SafeArrayDestroy( psa ); See also: StartAddImage and StopAddImage methods

12

StopAddImage method
HRESULT StopAddImage(LONG* Error) LONG StopAddImage( ) Description: Parameters Return Value Comments See Also StopAddImage signals the end of the image download and performs any necessary cleanup in the application. This call should be followed by ProcessImages to start the OCR process. none If the function succeeds, the return value will be 0; otherwise it will be a negative error number. none StartAddImage, AddImageData

Layout decomposition

LayoutFormat property
HRESULT get_LayoutDescription(LYTDESCR *pLayout) HRESULT put_LayoutDescription(LYTDESCR LayoutDescription) LONG GetLayoutDescription() void SetLayoutDescription(LONG LayoutDescription) Description: Parameters: The LayoutDescription property is used to control the layout format of the pages in the currently opened document. The following enumerated values are allowed: eLytFmtAuto (0) Automatic layout decomposition eLytFmtSingleColNoTbl (1) Single column without table eLytFmtMultiColNoTbl (2) Multiple column without table eLytFmtSingleColTbl (3) Single column with table eLytFmtSpreadsheet (4) Spreadsheet eLytFmtCustom (5) Custom layout eLytFmtTemplate (6) Use template

Automation interface of OmniPage Pro 12 If eLytFmtTemplate is used, the TemplateFile property has effect.

13

TemplateFilename property
HRESULT get_TemplateFilename(BSTR *TemplateFilename ) HRESULT put_TemplateFilename(BSTR TemplateFilename) CString GetTemplateFilename() void SetTemplateFilename(LPCTSTR TemplateFilename) Description: When the value of the LayoutFormat property is set to eLytFmtTemplate, the client can specify a template filename. Template files cannot be created via the automation interface. To create them, use the standard user interface of OmniPage.

AutoZoneState property
HRESULT get_AutoZoneState(VARIANT_BOOL *Value) HRESULT put_AutoZoneState(VARIANT_BOOL newValue) BOOL GetAutoZoneState() void SetAutoZoneState(BOOL newValue) Description: See also: The AutoZoneState property is used to control the default behavior of the ZoneImage method. ImageZone method

ZoneImage method
HRESULT ZoneImage(LONG Flag, LONG *Errorcode) LONG ZoneImage(LONG Flag) Description: Parameters: This method makes a simplified user interface of the OmniPage application visible to enable manual zoning. Flag: OP_ZONE_DEFAULT (-1) Manual or automatic zoning depending on the value of the AutoZoneState property; OP_ZONE_MANUAL (0) Manual zoning of images. Graphical UI is made visible; OP_ZONE_AUTO (1) Automatic zoning of images. Graphical UI stays hidden; AutoZoneState property

See also:

Recognition
The next set of properties and methods influences the recognition of pages in the currently opened document. The recognition result is not independent from other properties in particular the Layout decomposition and some processing properties.

RejectChar property
HRESULT get_RejectSymbol(short *Reject) HRESULT put_RejectSymbol(short Reject) SHORT GetOCRReject() void SetOCRReject(SHORT Reject) Description: This property is used to define the OCR reject character.

Automation interface of OmniPage Pro 12

14

Languages property
HRESULT get_Languages(LPDISPATCH *Value) LPDISPATCH GetLanguages() Description: The automation interface of OmniPage provides the IOPLanguages interface for enumerating recognition and UI languages. The returned Dispatch interface can be QueryInterface-d for the IOPLanguages interface. It has the following definition:

] interface IOPLanguages : IDispatch { [propget, id(1), helpstring("Get number of supported languages")] HRESULT Count([out, retval]long *Value); [propget, id(2), helpstring("Get the specified OCR language")] HRESULT Item([in]VARIANT index, [out, retval] LPDISPATCH *pValue); }; The elements of the collection are referenced by their (zero-based) index or by their name. The LPDISPATCH interface returned by the Item property can be QueryInterface-d for an IOPLanguage interface. It has the following definition: [ object, uuid(EEA8A5FC-5048-4A63-8BD2-3AEC83FB08D6), oleautomation, dual

object, uuid(9610F63C-E88D-4A72-B899-B0B509BD9AED), oleautomation, dual

] interface IOPLanguage : IDispatch { [propget, id(1), helpstring("Name of language")] HRESULT Name([out,retval]BSTR *pValue); [propget, id(2), helpstring("Identifier of language")] HRESULT Identifier([out,retval]long *pValue); [propget, id(3), helpstring("Is this language selected as OCR language")] HRESULT OCRLanguage([out,retval]VARIANT_BOOL *pValue); [propput, id(3), helpstring("Select/unselect this language as OCR language")] HRESULT OCRLanguage([in]VARIANT_BOOL Value); [propget, id(4), helpstring("Is this language can be UI language")] HRESULT UILanguageCapa([out, retval]VARIANT_BOOL *Value); [propget, id(5), helpstring("Is this language installed as UI language")] HRESULT UILanguage([out, retval]VARIANT_BOOL *Value); [id(6), helpstring("Install this language as UI language")] HRESULT SetUILanguage([out, retval]long *Error); };

Automation interface of OmniPage Pro 12

15

The Name property of the language object is a unique name to identify it. It can also be used by the client application to display on screen. The Identifier is a numeric value to identify the language. The Boolean OCRLanguage property is used to set the language as a recognition language. (More than one language is selectable for use on multilanguage documents.) The read-only UILanguageCapa property is used to determine whether a language can be set as a UI language or not. The UILanguage property is used to determine which language is selected as UI language. To change the UI language the client application should use the SetUILanguage method. The main screen, error messages and other dialog boxes displayed by the OmniPage UI use the selected UI language. This method returns with the OPOLE_NOTUILANGUAGE error code if the specified language is not a UI language.

UserDictionary property
HRESULT get_UserDictionary(BSTR *Filename) HRESULT put_UserDictionary(BSTR Filename) CString GetUserDictionary() void SetUserDictionary(LPCTSTR Filename) Description: The client can specify a user dictionary to be used during recognition. Passing a NULL string means no user dictionary will be used. The content of user dictionaries cannot be changed through the automation interface.

TrainingFile property
HRESULT get_TrainingFile(BSTR *Filename) HRESULT put_TrainingFile(BSTR Filename) CString GetTrainingFile() void SetTrainingFile(LPCTSTR Filename) Description: The client can control the use of a training file during recognition. Passing a NULL string means no training file will be used. Training of the OCR engine is not available through the automation interface.

Recognize method
HRESULT Recognize(RECMODE mode, LONG *Errorcode) LONG Recognize(LONG Flag) Description: The Recognize method is used to process all or non-processed pages of the currently opened document. Processing involves performing layout decomposition in line with values specified in LayoutFormat and other processing properties and then performing OCR on the specified pages. Progress indication is available and depends on the SilentMode property. The RECMODE Flag can have the following values RM_PROCESSALL(0) recognize all loaded pages RM_PROCESSNOTREC(1) recognize non-recognized pages LayoutFormat property; SilentMode property; AutoOrientation property; RetainColors property; AutoProofRead property, Chapter progress monitoring

Parameters: See also:

Automation interface of OmniPage Pro 12

16

Proof method
HRESULT Proof(eProofReadFlag Flag, LONG *Errorcode) LONG Proof(LONG Flag) Description: Parameters: Invokes the OCR Proofreader window of OmniPage to enable users to verify the OCR results. It can be launched after recognition automatically as defined by the AutoProof property. Flag input parameter can have the following enumerated values: OP_CHECKREC_MODAL(-2) OP_CHECKREC_DEFAULT(-1) Verify in accordance with the AutoProof property OP_CHECKREC_OFF(0) Skip proofreading OCR OP_CHECKREC_CURRPAGE(1) Verify current page OP_CHECKREC_ALLPAGES(2) Verify all pages AutoProof property;

See also:

ProcessImage method
HRESULT ProcessImage(BSTR Imagefile, BSTR OutputFile, LONG *Errorcode) LONG ProcessImage(LPCTSTR Imagefile, LPCTSTR OutputFile) Description: This method is a combination of other methods to make it easier to process images. This method can be substituted with the following series of methods: - CreateDocument(); - (optionally) AddImage(ImageFile); - LoadImage(); - Recognize(RM_PROCESSALL); - ExportSaveDocument(OutputFile); This method covers a typical usage of the automation interface, converting an image file to a specified text file. BSTR ImageFile: full path of the image file to convert. It can be a NULL value. In this case OmniPage launches the Load Image File dialog or starts scanning depending on the ImageSource property. BSTR OutputFile: full path of the converted text file. The export format and other parameters depend on the current settings. BSTR OutputFile can also be a NULL value. In this case OmniPage displays its Save As dialog box, allowing settings to be specified, including some not accessible through the automation interface.

Parameters:

Processing options

AutoOrientation property
HRESULT get_AutoOrientation(VARIANT_BOOL *Value) HRESULT put_AutoOrientation(VARIANT_BOOL newValue) BOOL GetAutoOrientation() void SetAutoOrientation(BOOL newValue) Description: This Boolean property is used to enable or disable detection of orientation and automatic rotation of images before recognition.

Automation interface of OmniPage Pro 12

17

RetainColor property
HRESULT get_RetainColor(RETAINCOLOROPT *Value) HRESULT put_RetainColor(RETAINCOLOROPT newValue) LONG GetRetainColors() void SetRetainColors(LONG newValue) Description: This three-state property is used to control font and background color retention during recognition. The value of the property can be one of the following: eRetainCol_Off(0) color retention is disabled eRetainCol_InvertedText(1) retain inverted text only eRetainCol_On(2) color retention is enabled

AutoProof property
HRESULT get_AutoProof(VARIANT_BOOL *Value) HRESULT put_AutoProof(VARIANT_BOOL newValue) BOOL GetAutoProof() void SetAutoProof(BOOL newValue) Description: This Boolean property is used to control automatic proofreading after the Recognize method. When the value of the property is TRUE, the Recognize method automatically invokes the OCR Proof reader dialog box to correct the recognized text. Proof and Recognize methods

See also:

Text export
The text export property group influences the behavior of ExportDocument method.

ExportDocument method
HRESULT ExportDocument (BSTR FileName, LONG *Errorcode) LONG ExportDocument(LPCTSTR FileName) Description: The ExportDocument method is a more complex method than the SaveDocument. Using this method the current document can be saved to disk, copied to the Clipboard or sent as mail attachments. The file format of the exported document can be set by the ExportTextFormat property and the export method by the ExportTarget property. Parameters FileName: Identifies the name of the file to save the converted document into. This name should include the full path and name of the file to save into. If this parameter has a NULL value, the Save As dialog appears allowing the location, file type, page range and other saving options to be specified. See Also SaveDocument method, ExportTextFormat and ExportTarget

properties

ExportTarget property
HRESULT get_ExportTarget(EXPTRG *Value) HRESULT put_ExportTarget(EXPTRG NewValue) long GetExportTarget() void SetExportTarget(long NewValue)

Automation interface of OmniPage Pro 12

18

Description:

This property specifies how OmniPage will export the currently loaded document via the ExportDocument method. There are three different targets specified by the following enumerated values: eExpToDisk Save document to one or more disk files. eExpToMail Save document to a temporary disk file and send it as one or more attachments to an empty e-mail message. The temporary file is deleted finally. eExpToClip Copy document to Clipboard in four different formats: ASCII text, Unicode text, comma-separated text and rich text format

ExportTextFormat property
HRESULT get_ExportTextFormat(VARIANT *Value) HRESULT put_ExportTextFormat(VARIANT NewValue) VARIANT GetExportTextFormat() void SetExportTextFormat(const VARIANT& newValue) Description: This property is used to specify the format (file type) of exported text. The format can be identified with the name of the format (e.g. Microsoft Word 2000, XP) or the unique identifier of the format. The name of the format is a localized string so it depends on the UI language setting. There are standard text converters built into OmniPage. Their identifiers are fixed. Users may create user-defined text converters based on standard converters. The identifier of these user-defined converters might vary when users manipulate the list of converters through the GUI of OmniPage. (User- defined text converters cannot be created through the automation interface.) Getting ExportTextFormat property: The returned VARIANT value contains an LPDISPATCH interface which can be QueryInterface-d for an IExportTextFormat interface. The properties of the current export format can be retrieved through this interface. Setting ExportTextFormat property: The client application should pass the name of the export format or an LPDISPATCH interface returned from the ExportFormats collection in the VARIANT parameter to set the required export text format. ExportTextFormats property to get more detailed information about available formats.

Parameters:

See also:

FormattingLevel property
HRESULT get_ExportFormattingLevel(FMTLVL *Value) HRESULT put_ExportFormattingLevel(FMTLVL NewValue) long GetExportFormattingLevel() void SetExportFormattingLevel(long NewValue) Description: This property is used to specify what kind of document formatting elements (font, paragraph, column formats) should be kept during export. The property can have the following enumerated values: eFmtLvlRemove (0) Remove all formatting elements and export text only. eFmtLvlRFP (1) Retain font and paragraph formatting eFmtLvlRFC (2) Retain flowing columns eFmtLvlTruePage (3) Retain all formatting elements

Automation interface of OmniPage Pro 12

19

See also:

Some values of FormattingLevel and ExportTextFormat properties preclude each other. For example: ExportTextFormat ASCII Text and FormattingLevel eFmtLvlTruePage because the ASCII Text export format cannot handle high-level formatting information. It is the responsibility of the automation interface to avoid mismatches between formatting level and file type. In the case of a mismatch, the format (file type) is retained and the formatting level is reduced to the highest supported level. In the stand-alone OmniPage Pro, mismatches cannot arise. FormattingLevelCapa property of IExportTextFormat interface

TextSeparation property
HRESULT get_TextSeparation(EXPFILEOPT *Value) HRESULT put_TextSeparation(EXPFILEOPT newValue) LONG GetTextSeparation() void SetTextSeparation(LONG newValue) Description: This property is used to specify how the currently loaded document should be separated during export. OmniPage can save the document into a single file or cut it into separate files. This property controls this behavior with the following enumerated values: eExpOneFile (0) create one export file from the document eExpSepPerPage (1) Each page is saved into a separate file eExpSepOnBlankpage (2) Separate document on blank pages

LaunchOnExport property
HRESULT get_LaunchOnExport(VARIANT_BOOL *Value) HRESULT SetLaunchOnExport(VARIANT_BOOL bNewValue) BOOL GetLaunchOnExport() void SetLaunchOnExport(BOOL bNewValue) Description: When the value of this property is true, OmniPage starts or activates the application associated with the selected export format and displays the currently saved document.

IExportTextFormats and IExportTextFormat interfaces

The IProcess interface has an ExportTextFormats property that provides a collection of the supported export text formats (file types) through the IExportTextFormats interface. This collection can be useful when the client application attempts to set a default export format or when it displays a Save Text dialog. Using the following calls the client application can retrieve the interface: HRESULT get_ExportTextFormats(LPDISPATCH *pValue) LPDISPATCH GetExportTextFormats() Description: The ExportTextFormats collection is used to enumerate all available text formats. The returned LPDISPATCH interface can be QueryInterface-d for the IExportTextFormats interface

The IExportTextFormats interface has the following definition: [ object, uuid(FA171E68-8E90-4F5F-9320-9FB7DF22D1AE), dual,

Automation interface of OmniPage Pro 12 oleautomation ] interface IExportTextFormats : IDispatch { [propget, id(1), helpstring("Get number of available export text formats")] HRESULT Count([out, retval]long *pValue); [propget, id(2), helpstring("Get the specified text format")] HRESULT Item([in]VARIANT index, [out, retval] LPDISPATCH *pValue); }; The get_Count property is used to get the total number of available export text formats including the standard and the user-defined formats. The get_Item property is used to get the dispatch interface to the converter specified by the index parameter. The index can be the order number (zero based index) of the converter or the name of the converter. The returned LPDISPATCH interface can be QueryInterface-d for the IExportTextFormat interface. It has the following definition. [ object, uuid(9E31809D-559B-4B4C-A51D-3B834EFF2649), dual, oleautomation ] interface IExportTextFormat : IDispatch { [propget, id(1), helpstring("Name of format")] HRESULT Name([out, retval]BSTR *pValue); [propget, id(2), helpstring("ID of format")] HRESULT FormatID([out, retval] long *pValue); [propget, id(3), helpstring("File extension")] HRESULT Extension([out, retval] BSTR *pValue); [id(4), helpstring("Set as default export text format")] HRESULT Set([out, retval]long *Error); [propget, id(5), helpstring("Output format level capability")] HRESULT FormatLevelCapa([out, retval] LONG *pValue); };

20

The Name property returns the localized name of the associated converter. The FormatID property contains the unique identifier of the converter. OmniPage provides for the creation of user-defined converters that are inherited from a standard one (such as Text, RTF or Word). The identifiers of these user-defined converters might change when the user removes some of them. The Extension property returns the default file extension of the associated format (e.g. .doc in the case of the Word 97, 2000 text format). Use the Set method to set the default export text format (Same as put_ExportTextFormat on the IProcess interface). The read-only FormatLevelCapa property is a bit field, which contains the possible formatting levels accepted by the specified converter. The meaning of the different fields is the following: bit 0. eFmtLvlRemove supported bit 1. eFmtLvlRFP supported bit 2. eFmtLvlRFC supported (called Flowing Page in the OmniPage GUI) bit 3. eFmtLvlTruePage supported Example: Using dual interface: IProcess *m_pIProcess;

Automation interface of OmniPage Pro 12 auto LPDISPATCH lp; lerr = m_pIProcess->get_ExportTextFormats(&lp); if (SUCCEEDED(lerr)) { if (lp == NULL) { lerr = E_NOINTERFACE; } else { auto IExportTextFormats *pfmts = NULL; lerr = lp->QueryInterface(IID_IExportTextFormats, (void**)&pfmts); lp->Release(); if (SUCCEEDED(lerr)) { auto long lcnt, i; pfmts->get_Count(&lcnt); auto char *pNameList = new char[_MAX_FORMATNAME * lcnt]; *pNameList = '\0'; for(i = 0; i < lcnt; i++) { auto VARIANT v; auto LPDISPATCH pDisp; auto BSTR bstrName, bstrExt; ::VariantInit(&v); v.vt = VT_I4; v.lVal = i; pfmts->get_Item(v, &pDisp); if (pDisp) { IExportTextFormat *pFmt; lerr = pDisp->QueryInterface(IID_IExportTextFormat, (void**)&pFmt); pDisp->Release(); if (FAILED(lerr)) { break; } pFmt->get_Name(&bstrName); pFmt->get_Extension(&bstrExt); pFmt->Release(); } pfmts->Release(); } See also: ExportTextFormat property

21

Image export
All page images from the current document can be saved to file. The following group of properties and methods covers this functionality.

Automation interface of OmniPage Pro 12

22

ExportImageFiles method
HRESULT ExportImageFiles(BSTR Filename, LONG *Errorcode) long ExportImageFiles (LPCTSTR Filename) Description: Parameters: Comments: See also: This method saves all pages of the currently loaded document as image into one file or separate files in a specified format. Parameter Filename specifies the full path of the target image file. When separated files are generated, numerical suffixes are appended to the specified name. The selected image format and image separation property may preclude each other (e.g. Windows Bitmap format does not support multi-page image files) ImageFileFormat and ImageSeparation properties

ExportImageFormat property
HRESULT get_ExportImageFormat(VARIANT *Value); HRESULT put_ExportImageFormat([in]VARIANT newValue); VARIANT GetExportImageFormat(); void SetExportImageFormat(const VARIANT& newValue); Description: This property specifies the image file format to which the pages of currently loaded document should be exported. The available formats can be enumerated by the ImageFormats collection. The list of supported image formats depends on the installed version of OmniPage. Getting current export image format: The returned VARIANT value is a LPDISPATCH type interface pointer that can be used to QueryInterface for an IImageFormat. The client application can retrieve several properties of the current image format through this interface. A more detailed description of this interface can be found under chapter ImageFormats collection. SaveImages method, ImageFormats collection

Parameter:

See also:

ImageSeparation property
HRESULT get_ImageSeparation(IMGFILEOPT *pValue) HRESULT put_ImageSeparation(IMGFILEOPT newValue) LONG GetImageSeparation() void SetImageSeparation(LONG newValue) Description: Parameter: OmniPage can save images into one multi-page file or separate files. This property controls this behavior. The input parameters can have the following enumerated values: eImgExpOneFile(0) creates a multipage image file ( for example, TIF or DCX) eImgExpSeparateFile(1) creates separate image files for each page SaveImages method

See also:

IImageFormats and IImageFormat interfaces

The IProcess interface has an ImageFormats property, which provides a collection of supported input and output image formats through the IImageFormats interface. Using the following calls the client application can retrieve the interface: HRESULT get_ImageFormats(IMAGEFORMATTYPE type, LPDISPATCH *pValue)

Automation interface of OmniPage Pro 12 LPDISPATCH GetImageFormats(LONG type) Description: Parameters:

23

This collection is used to enumerate all input and output image formats supported by OmniPage. The contents of this list depends on the installed version (Pro, SE, Office) of OmniPage. The input parameter type can be one of the following enumerated values. eEnumInputFormats (0) - Enumerate all input image formats eEnumOutputFormats (1) - Enumerate all output image formats eEnumAllFormats (2) - Enumerate all image formats The returned output parameter is an LPDISPATCH interface pointer that can be used to QueryInterface for an IImageFormats interface.

Here is the definition of the IImageFormats interface. [ object, uuid(704E1B9A-3CE9-4B7D-87F0-7BB3D8BC0AC7), oleautomation, dual ] interface IImageFormats : IDispatch { [propget, id(1), helpstring("Get number of supported image fileformats")] HRESULT Count([out, retval]long *Value); [propget, id(2), helpstring("Get the specified image fileformat")] HRESULT Item([in]VARIANT index, [out, retval] LPDISPATCH *pValue); }; The property Count retrieves the number of supported formats. The Item property retrieves a Dispatch interface to an image format description specified by the index parameter. The type of index can be a long value (VT_I4) that is the order number of the format or a string value (VT_BSTR) which is the localized name of the format (e.g. Bitmap Files). The returned Dispatch interface can be QueryInterface-d for an IImageFormat interface. Here is its definition: [ object, uuid(6D1B7576-1DE9-4C3B-80D8-C271FAC95194), oleautomation, dual

] interface IImageFormat : IDispatch { [propget, id(1), helpstring("Reference name of the image format")] HRESULT Name([out, retval]BSTR *Value); [propget, id(2), helpstring("Identifier of the image format")] HRESULT Identifier([out, retval] long *pValue); [propget, id(3), helpstring("Is Multi-page file supported")] HRESULT MultipageFormat([out, retval] VARIANT_BOOL *pValue); [propget, id(4), helpstring("Default extension of the file ")] HRESULT Extension([out, retval] BSTR *pValue); [id(5), helpstring("Set the current image format for export")] HRESULT Set([out, retval]long *Error); };

Automation interface of OmniPage Pro 12

24

The Name property returns with the localized name of the current image format. The Identifier returns its order number. The Boolean MultipageFormat property has a true value if the current format supports multi-page image files (for example, the TIF and DCX formats). The Extension property contains the default file extension associated with the current format. If the current format is a supported output format, the client application can use the Set method to set the format as a default export format (same as SetExportImageFormat on the IProcess interface). See also: ExportImageFormat property

Settings
Automation client applications are allowed to save a set of preferred settings into a separate standard Windows INI file and load this when they are launched again. The different settings can be set programmatically or it is possible to invoke the Options property sheet of OmniPage.

LoadSettings method
HRESULT LoadSettings(BSTR Filename, LONG*Errorcode) LONG LoadSettings(LPCTSTR Filename) Description: Parameter: See also: Loading the previously saved OmniPage settings from a Windows INI file. It is usually called when the client application starts using the automation interface. Filename specifies the Windows INI file that contains the settings to be loaded. SaveSettings method

SaveSettings method
HRESULT SaveSettings(BSTR Filename, LONG*Errorcode) LONG SaveSettings(BSTR Filename); Description: Save the current OmniPage settings into a Windows INI file. It is usually called when the client application finishes its work with OmniPage. Parameter: Filename specifies the Windows INI file where the settings should be saved. See also: LoadSettings method

OptionsDialog method
HRESULT OptionsDialog(LONG Flag, LONG *Errorcode); LONG OptionsDialog(LONG Flag); Description: This method launches the OmniPage Options Dialog to modify different properties via a UI. Parameter: The Flag parameter is a bit-field. It controls which pages of the Options property sheet should be displayed. The value can be composed from the following values (some of them are kept because of backward compatibility) OP_ACCURACY_PAGE = 0x0001, OP_EXPORT_PAGE = 0x0002, OP_CONFIGURE_PAGE = 0x0008, OP_SCANNER_PAGE = 0x0010, OP_DIRECT_PAGE = 0x0020, OP_DIRECT_MINI_PAGE = 0x0040,

Automation interface of OmniPage Pro 12

25

The following tabs are displayed when the relevant bit field is turned on OP_ACCURACY_PAGE

OP_SCANNER_PAGE

Automation interface of OmniPage Pro 12 OP_DIRECT_PAGE

26

OP_CONFIGURE_PAGE

Automation interface of OmniPage Pro 12 OP_EXPORT_PAGE

27

OP_DIRECT_MINI_PAGE

Description of usage of the property pages can be found in the OmniPages Online Help (including its Context-Sensitive Help).

IScanner interface
HRESULT get_Scanner(LPDISPATCH *Value) LPDISPATCH GetScanner() Description: The IScanner interface is designed to retrieve scanner capabilities and control the scanner settings. This interface can be accessed through the Scanner property of the IProcess interface. The returned LPDISPATCH interface can be QueryInterface-d for the IScanner interface. More detailed information about the interface properties is provided in the following chapters. See also: ImageSource property, LoadImages method (loading images from scanner image source).

Automation interface of OmniPage Pro 12

28

Scanner capabilities
The following properties give information about capabilities of currently installed scanners.

IsScannerAvailable method
HRESULT IsScannerAvailable(VARIANT_BOOL *Value) BOOL IsScannerAvailable() Description: This method is used to detect an installed scanner. The return value is true when a scanner is installed for OmniPage

IsTWAINBasicMode method
HRESULT IsTWAINBasicMode(VARIANT_BOOL *Value) BOOL IsTWAINBasicMode() Description: This method is used to determine whether the scanner is installed in TWAIN Basic mode. When the return value is true, the scanner parameters are not changeable programmatically.

BrightnessCap property
HRESULT get_BrightnesCap(VARIANT_BOOL *Value) BOOL GetBrightnessCap () Description: This property is used to determine whether the brightness value can be changed or not.

ContrastCap property
HRESULT get_ContrastCap(VARIANT_BOOL *Value) BOOL GetContrastCap () Description: This property is used to determine whether the contrast value can be changed or not.

PaperSizeCap property
HRESULT get_PaperSizeCap(LONG *Value) LONG GetPaperSizeCap () Description: Parameters: This property is used to determine what kind of paper sizes can be set for the installed scanner. The return value is a combination of the following bit fields. ps_UnassignedSize=0, ps_Letter=1, ps_A3=2, ps_A4=4, ps_A5=8, ps_B4=16, ps_B5=32, ps_Legal=64,

Automation interface of OmniPage Pro 12 ps_DLetter=128

29

ADFCap property
HRESULT get_ADFCap(VARIANT_BOOL *Value) BOOL GetADFCap () Description: This property is used to determine whether an ADF is installed or not.

ScanModeCap property
HRESULT get_ScanModeCap(LONG *Value) LONG GetScanModeCap () Desctiption: This property is used to determine what kind of scanning modes (blackand-white, grayscale or color modes) are supported. The return value can be one of the following values eScnMode_Undef (-1) not determined eScnMode_BW(0) black-and-white only eScnMode_Gray(1) grayscale (and BW) eScnMode_Color(2) all scanning modes are available

Scanner settings

Brightness property
HRESULT get_Brightness(short *Value) HRESULT put_Brightness(short nNewValue) short GetBrightness() void SetBrightness(short nNewValue) Description: This property is used to control the brightness of the scanner. The value can be changed between 1-100.

Contrast property
HRESULT get_Contrast(short *Value) HRESULT put_Contrast(short nNewValue) short GetContrast() void SetContrast(short nNewValue) Description: This property is used to control the contrast of the scanner. The value can be changed between 1-100.

Resolution property
HRESULT get_Resolution(long *Value) HRESULT put_Resolution(long nNewValue) long GetResolution() void SetResolution(long nNewValue) Description: This property is used to control the scanning resolution. The value of this property can be one of the following values eScnRes200dpi(1)

Automation interface of OmniPage Pro 12

30

eScnRes300dpi(2)

Scanmode property
HRESULT get_Scanmode(long *Value) HRESULT put_Scanmode(long nNewValue) long GetScanmode() void SetScanmode(long nNewValue) Description: This property is used to control the scanning mode (black-and-white, grayscale or color). The property can have one of the following predefined values. eScnMode_BW (0) - scan in BW mode eScnMode_Gray (1) - scan in grayscale mode eScnMode_Color (2) - scan in color mode

Papersize property
HRESULT get_Papersize(long *Value) HRESULT put_Papersize(long nNewValue) long GetPapersize() void SetPapersize(long nNewValue) Description: This property is used to control the preferred paper size during scanning. The accepted property values can be one of the following ps_Letter=1, ps_A3=2, ps_A4=4, ps_A5=8, ps_B4=16, ps_B5=32, ps_Legal=64, ps_DLetter=128

PageOrientation property
HRESULT get_PageOrientation(long *Value) HRESULT put_PageOrientation(long nNewValue) long GetPageOrientation() void SetPageOrientation(long nNewValue) Description: This property is used to control the page orientation. The accepted property value can be one of the following values. eOrient_Portrait(0) eOrient_Landscape(1)

Error handling
The methods of the IProcess interface have return values to describe the status of the execution. A zero return value means successful execution. The client application can get the LastError property which retrieves a localized error message. It can be displayed by the client to indicate the error.

LastError property
HRESULT get_LastError(BSTR *ErrorMessage)

Automation interface of OmniPage Pro 12 CString GetLastError() Description: This property contains the localized error message associated to the error that occurred during the last automation call.

31

Progress indication
There are time-consuming methods in the IProcess interface. Progress indication is desirable for the client application. There are two ways to implement it. If the client turns off the SilentMode property of the IApplication interface, OmniPage displays a progress indicator window to give some information about the current process. The parent of this window can be set by the ParentWindow property of IApplication. The other possibility puts the control of progress indication into the responsibility of the client application. It has to implement the IOPProgress interface defined by OmniPage: [ object, uuid(B7868728-2641-4BFC-B160-55BE16BB7A6A), oleautomation, dual

] interface IOPProgress : IDispatch { [id(1), helpstring("Start progress monitor")] HRESULT Start([in]long proctype); [id(2), helpstring("Progress monitor")] HRESULT Progress([in] long proctype, [in] long percent, [out, retval] long *CanContinue); [id(3), helpstring("Page number currently is under processing")] HRESULT SetPageNumber([in]long proctype); [id(4), helpstring("Progress monitor")] HRESULT Stop([in]long proctype); }; This interface has to be Advise-d to the IConnectionPoint interface of OmniPage. The same object in OmniPage implements the IProcess and the IConnectionPointContainer interfaces. The next example demonstrates how the client application should connect to OmniPage through the IConnectionPoint interface: - The CSampleProgress class implements the IOPProgress interface at the client side. Lets assume that it is inherited from the CCmdTarget class. - Its Init() member function is called before starting progress indication and it connects to the IConnectionPoint interface. HRESULT CSampleProgress::Init() { IConnectionPointContainer *pCPC; IUnknown *punk; IProcess *pProcess = GetIProcess(); //Get IProcess from IApplication punk = (IUnknown *)GetIDispatch(FALSE); HRESULT hr = pProcess->m_lpDispatch-> QueryInterface(IID_IConnectionPointContainer,(void**)&pCPC); if (hr == S_OK) { hr = pCPC->FindConnectionPoint(IID_IOPProgress, &m_pConnPoint); if (S_OK == hr) {

Automation interface of OmniPage Pro 12 hr = m_pConnPoint->Advise(punk, &m_dwCookie);

32

} return hr;

After this registration the client application should call other methods from IProcess and they will call back this interface to inform the state of progress. The calling sequence is like this: 1. IOPProgress::Start 2. IOPProgress::SetPageNumber 3. IOPProgress::Progress 4. if there are more pages to process then loop back to 2. 5. IOPProgress::Stop The client application can create its progress bar when the Start method is called and destroy it when Stop is called. The Progress method should return with a non-zero value if the execution should be stopped immediately. In this case the called method will return with a specific error code. The following methods can use this callback interface: - OpenDocument - SaveDocument - LoadImage - Recognize - ProcessImage - ExportDocument - ExportImageFiles Finally, if the client application turns the SilentMode property on but it does not register itself as ConnectionPoint then the mentioned methods are executed without any progress indication and they cannot be canceled.

Localization issues
There are some properties in the interface that are language-dependent. Their values depend on which localized version of OmniPage is installed. So the automation interface itself does not require any additional localization tasks.

Error codes
The following table contains the list of error codes that are defined by the automation interface. Note that some methods may return different error codes, which are supplied by OmniPage itself. Error code OPOLE_SUCCESS OPOLE_INIT OPOLE_INTERNAL Description Execution of the method succeeded The automation interface has not been initialized properly Internal error (like memory allocation error) occurred during execution Attempt to create or open a document while the currently open document has still not been saved Method

OPOLE_UNSAVEDFILE

OpenDocument StartAddImage AddImageData Recognize CreateDocument OpenDocument

Automation interface of OmniPage Pro 12

33

OPOLE_NOFILENAME

The current document has no filename. It could not be saved. The specified document could not be opened. The operation could not be performed. The document has no pages yet.

OPOLE_DOCOPENFAILED OPOLE_EMPTYDOC

CreateDocument OpenDocument SaveDocument ExportDocument OpenDocument ExportDocument SaveDocument ZoneImage Recognize Proof ExportImageFiles ExportDocument SaveDocument LoadImages LoadImages StopAddImage StartAddImage AddImageData StopAddImage ExportDocument OpenDocument SaveDocument LoadImage Recognize ProcessImage ExportDocument ExportImageFiles ZoneImage ReadDocument ReadDocument PrintImages PrintText ReadDocument Proof ExportImageFiles

OPOLE_DOCSAVEFAILED OPOLE_IMGSOURCE OPOLE_CREATENEWPAGE OPOLE_INVALIDPARAM OPOLE_IMAGESIZEERROR OPOLE_PROCESSNOTCOMPLETE OPOLE_ACTIONCANCELED

Saving current document failed. Internal error occurred. New page could not be added to the document Invalid parameter has been passed to the method The size of downloaded image is less or greater then expected The document cannot be exported, because not all pages have been recognized. The execution canceled by the user.

OPOLE_TTSNOTAVAIL OPOLE_TTSDISABLED OPOLE_OUTOFPAGERANGE

OPOLE_NOTEXT OPOLE_IMAGECONVERSION

OPOLE_IMAGESAVECOLOR

OPOLE_NOTUILANGUAGE

A Text-to-Speech engine is not installed A Text-to-Speech engine is not enabled Printing or reading out could not be performed because of invalid page index (These methods use 1-based indices.) The specified page has no text. It cannot be read out. ExportImageFiles method may return with this error code if the client application attempts to save multiple pages into a format that does not support it. ExportImageFiles method may return with this error code if the client application attempts to save a color image into a format that does not support it. The selected language is not a UI language.

ExportImageFiles

IOPLanguage::SetUILanguage