Simple Multipage Document Handling Module

Simple document handling functions. RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X. More...

Typedefs
typedef struct RECDOCSTRUCT *	HDOC
	Document handle.
Enumerations
enum	HPAGESaveFlags {   HPSF_Default = 0x0000,   HPSF_SaveAll = 0xFFFF }
	Possible enumerations for the "APIPlus.HPAGE.SaveFlags" setting. More...
Functions
RECERR RECAPIPLS	RecCreateDoc (int sid, LPCTSTR pDocFile, HDOC *phDoc, int mode)
	Create an OmniPage document file or folder.
RECERR RECAPIPLS	RecOpenDoc (int sid, LPCTSTR pDocFile, HDOC *phDoc)
	Open an OmniPage document file or folder.
RECERR RECAPIPLS	RecCloseDoc (int sid, HDOC hDoc)
	Close an OmniPage document.
RECERR RECAPIPLS	RecDeleteDoc (LPCTSTR pDocName)
	Deletes an OmniPage document file or folder.
RECERR RECAPIPLS	RecSaveDoc (int sid, HDOC hDoc, LPCTSTR pDocFile)
	Save an OmniPage document to file.
RECERR RECAPIPLS	RecGetPageCount (int sid, HDOC hDoc, int *pnPages)
	Get the number of pages of an OmniPage document.
RECERR RECAPIPLS	RecInsertPage (int sid, HDOC hDoc, HPAGE hPage, int iPage)
	Insert an HPAGE as a new page into a document.
RECERR RECAPIPLS	RecUpdatePage (int sid, HDOC hDoc, int iPage, HPAGE hPage)
	Update a page in a document specified by an HPAGE.
RECERR RECAPIPLS	RecGetPage (int sid, HDOC hDoc, int iPage, HPAGE *phPage)
	Retrieve HPAGE from a document.
RECERR RECAPIPLS	RecDeletePage (int sid, HDOC hDoc, int iPage)
	Delete a page from a document.
RECERR RECAPIPLS	RecMovePage (int sid, HDOC hDoc, int iPageFrom, int iPageTo)
	Move a page in a document.
RECERR RECAPIPLS	RecConvert2Doc (int sid, HDOC hDoc, LPCTSTR pOutputFilename)
	Convert and export an OmniPage document to the final output document.
RECERR RECAPIPLS	RecGetPageStatistics (int sid, HDOC hDoc, int iPage, STATISTIC *stat)
	Getting recognition statistics.
RECERR RECAPIPLS	RecCreatePageStore (int sid, HDOC hDoc, int storeId, HPAGE hPage)
	Create a Page Store inside a document and attach a page to it.
RECERR RECAPIPLS	RecDeletePageStore (int sid, HDOC hDoc, int storeId)
	Delete a Page Store from inside a document.
RECERR RECAPIPLS	RecGetPageStore (int sid, HDOC hDoc, int storeId, HPAGE *phPage)
	Create a handle for an existing Page Store inside a document.
RECERR RECAPIPLS	RecFormatPageStore (int sid, HPAGE hPage)
	Run Format Detection on a page attached to a Page Store.
Document Storage Mode
These values can be used as the mode at RecCreateDoc.
#define	DOC_NORMAL   0
	Normal Storage mode: The document is a compound file. This mode is supported on: Windows. On other platforms it works as DOC_FOLDER.
#define	DOC_FOLDER   1
	Folder Storage mode: The document is a set of files in a folder.

---

Detailed Description

Simple document handling functions. RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

With these functions the User's application can implement document-based solutions. The application can create (RecCreateDoc) multi-page documents. The application can insert recognized pages (HPAGE's) that have been processed using KernelAPI functions.

The RecAPIPlus Document can be handled at two levels:

