Automation Interface ENG

Automation interface of OmniPage Pro 12 1

Automation interface of OmniPage Pro 12

Last revision date: July 24, 2002


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


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


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 OmniPage’s 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.

IProcess

IExportTextFormats

IExportTextFormat

IOPLanguages

IOPLanguage

IOPScanner

IImageFormats

IImageFormat

IApplication

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.


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: This Boolean property indicates whether the OLE automation interface

is initialized properly or not. It is true after a successful login. See also: 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.

Parameter: Key is an encrypted character string that authorizes the client to use the interface in any edition of OmniPage.

Return value: 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.

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


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.

See also: ParentWindow property

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()


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.

Parameters: 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.

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.

Parameters: 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.

See Also ExportDocument, OpenDocument

PrintImages method HRESULT PrintImages(short FirstPage, short LastPage, LONG *Errorcode) LONG PrintImages(short FirstPage, short LastPage) Description: 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.

Parameter: FirstPage and LastPage parameters specify the range of pages. If their value is –1 then all pages are printed.

See also: PrintText method

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


Description: 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.

Parameter: FirstPage and LastPage parameters specify the range of pages. If their value is –1 then all pages are printed.

See also: PrintImages method

ReadDocument method HRESULT ReadDocument (LONG PageNumber, LONG *Errorcode) LONG ReadDocument (LONG PageNumber); Description: ReadDocument is used to read the specified page of the currently

opened document out, using the currently installed text-to-speech system.

Parameter: PageNumber specifies the page to be read out. Use one-based index of the page.

See Also: 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.


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.

See also: CreateDocument method, OpenDocument method.

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.

Comment: The client application should use this flag before closing any document containing unsaved modifications.

See also: AutoSave property

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.

Input parameters: Filename – the full path of the image file to be appended to the internal file list.

See also: LoadImage method

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


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 scanner’s 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.

Input parameters: Filename specifies an image file to be loaded optionally. It can have a NULL value.

Return value: See also: 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.

See also: LoadImages method

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. See also: LoadImage method


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: AddIMageInit will set up for image download in strips, and initialize

image parameters. 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

Return Value If the function succeeds, the return value is 0; otherwise it is a negative error value.

Comments 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.

See also: AddImageData and StopAddImage methods

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.

Parameters 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

Return Value If the function succeeds, the return value is 0; otherwise it is a negative error value.

Comments vSafeArray should contain a SAFEARRAY of the image data in its parray member. Use the array manipulation functions to create the SAFEARRAY.

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


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

StopAddImage method HRESULT StopAddImage(LONG* Error) LONG StopAddImage( ) Description: 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.

Parameters none Return Value If the function succeeds, the return value will be 0; otherwise it will be

a negative error number. Comments none See Also StartAddImage, AddImageData

Layout decomposition

LayoutFormat property HRESULT get_LayoutDescription(LYTDESCR *pLayout) HRESULT put_LayoutDescription(LYTDESCR LayoutDescription) LONG GetLayoutDescription() void SetLayoutDescription(LONG LayoutDescription) Description: The LayoutDescription property is used to control the layout format of

the pages in the currently opened document. Parameters: 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


If eLytFmtTemplate is used, the TemplateFile property has effect.

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: The AutoZoneState property is used to control the default behavior of

the ZoneImage method. See also: ImageZone method

ZoneImage method HRESULT ZoneImage(LONG Flag, LONG *Errorcode) LONG ZoneImage(LONG Flag) Description: This method makes a simplified user interface of the OmniPage

application visible to enable manual zoning. Parameters: 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;

See also: AutoZoneState property

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.


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:

[ object, uuid(9610F63C-E88D-4A72-B899-B0B509BD9AED), oleautomation, dual ] 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 ] 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); };


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 multi-language 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.

Parameters: The RECMODE Flag can have the following values RM_PROCESSALL(0) – recognize all loaded pages RM_PROCESSNOTREC(1) – recognize non-recognized pages See also: LayoutFormat property; SilentMode property; AutoOrientation

property; RetainColors property; AutoProofRead property, Chapter progress monitoring


Proof method HRESULT Proof(eProofReadFlag Flag, LONG *Errorcode) LONG Proof(LONG Flag) Description: 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.

Parameters: 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 See also: AutoProof property;

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.

Parameters: 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.

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.


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.

See also: Proof and Recognize methods

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)


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.)

Parameters: 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.

