CIB ocr technical manual (EN)

11. Technical interface: Native functions

This chapter provides a brief overview of native functions.

CIB ocr job handle
CibOcrJobCreate
CibOcrJobSetProperty
CibOcrJobSetPropertyW
CibOcrJobGetProperty
CibOcrJobGetPropertyW
CibOcrJobGetProgress
CibOcrJobStart
CibOcrJobFree
CibOcrJobCancel
CibOcrGetVersion
CibOcrGetVersionText
CibOcrGetVersionTextW
CibOcrJobGetErrorText
CibOcrJobGetErrorTextW
CibOcrJobGetError

CIB ocr job handle

Every CIB ocr task is assigned  to a „job handle“ of the type Handle* . This object represents the task. The steps 

  • Setting and reading properties(CibOcrJobSetProperty/ CibOcrJobGetProperty)
  • Executing the task(CibOcrJobStart)
  • Getting error information(CibOcrJobGetError/ CibOcrJobGetErrorText)

always refer to such a job handle. 

A CIB ocr task is initiated by creating a job handle ( CibOcrJobCreate). After setting the necessary properties and running the task the job handle is released again ( CibOcrJobFree ). 


CibOcrJobCreate

bool exportfunc CibOcrJobCreate(Handle *job); 

This method creates a job handle. The Job-handle is given to all  subsequent functions to ensure thread-security. It should be released again with CibOcrJobFree  after the task is completed. 

If no error occurs, the function result is TRUE, otherwise  FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Creates a new job handle and stores it at *Job   


CibOcrJobSetProperty

bool  exportfunc  CibOcrJobSetProperty  (Handle job, const char *name, const char *value); 

This function allows setting additional properties for a merge run. The names and values are expected to be UTF-8 encoded zero terminated strings. 

If no error occurs, the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the job that this property refers to 

Char* 

Name 

Name of the property that is to be set 

Char* 

Value 

Value of the property that is to be set 


CibOcrJobSetPropertyW

Windows 

bool  exportfunc  CibOcrJobSetProperty W (Handle job, const  wchar *name, const  wchar  *value );  

This function allows setting additional properties for a merge run. The names and values are expected to be zero terminated wide strings.  

If no error occurs, the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the job that this property refers to 

wchar* 

Name 

Name of the property that is to be set 

wchar* 

Value 

Value of the property that is to be set 


CibOcrJobGetProperty

bool  exportfunc  CibOcrJobGetProperty  (Handle *job, const char *name, const char *buffer, int size); 

This function returns the property values that are currently set into the specified buffer. The returned names and values are zero terminated strings in UTF-8 encoding. 

If no error occurs, the function result is TRUE, otherwise FALSE. 

Type 

Value 

Description 

Handle* 

Job 

Handle of the job that this property refers to 

char* 

Name 

Name of the property whose value is to be returned 

char* 

Buffer 

The property’s value that is currently set 

int 

Size 

Maximum buffer length 


CibOcrJobGetPropertyW

Windows 

bool  exportfunc  CibOcrJobGetProperty W (Handle *job, const  wchar *name, const  wchar  *buffer, int size );  

This function returns the property values that are currently set into the specified buffer. The returned names and values are zero terminated wide strings. 

If no error occurs, the function result is TRUE, otherwise FALSE. 

 

Type 

Value 

Description 

Handle* 

Job 

Handle of the job that this property refers to 

wchar* 

Name 

Name of the property whose value is to be returned 

wchar* 

Buffer 

The property’s value that is currently set 

int 

Size 

Maximum buffer length 


CibOcrJobGetProgress

(From CIB ocr version 2.3.2) 

bool exportfunc CibOcrJobGetProgress(Handle* job, char *buffer, size_t size); 

Gets percent of recognition progress. 

This function fills buffer by the string:  
<page_number> <page_count> <page_progress> 

 

  • <page_number>       number of page processed at the moment<
  • <page_count>           total page count
  • <page_progress>     progress for current page

 

Special values <page_progress>: 

  • 1   Recognition proces has not started
  • 2   Recognition finished successfully
  • 3   Recognition cancelled
  • 4   Recognition finished with error

 

If no error occurs, the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the job that this property refers to  

char* 

Buffer 

The property’s value that is currently set 

int 

Size 

Maximum buffer length 

 


CibOcrJobStart

bool exportfunc CibOcrJobStart(Handle *job); 

Starts a CIB ocr-Job.  

If no error occurs, the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the job that is to be started. 


CibOcrJobFree

bool exportfunc CibOcrJobFree(Handle *job); 

This function frees the created CibOcrJobHandle and other resources allocated by CIB ocr. 

If no error occurs, the function result  is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the job that is to be terminated 


CibOcrJobCancel

(From CIB ocr version 2.3.2 

bool exportfunc CibOcrJobCancel(Handle* job); 

This function stops recognition process. 

If no error occurs, the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the job that is to be cancelled 


CibOcrGetVersion

bool CibOcrGetVersion(unsigned long * iVersion); 

This function provides access to the current CIB ocr version number as an integer.  

If no error occurs, the function result is TRUE, otherwise FALSE.  

Type 

Variable 

Description 

Unsigned long* 

iVersion 

Pointer to the stored product version 


CibOcrGetVersionText

bool exportfunc CibOcrGetVersionText(char *text, long *maxlength); 

This function provides access to the current CIB ocr version number as a string.  

If no error occurs function result is TRUE, otherwise FALSE.  

 

Type 

Variable 

Description 

Char* 

Text 

Pointer to character buffer where the version text is stored 

Long* 

maxlength 

Maximum length of version text 


CibOcrGetVersionTextW

Windows 

bool exportfunc CibOcrGetVersionTextW(wchar *text, long *maxlength); 

This function provides access to the current CIB ocr version number as a string.  

If no error occurs function result is TRUE, otherwise FALSE.  

 

Type 

Variable 

Description 

wchar* 

Text 

Pointer to character buffer where the version text is stored 

Long* 

maxlength 

Maximum length of version text 


CibOcrJobGetErrorText

bool exportfunc CibOcrJobGetErrorText(Handle *job, char *text, long *maxlength); 

This function returns the error text that is output after executing a function. 

If no error occurs the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the current job 

Char* 

Text 

Pointer to the string buffer where the error message text is stored 

Long* 

maxlength 

Maximum length of the error message (size of message buffer) 


CibOcrJobGetErrorTextW

Windows 

bool exportfunc CibOcrJobGetErrorTextW(Handle *job, wchar *text, long *maxlength); 

This function returns the error text that is output after executing a function. 

If no error occurs the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the current job 

wchar* 

Text 

Pointer to the string buffer where the error message text is stored 

Long* 

maxlength 

Maximum length of the error message (size of message buffer) 


CibOcrJobGetError

bool exportfunc CibOcrJobGetError(Handle *job,  int *ErrorCode); 

This function gives access to the current error state of CIB ocr after executing various functions.  

If no error occurs, the function result is TRUE, otherwise FALSE. 

Type 

Variable 

Description 

Handle* 

Job 

Handle of the current job 

Int* 

Errorcode 

Outputs the current error code 

 

For all possible error-codes please see the appendix .