• Page level: In this case the Document is a set of Page Stores. Pages are independent of each other, not used as a connected document. (E.g. Page Stores are not assigned to a page number inside the document; they just have an identifier which is independent from their final place in a document.)
  See RecCreatePageStore, RecGetPageStore.
  Page level functions are needed mostly if recognition is done in multiple processes. After creating the document in one process it can be opened in other processes, too, and concurrent page level use is possible in all those processes (of course the processes should work on different pages).
• Document level: In this case pages are inserted into the document at a given page number (RecInsertPage). The application can delete or move pages or save and load the document to and from the proprietary OPD file type. When the document is ready, the application can export it (RecConvert2Doc) into the output file, using the appropriate output format like PDF, Word, etc. (RecSetOutputFormat). Document level functions must be called in a single process only.

It is not necessary to step to the Document level; an HDOC can be used exclusively on the Page level, too. This is useful when pages are processed in multiple processes, saved to Page Stores, then when all the pages are done, converted to a file or files with kRecConvert2DTXT calls.

---

Typedef Documentation

typedef struct RECDOCSTRUCT* HDOC

Document handle.

This is handle for an OmniPage document. Every function which handles a document needs it as an input parameter.

---

Enumeration Type Documentation

enum HPAGESaveFlags

Possible enumerations for the "APIPlus.HPAGE.SaveFlags" setting.

Enumerator:

HPSF_Default	Save default elements.
HPSF_SaveAll	Save all HPAGE elements.

---

Function Documentation

RECERR RECAPIPLS RecCloseDoc	(	int	sid,
		HDOC	hDoc
	)

Close an OmniPage document.

This closes an OmniPage document when it is no longer being used. The document handle becomes invalid.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

In DOC_NORMAL mode the OPD file is automatically saved before closing.

The specification of this function in C# is:

 RECERR RecCloseDoc(int sid, IntPtr hDoc); 

The specification of this function in Java is:

 int RecCloseDoc(int sid, HDOC hDoc) 

RECERR RECAPIPLS RecConvert2Doc	(	int	sid,
		HDOC	hDoc,
		LPCTSTR	pOutputFilename
	)

Convert and export an OmniPage document to the final output document.

This creates a document file from an OmniPage document. The new document file's type and format can be given by RecSetOutputFormat.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	pOutputFilename	Pointer to an output file name.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X. However not all the output formats are supported on all of these platforms. See details.

In the Microsoft Word and Power Point programs, the size of the page is limited. The width and height of the page must be between 0.1 and 22 inches. Because of this, if you scanned or loaded a page that is larger than this limit, you cannot save it into Flowing Page or True Page formats with *.rtf and *.docx and *.pptx file extensions. These formats try to retain the original page size and layout. If you try to save this, you will get an error message and the file will not be saved.

The specification of this function in C# is:

 RECERR RecConvert2Doc(int sid, IntPtr hDoc, string outputFilename); 

The specification of this function in Java is:

 int RecConvert2Doc(int sid, HDOC hDoc, String pOutputFilename) 

RECERR RECAPIPLS RecCreateDoc	(	int	sid,
		LPCTSTR	pDocFile,
		HDOC *	phDoc,
		int	mode
	)

Create an OmniPage document file or folder.

This creates a new OmniPage document, and also a disk file or folder for it. It also generates a document handle for this document.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pDocFile	Path to the OPD file (DOC_NORMAL mode) or folder (DOC_FOLDER mode). In DOC_NORMAL mode if pDocFile is an empty string, OPD file will not be created after closing the document. If you are not interested in persistent OPD files, use empty string as file name. It speeds up RecCreateDoc / RecInsertPage / RecConvert2Doc / RecCloseDoc workflow. In DOC_FOLDER mode pDocFile cannot be an empty string.
[out]	phDoc	Contains the handle of the created document.
[in]	mode	Specifies the Document Storage Mode. Can be either DOC_NORMAL or DOC_FOLDER.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

The OmniPage document file extension is "OPD", but other extensions can be used as well.