See also: ExportTextFormats property to get more detailed information about available formats.

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


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.

See also: 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,


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); }; 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;


… 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

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


ExportImageFiles method HRESULT ExportImageFiles(BSTR Filename, LONG *Errorcode) long ExportImageFiles (LPCTSTR Filename) Description: This method saves all pages of the currently loaded document as image

into one file or separate files in a specified format. Parameters: Parameter Filename specifies the full path of the target image file.

When separated files are generated, numerical suffixes are appended to the specified name.

Comments: The selected image format and image separation property may preclude each other (e.g. Windows Bitmap format does not support multi-page image files)

See also: 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.

Parameter: 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.

See also: SaveImages method, ImageFormats collection

ImageSeparation property HRESULT get_ImageSeparation(IMGFILEOPT *pValue) HRESULT put_ImageSeparation(IMGFILEOPT newValue) LONG GetImageSeparation() void SetImageSeparation(LONG newValue) Description: OmniPage can save images into one multi-page file or separate files.

This property controls this behavior. Parameter: 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

See also: SaveImages method

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)


LPDISPATCH GetImageFormats(LONG type) Description: 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.

Parameters: 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); };


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: Loading the previously saved OmniPage settings from a Windows INI

file. It is usually called when the client application starts using the automation interface.

Parameter: Filename specifies the Windows INI file that contains the settings to be loaded.

See also: 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,


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

OP_ACCURACY_PAGE

OP_SCANNER_PAGE


OP_DIRECT_PAGE

OP_CONFIGURE_PAGE


OP_EXPORT_PAGE

OP_DIRECT_MINI_PAGE

Description of usage of the property pages can be found in the

OmniPage’s 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).


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: This property is used to determine what kind of paper sizes can be set

for the installed scanner. Parameters: 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,


ps_DLetter=128

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 (black-

and-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)


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)


CString GetLastError() Description: This property contains the localized error message associated to the

error that occurred during the last automation call.

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. Let’s 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) {


hr = m_pConnPoint->Advise(punk, &m_dwCookie); } } 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 Description Method OPOLE_SUCCESS Execution of the method

succeeded

OPOLE_INIT The automation interface has not been initialized properly

OPOLE_INTERNAL Internal error (like memory allocation error) occurred during execution

OpenDocument StartAddImage AddImageData Recognize

OPOLE_UNSAVEDFILE Attempt to create or open a document while the currently open document has still not been saved

CreateDocument OpenDocument


OPOLE_NOFILENAME The current document has no filename. It could not be saved.

CreateDocument OpenDocument SaveDocument ExportDocument

OPOLE_DOCOPENFAILED The specified document could not be opened.

OpenDocument

OPOLE_EMPTYDOC The operation could not be performed. The document has no pages yet.

ExportDocument SaveDocument ZoneImage Recognize Proof ExportImageFiles

OPOLE_DOCSAVEFAILED Saving current document failed.

ExportDocument SaveDocument

OPOLE_IMGSOURCE Internal error occurred. LoadImages OPOLE_CREATENEWPAGE New page could not be added

to the document LoadImages StopAddImage

OPOLE_INVALIDPARAM Invalid parameter has been passed to the method

StartAddImage AddImageData

OPOLE_IMAGESIZEERROR The size of downloaded image is less or greater then expected

StopAddImage

OPOLE_PROCESSNOTCOMPLETE The document cannot be exported, because not all pages have been recognized.

ExportDocument

OPOLE_ACTIONCANCELED The execution canceled by the user.

OpenDocument SaveDocument LoadImage Recognize ProcessImage ExportDocument ExportImageFiles ZoneImage

OPOLE_TTSNOTAVAIL A Text-to-Speech engine is not installed

ReadDocument

OPOLE_TTSDISABLED A Text-to-Speech engine is not enabled

ReadDocument

OPOLE_OUTOFPAGERANGE Printing or reading out could not be performed because of invalid page index (These methods use 1-based indices.)

PrintImages PrintText ReadDocument

OPOLE_NOTEXT The specified page has no text. It cannot be read out.

Proof

OPOLE_IMAGECONVERSION 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

OPOLE_IMAGESAVECOLOR 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.

ExportImageFiles

OPOLE_NOTUILANGUAGE The selected language is not a UI language.

IOPLanguage::SetUILanguage

Date post:	04-Mar-2015
Category:	Documents
Upload:	rrtc1988
View:	94 times
Download:	2 times