Header

Device handling


Detailed Description

Functions for controlling the device.


Modules

 Examples
 Device handling example

Functions

static int pr_getdevicelist (gxHANDLE handle, wchar_t ***devices, int *ndevices)
 Returns a list of the available Passport Reader devices (Unicode version).
static int pr_getdevicelista (gxHANDLE handle, char ***devices, int *ndevices)
 Returns a list of the available Passport Reader devices (ASCII version).
static int pr_usedevice (gxHANDLE handle, const wchar_t *device, int mode)
 Connects a PR device.
static int pr_usedevicea (gxHANDLE handle, const char *device, int mode)
 Conects to a PR device.
static int pr_usedevicen (gxHANDLE handle, int devno, int mode)
 Conects to a PR device.
static int pr_closedevice (gxHANDLE handle)
 Disconnects the connected device.
static int pr_getctrlhandle (gxHANDLE handle, gxHANDLE **hctrl)
 Returns a handle of the capturing device.
static int pr_calibrate (gxHANDLE handle, int windowid)
 Calibrates the used device.
static int pr_iscalibrated (gxHANDLE handle, int windowid)
 Tests the calibrated state of the device.
static int pr_testdocument (gxHANDLE handle, int *state, int windowid)
 Gives back the result of the document (motion) detector module.
static int pr_getlightnumber (gxHANDLE handle, int *lights)
 Gives back the number of usable lights of the device.
static int pr_getlightmask (gxHANDLE handle, int *lightmask, int lightid, int windowid)
 Gives back a light mask for a given light and window.
static int pr_getlightlist (gxHANDLE handle, int *lightbuf, int nlights)
 Gives back a list of usable lights of the device.
static int pr_getwindownumber (gxHANDLE handle, int *windows)
 Gives back the number of object windows of the device.
static int pr_setstatusled (gxHANDLE handle, int ledmask, int color)
 Turns on/off the status leds.
static int pr_blinkstatus (gxHANDLE handle, int coding, int mask, int type, int iteration, unsigned int *data, unsigned int datalength)
 Blinks status outputs (led or buzzer).
static int pr_testpower (gxHANDLE handle, int *state, int *level)
 Gets the power state of the device.
static int pr_testbutton (gxHANDLE handle, int keycode, int *state)
 Gets the device's button state.
static int pr_getbuttonevent (gxHANDLE handle, int *keycode, int *state)
 Gets the device's next button event.
static int pr_suspend (gxHANDLE handle)
 Suspends the Passport Reader system.
static int pr_wakeup (gxHANDLE handle)
 Wakes up the previously suspended Passport Reader system.
static int pr_getudinfo (gxHANDLE handle, int *nblocks, int *sblock)
 Gets information about the available user data space.
static int pr_readudata (gxHANDLE handle, int fblock, int nblocks, void **data)
 Reads the user data from the device.
static int pr_writeudata (gxHANDLE handle, int fblock, int nblocks, const void *data)
 Writes the user data in the used device.
static int pr_getdeviceinfo (gxHANDLE handle, gxVARIANT *devinfo)
 Gets information about the device used.
static int pr_selftest (gxHANDLE handle, int condition, gxVARIANT *result)
 Performs a device self test.
static int pr_readmagstripe (gxHANDLE handle, wchar_t ***tracks, int *ntracks)
 Reads magnetic stripe (Unicode version).
static int pr_readmagstripea (gxHANDLE handle, char ***tracks, int *ntracks)
 Reads magnetic stripe (ASCII version).
static int pr_getlicenses (gxHANDLE handle, int **licenses, int *nlicenses)
 Returns a list of available licenses.
static int pr_getlicensedate (gxHANDLE handle, int license, wchar_t **date)
 Returns the engine acceptance date of a license.
static int pr_getengineinfo (gxHANDLE handle, gxVARIANT *info)
 Returns information about the used engine.


Function Documentation

static int pr_getdevicelist ( gxHANDLE  handle,
wchar_t ***  devices,
int *  ndevices 
) [static]

Returns a list of the available Passport Reader devices (Unicode version).

The application must call the gx_globalfree() function to free the allocated memory for the devices parameter.

Parameters:
handle Handle of the prapi module.
devices List of the device names. Data returned by this function must be freed by the gx_globalfree() function.
ndevices Number of devices.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getdevicelista ( gxHANDLE  handle,
char ***  devices,
int *  ndevices 
) [static]

Returns a list of the available Passport Reader devices (ASCII version).

The application must call the gx_globalfree() function to free the allocated memory for the devices parameter.

Parameters:
handle Handle of the prapi module.
devices List of the device names. Data returned by this function must be freed by the gx_globalfree() function.
ndevices Number of devices.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

Referenced by pr_usedevicen().

static int pr_usedevice ( gxHANDLE  handle,
const wchar_t *  device,
int  mode 
) [static]

Connects a PR device.

To get a list of the available devices call the pr_getdevicelist() function (Unicode version).