DOC_NORMAL mode is supported on: Windows. On other platforms it works as DOC_FOLDER.

The created OPD file or folder can be deleted by RecDeleteDoc.

The specification of this function in C# is:

 RECERR RecCreateDoc(int sid, string DocFile, out IntPtr hDoc, DOCOPENMODE mode); 

The specification of this function in Java is:

 int RecCreateDoc(int sid, String pDocFile, HDOC phDoc, int mode) 

RECERR RECAPIPLS RecCreatePageStore	(	int	sid,
		HDOC	hDoc,
		int	storeId,
		HPAGE	hPage
	)

Create a Page Store inside a document and attach a page to it.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	storeId	Page Store identifier.
[in]	hPage	Handle of a page.

Return values:

RECERR

Note:

This function is supported on: Windows, Linux, Embedded Linux, Mac OS X.

hPage is saved to the Page Store. Any future changes done to hPage will also be saved to the store when hPage is kRecFreeImg'd. The Page Store is not removed even when hPage is freed; it is removed only by RecDeletePageStore or RecDeleteDoc.

The storeId identifier can be any positive number. (It could be the 1 based serial number of the given page, but this is not necessary.) A second call of this function with the same storeId overwrites the previous content. Take care not to have the previous hPage still in memory as multiple Page Store handles are not supported.

hDoc must have been created in DOC_FOLDER mode.

This function is designed for a multiprocessing environment. Page Stores can be created in a different process, too, not only in the one that created the Document.

The specification of this function in C# is:

 RECERR RecCreatePageStore(int sid, IntPtr hDoc, int storeId, IntPtr hPage); 

The specification of this function in Java is:

 int RecCreatePageStore(int sid, HDOC hDoc, int storeId, HPAGE hPage) 

RECERR RECAPIPLS RecDeleteDoc

(

LPCTSTR

pDocName

)

Deletes an OmniPage document file or folder.

This deletes an existing OmniPage document file or folder in the file system.

Parameters:

[in]

pDocName

Path to the OPD file or folder.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

The specification of this function in C# is:

 RECERR RecDeleteDoc(string DocName); 

The specification of this function in Java is:

 int RecDeleteDoc(String pDocName) 

RECERR RECAPIPLS RecDeletePage	(	int	sid,
		HDOC	hDoc,
		int	iPage
	)

Delete a page from a document.

This removes a page from an open OmniPage document. The page will be deleted.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	iPage	Page index.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

The specification of this function in C# is:

 RECERR RecDeletePage(int sid, IntPtr hDoc, int iPage); 

The specification of this function in Java is:

 int RecDeletePage(int sid, HDOC hDoc, int iPage) 

RECERR RECAPIPLS RecDeletePageStore	(	int	sid,
		HDOC	hDoc,
		int	storeId
	)

Delete a Page Store from inside a document.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	storeId	Page Store identifier.

Return values:

RECERR

Note:

This function is supported on: Windows, Linux, Embedded Linux, Mac OS X.

Take care not to have a handle for the Page Store in memory. Free the handle (if any) with kRecFreeImg before deleting the store.

The specification of this function in C# is:

 RECERR RecDeletePageStore(int sid, IntPtr hDoc, int storeId); 

The specification of this function in Java is:

 int RecDeletePageStore(int sid, HDOC hDoc, int storeId) 

RECERR RECAPIPLS RecFormatPageStore	(	int	sid,
		HPAGE	hPage
	)

Run Format Detection on a page attached to a Page Store.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hPage	Page Store handle.

Return values:

RECERR

Note:

This function is supported on: Windows, Linux, Embedded Linux, Mac OS X.

hPage must be a Page Store handle, not a simple Page handle. Detected format data is saved to the Page Store and will be used for document conversion.

The specification of this function in C# is:

 RECERR RecFormatPageStore(int sid, IntPtr hPage); 

The specification of this function in Java is:

 int RecFormatPageStore(int sid, HPAGE hPage) 

RECERR RECAPIPLS RecGetPage	(	int	sid,
		HDOC	hDoc,
		int	iPage,
		HPAGE *	phPage
	)

Retrieve HPAGE from a document.

It copies most of the information from a document page to a HPAGE.

Parameters:

[in]	sid	Session ID.
[in]	hDoc	Document handle.
[in]	iPage	Index of the requested page.
[out]	phPage	Contains the handle of the requested page.

Return values:

RECERR

Note:

If you want to store and retrieve a HPAGE with all its elements like recognized letters you have to change "APIPlus.HPAGE.SaveFlags" setting (HPAGESaveFlags) to HPSF_SaveAll before calling RecInsertPage.

The specification of this function in C# is:

 RECERR RecGetPage(int sid, IntPtr hDoc, int iPage, out IntPtr hPage); 

The specification of this function in Java is:

 int RecGetPage(int sid, HDOC hDoc, int iPage, HPAGE phPage) 

RECERR RECAPIPLS RecGetPageCount	(	int	sid,
		HDOC	hDoc,
		int *	pnPages
	)

Get the number of pages of an OmniPage document.

This asks the current number of pages in the OmniPage document.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[out]	pnPages	Contains the page number.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

The specification of this function in C# is:

 RECERR RecGetPageCount(int sid, IntPtr hDoc, out int nPages); 

The specification of this function in Java is:

 int RecGetPageCount(int sid, HDOC hDoc, int[] pnPages) 

RECERR RECAPIPLS RecGetPageStatistics	(	int	sid,
		HDOC	hDoc,
		int	iPage,
		STATISTIC *	stat
	)

Getting recognition statistics.

This function retrieves the statistics of the recognition of the specified page. The values are the number of characters, words and rejected characters and time information for each part of the recognition process.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	iPage	Index of the page to be examined.
[out]	stat	Buffer for statistics.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

The specification of this function in C# is:

 RECERR RecGetPageStatistics(int sid, IntPtr hDoc, int iPage, out STATISTIC stat); 

The specification of this function in Java is:

 int RecGetPageStatistics(int sid, HDOC hDoc, int iPage, STATISTIC stat) 

RECERR RECAPIPLS RecGetPageStore	(	int	sid,
		HDOC	hDoc,
		int	storeId,
		HPAGE *	phPage
	)

Create a handle for an existing Page Store inside a document.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	storeId	Page Store identifier.
[out]	phPage	Contains the handle of the requested Page Store.

Return values:

RECERR

Note:

This function is supported on: Windows, Linux, Embedded Linux, Mac OS X.

The returned Page Store handle is attached to the Page Store. The content of the file is read only as needed, and any changes done to the returned HPAGE are written to the store. The handle must be freed by kRecFreeImg when not needed any more. Freeing the handle does not remove the Page Store itself!

Take care not to have multiple handles for the same Page Store! Close all Page Store handles before RecConvert2Doc.

A similar function is RecGetPage, but that one creates an independent page (a copy).

The specification of this function in C# is:

 RECERR RecGetPageStore(int sid, IntPtr hDoc, int storeId, out IntPtr hPage); 

The specification of this function in Java is:

 int RecGetPageStore(int sid, HDOC hDoc, int storeId, HPAGE phPage) 

RECERR RECAPIPLS RecInsertPage	(	int	sid,
		HDOC	hDoc,
		HPAGE	hPage,
		int	iPage
	)

Insert an HPAGE as a new page into a document.

This inserts an HPAGE into an opened document. During insertion, PageFormatter is applied and at the end of the process, this function frees the HPAGE. The HPAGE must contain a BW or OCR image. By default you must not free HPAGE, because RecInsertPage frees it (see also notes). This page will no longer be accessible via KernelAPI functions.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	hPage	Handle of a page.
[in]	iPage	Insert before this page. -1 append the page.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