Parameters:
handle Handle of the prapi module.
device Name of the device to connect to.
mode Connection mode. The possible values are defined in the PR_USAGEMODE enumeration. Generally the PR_UMODE_FULL_CONTROL is recommended to use.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_usedevicea ( gxHANDLE  handle,
const char *  device,
int  mode 
) [static]

Conects to a PR device.

To get a list of the available devices call the pr_getdevicelist() function (ASCII version).

Parameters:
handle Handle of the prapi module.
device Name of the device to connect to.
mode Connection mode. The possible values are defined in the PR_USAGEMODE enumeration. Generally the PR_UMODE_FULL_CONTROL is recommended to use.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

Referenced by pr_usedevicen().

static int pr_usedevicen ( gxHANDLE  handle,
int  devno,
int  mode 
) [static]

Conects to a PR device.

Parameters:
handle Handle of the prapi module.
devno Ordinal number of the device to connect to.
mode Connection mode. The possible values are defined in the PR_USAGEMODE enumeration. Generally the PR_UMODE_FULL_CONTROL is recommended to use.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_globalfree(), gx_seterror(), pr_getdevicelista(), and pr_usedevicea().

static int pr_closedevice ( gxHANDLE  handle  )  [static]

Disconnects the connected device.

Parameters:
handle Handle of the prapi module.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getctrlhandle ( gxHANDLE  handle,
gxHANDLE **  hctrl 
) [static]

Returns a handle of the capturing device.

This handle can be used for special hardware controls that differs from the usual PR activities such as status led flushing or start button testing. The handle is valid while the the PR device is connected.

Parameters:
handle Handle of the prapi module.
hctrl Handle of the hardware controlling module.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_calibrate ( gxHANDLE  handle,
int  windowid 
) [static]

Calibrates the used device.

Generates data for correcting the geometrical and colour distortions of the capturing system. This process can take up to 20-70 seconds according to the computer's speed. The calibration image is needed to be put on the document window.

Parameters:
handle Handle of the prapi module.
windowid Id of the used window. The possible values are defined in PR_WINDOW_ID enumeration.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_iscalibrated ( gxHANDLE  handle,
int  windowid 
) [static]

Tests the calibrated state of the device.

Parameters:
handle Handle of the prapi module.
windowid Id of the used window. The possible values are defined in PR_WINDOW_ID enumeration.
Returns:
If the device is calibrated the function returns true. Otherwise it returns false and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_testdocument ( gxHANDLE  handle,
int *  state,
int  windowid 
) [static]

Gives back the result of the document (motion) detector module.

The possible result values are defined in the PR_TESTDOC enumeration. Call this function 2-3 times in every second. When the result is PR_TD_IN the document is ready for capturing. The document detection is work only when the freerun_mode property contains the PR_FRMODE_TESTDOCUMENT value.

Parameters:
handle Handle of the prapi module.
state Buffer for the result.
windowid Id of the used window. The possible values are defined in PR_WINDOW_ID enumeration.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getlightnumber ( gxHANDLE  handle,
int *  lights 
) [static]

Gives back the number of usable lights of the device.

Parameters:
handle Handle of the prapi module.
lights Buffer for the number of usable lights.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getlightmask ( gxHANDLE  handle,
int *  lightmask,
int  lightid,
int  windowid 
) [static]

Gives back a light mask for a given light and window.

It is usable to test if the a light is available for the device or one of its object windows. It can return a whole light mask for a given object window if the lightid is null. Light masks are used by the pr_setpagelight() function.

Parameters:
handle Handle of the prapi module.
lightmask The result light mask.
lightid The id of the interesting light. The possible values are defined in the PR_LIGHT enumeration. If this value is null the fuction returns the whole light mask of the given object window.
windowid The id of the interesting object window. The possible values are defined in the PR_WINDOW_ID enumeration. If the value is PR_OW_DEFAULT (null) the fuction returns the light mask of the device.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getlightlist ( gxHANDLE  handle,
int *  lightbuf,
int  nlights 
) [static]

Gives back a list of usable lights of the device.

Parameters:
handle Handle of the prapi module.
lightbuf Preallocated buffer for the list of the usable lights.
nlights Number of lights.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getwindownumber ( gxHANDLE  handle,
int *  windows 
) [static]

Gives back the number of object windows of the device.

Parameters:
handle Handle of the prapi module.
windows Buffer for the number of object windows.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_setstatusled ( gxHANDLE  handle,
int  ledmask,
int  color 
) [static]

Turns on/off the status leds.

Parameters:
handle Handle of the prapi module.
ledmask Mask representing the status leds. Each bit represents a status led on the device.
color The color to display on the specified status leds. The predefined values of the lights are stored in the PR_STATUS_LED_COLOR enumeration. Bit 7 represents the on/off parameter of the light so any value below 80 hex means led off.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_blinkstatus ( gxHANDLE  handle,
int  coding,
int  mask,
int  type,
int  iteration,
unsigned int *  data,
unsigned int  datalength 
) [static]

Blinks status outputs (led or buzzer).