hPage can be either a simple page handle or a Page Store handle. In the first case the page is saved to a Page Store then formatted. In the latter case the existing Page Store is just assigned to the specified page number then formatted.

If the application changes APIPlus.FreehPageAfterInsert setting to false, HPAGE will not be freed and the application can use it, but it has to be freed later. In this case there is no connection between the HPAGE and the HDOC after the function returns, i.e. modifications on either do not affect on the other.

The specification of this function in C# is:

 RECERR RecInsertPage(int sid, IntPtr hDoc, IntPtr hPage, int iPage); 

The specification of this function in Java is:

 int RecInsertPage(int sid, HDOC hDoc, HPAGE hPage, int iPage) 

RECERR RECAPIPLS RecMovePage	(	int	sid,
		HDOC	hDoc,
		int	iPageFrom,
		int	iPageTo
	)

Move a page in a document.

This changes the page index of a page in an open OmniPage document.

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	iPageFrom	Starting page index.
[in]	iPageTo	Destination page index.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

The specification of this function in C# is:

 RECERR RecMovePage(int sid, IntPtr hDoc, int iPageFrom, int iPageTo); 

The specification of this function in Java is:

 int RecMovePage(int sid, HDOC hDoc, int iPageFrom, int iPageTo) 

RECERR RECAPIPLS RecOpenDoc	(	int	sid,
		LPCTSTR	pDocFile,
		HDOC *	phDoc
	)

Open an OmniPage document file or folder.

This opens an existing OmniPage document file or folder in the file system. It also generates a document handle for this document.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pDocFile	Path to the OPD file or folder.
[out]	phDoc	Contains the handle of the opened document.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

An OPD file or folder can be deleted by RecDeleteDoc.

The specification of this function in C# is:

 RECERR RecOpenDoc(int sid, string DocFile, out IntPtr hDoc); 

The specification of this function in Java is:

 int RecOpenDoc(int sid, String pDocFile, HDOC phDoc) 

RECERR RECAPIPLS RecSaveDoc	(	int	sid,
		HDOC	hDoc,
		LPCTSTR	pDocFile
	)

Save an OmniPage document to file.

This saves an OmniPage document to another file.

Parameters:

[in]	sid	Settings Collection ID.
[in]	pDocFile	Path to the OPD file.
[in]	hDoc	Document handle.

Return values:

RECERR

Note:

RecAPIPlus level of CSDK is supported on: Windows, Linux, Embedded Linux, Mac OS X.

In DOC_FOLDER mode pDocFile must be the same folder as specified in RecCreateDoc.

An OPD file or folder can be deleted by RecDeleteDoc.

The specification of this function in C# is:

 RECERR RecSaveDoc(int sid, IntPtr hDoc, string DocFile); 

The specification of this function in Java is:

 int RecSaveDoc(int sid, HDOC hDoc, String pDocFile) 

RECERR RECAPIPLS RecUpdatePage	(	int	sid,
		HDOC	hDoc,
		int	iPage,
		HPAGE	hPage
	)

Update a page in a document specified by an HPAGE.

This overwrites a page in an open OmniPage document. The input page is HPAGE which will be freed at the end of the function, and cannot be used anymore (see also notes).

Parameters:

[in]	sid	Settings Collection ID.
[in]	hDoc	Document handle.
[in]	iPage	Page index.
[in]	hPage	Handle of a page.

Return values:

RECERR

Note:

This function is supported on: Windows.

If the application changes APIPlus.FreehPageAfterInsert setting to false, HPAGE will not be freed and the application can use it, but it has to be freed later. In this case there is no connection between the HPAGE and the HDOC after the function returns, i.e. modifications on either do not affect on the other.

The specification of this function in C# is:

 RECERR RecUpdatePage(int sid, IntPtr hDoc, int iPage, IntPtr hPage); 

The specification of this function in Java is:

 int RecUpdatePage(int sid, HDOC hDoc, int iPage, HPAGE hPage)