Parameters:
handle Handle of the prapi module.
coding Coding of the data. The possible values are: 0: stop pulses, 1: data[odd]: time duration output high level [ms], data[even]: time duration output low level [ms]
mask Mask representing the status leds and buzzer. Each bit represents a status led or buzzer on the device.
type Led color id or buzzer id. Its predefined values are stored in the PR_STATUS_LED_COLOR and PR_BUZZER enumerations.
iteration Number of repeat, 0 menas forever.
data Data of blinking.
datalength Length of the data, (maximum 16).
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_testpower ( gxHANDLE  handle,
int *  state,
int *  level 
) [static]

Gets the power state of the device.

Parameters:
handle Handle of the prapi module.
state Buffer for the device power state.
level Buffer for the battery power level. In case of devices without battery -1 is returned.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_testbutton ( gxHANDLE  handle,
int  keycode,
int *  state 
) [static]

Gets the device's button state.

Parameters:
handle Handle of the prapi module.
keycode The code of the button/key.
state Buffer for the button/key state.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getbuttonevent ( gxHANDLE  handle,
int *  keycode,
int *  state 
) [static]

Gets the device's next button event.

Parameters:
handle Handle of the prapi module.
keycode Buffer for the button/key code.
state Buffer for the button/key state.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_suspend ( gxHANDLE  handle  )  [static]

Suspends the Passport Reader system.

It may be called for example when the operating system tries to suspend or for power saving reasons you want to suspend the connected device. Depending on the type of the device and the control level set different suspend levels can be reached.

Parameters:
handle Handle of the prapi module.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_wakeup ( gxHANDLE  handle  )  [static]

Wakes up the previously suspended Passport Reader system.

Parameters:
handle Handle of the prapi module.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getudinfo ( gxHANDLE  handle,
int *  nblocks,
int *  sblock 
) [static]

Gets information about the available user data space.

Parameters:
handle Handle of the prapi module.
nblocks Number of blocks.
sblock Size of a block.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_readudata ( gxHANDLE  handle,
int  fblock,
int  nblocks,
void **  data 
) [static]

Reads the user data from the device.

The application must call the gx_globalfree() function for the data to free the allocated memory.

Parameters:
handle Handle of the prapi module.
fblock First block to read.
nblocks Number of blocks to read.
data Bytes read.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_writeudata ( gxHANDLE  handle,
int  fblock,
int  nblocks,
const void *  data 
) [static]

Writes the user data in the used device.

Parameters:
handle Handle of the prapi module.
fblock First block to write.
nblocks Number of blocks to write.
data Bytes to write.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getdeviceinfo ( gxHANDLE  handle,
gxVARIANT devinfo 
) [static]

Gets information about the device used.

Parameters:
handle Handle of the prapi module.
devinfo Variant structure for device information.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_selftest ( gxHANDLE  handle,
int  condition,
gxVARIANT result 
) [static]

Performs a device self test.

Parameters:
handle Handle of the prapi module.
condition Test control condition that declares the type of object which is placed on the document window (0: unknown/nothing, 1: white image, 2: calibration image, 3: document with MRZ line)
result A list of partial test results. The test element ids are defined in PR_SELFTEST_ELEMENTS enumeration, and the result values are defined in PR_SELFTEST_RESULT enumeration.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_readmagstripe ( gxHANDLE  handle,
wchar_t ***  tracks,
int *  ntracks 
) [static]

Reads magnetic stripe (Unicode version).

The application must call the gx_globalfree() function for the tracks to free the allocated memory.

Parameters:
handle Handle of the prapi module.
tracks Buffer for a pointer to the list of tracks.
ntracks Buffer for the number of tracks.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_readmagstripea ( gxHANDLE  handle,
char ***  tracks,
int *  ntracks 
) [static]

Reads magnetic stripe (ASCII version).

The application must call the gx_globalfree() function for the tracks to free the allocated memory.

Parameters:
handle Handle of the prapi module.
tracks Buffer for a pointer to the list of tracks.
ntracks Buffer for the number of tracks.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getlicenses ( gxHANDLE  handle,
int **  licenses,
int *  nlicenses 
) [static]

Returns a list of available licenses.

The application must call the gx_globalfree() function for the licenses to free the allocated memory.

Parameters:
handle Handle of the prapi module.
licenses Buffer for a pointer to the list of licenses.
nlicenses Buffer for the number of licenses.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().

static int pr_getlicensedate ( gxHANDLE  handle,
int  license,
wchar_t **  date 
) [static]

Returns the engine acceptance date of a license.

The application must call the gx_globalfree() function for the date to free the allocated memory.

Parameters:
handle Handle of the prapi module.
license The license to query for the date.
date The date of the license.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call(), and gx_globalfree().

static int pr_getengineinfo ( gxHANDLE  handle,
gxVARIANT info 
) [static]

Returns information about the used engine.

Parameters:
handle Handle of the prapi module.
info Variant structure for engine information.
Returns:
On error false is returned and the error code/string in the GX system is set appropriately. ( see gx_geterror() )

References gx_call().


Generated  for Passport Reader
(c) ADAPTIVE RECOGNITION