MRZ_Listener Class Reference

Description

Base class for receiving events related to reading of Machine-Readable Zones (MRZs)

At present, three events are supported by this class:

• dataEvent - machine-readable zone data was read, regardless of the validation outcome
• validatedDataEvent - machine-readable zone data was read and it passed validation
• validationFailedEvent - machine-readable zone data was read, but it failed validation

Each event may invoke callbacks in two ways:

• Subclassing - the relevant event methods (e.g. dataEvent) are called directly
  • This approach is recommended wherever feasible, due to its simplicity
  • To use it, create an object of a suitable subclass, which overrides the desired event method(s)
• Delegation - event methods trigger method calls for a delegate object
  • This approach is only recommended when the callback handler must inherit from a different base class
  • To use it, create an object of this class, create an object of a class which implements MRZ_Interface, then call setDelegate() to provide the necessary linkage.

Note

Delegation will be disabled for an event if that event's method is subclassed, unless the subclass calls the superclass' equivalent method from within its override thereof.

By default, each listener object will receive event notifications from the driver for its entire lifetime; the enable() and disable() methods may be used if control is required over whether notifications are received.

The default behaviour for each event, if not overridden, on an enabled listener object is as follows:

• If setDelegate() has not been called, then take no action
• If the last call to setDelegate() accepted a null reference, then take no action
• If the last call to setDelegate() accepted a non-null object reference, then delegate to that object

Overrides need not call the superclass' equivalent method unless it is necessary to preserve the delegation (i.e. to support both subclassing and delegation from a single object).

Thread safety: This class is intended to be thread-safe; any classes deriving from it should ensure that the relevant methods are callable from any thread.

See also

MRZ_API for related API functions

Inheritance diagram for MRZ_Listener:

Public Member Functions
	MRZ_Listener ()
	Default constructor - builds a listener object then enables receipt of events from the driver.
	MRZ_Listener (boolean startEnabled)
	Constructor - builds a listener object then optionally enables receipt of events from the driver. More...
void	dataEvent (@NonNull MRZ_Data data)
	Callback which is invoked when a Machine-Readable Zone (MRZ) is read, regardless of validation outcome. More...
final void	disable ()
	Disable receipt of events from the driver by this object. More...
final void	enable ()
	Enable receipt of events from the driver by this object. More...
final void	setDelegate (Delegate newDelegate)
	Set the delegate which will receive event callbacks if default listener behaviour is not overridden. More...
void	validatedDataEvent (@NonNull ValidatedMRZ data)
	Callback which is invoked when a Machine-Readable Zone (MRZ) is read and successfully validated. More...
void	validationFailedEvent (@NonNull MRZ_Data data, @NonNull String reason)
	Callback which is invoked when a machine-readable zone (MRZ) is read, but fails validation. More...

Constructor & Destructor Documentation

MRZ_Listener()

MRZ_Listener

(

boolean

startEnabled

)

Constructor - builds a listener object then optionally enables receipt of events from the driver.

Parameters

startEnabled

If set, the listener object is enabled immediately (equivalent of default constructor), otherwise it is disabled until the first call to enable()

Member Function Documentation

dataEvent()

void dataEvent

(

@NonNull MRZ_Data

data

)

Callback which is invoked when a Machine-Readable Zone (MRZ) is read, regardless of validation outcome.

This event is triggered when the optical character recognition (OCR) module encounters an MRZ (swiped through the Grabba device's reading slot) and is able to read data from it, providing the listener object is enabled.

This event will be triggered regardless of data validity - i.e. even if some characters are not read successfully, or if the data which was read does not conform to any of the formats defined in ICAO 9303.

Most applications can safely ignore this event unless they need the raw MRZ data even from validated MRZs - consider using validatedDataEvent() and/or validationFailedEvent() instead. Each trigger of this event will be coupled with exactly one of those two (with the choice depending on the validation outcome); no guarantees are made as to the order in which the two events are triggered.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

Parameters

data	Passport, visa or identity card data which was read; see MRZ_Data for details

Implements MRZ_Interface.

disable()

final void disable ( )

inherited

Disable receipt of events from the driver by this object.

This has no effect if the object was already disabled.

enable()

final void enable ( )

inherited

Enable receipt of events from the driver by this object.

This has no effect if the object was already enabled.

setDelegate()

final void setDelegate ( Delegate  newDelegate )

inherited

Set the delegate which will receive event callbacks if default listener behaviour is not overridden.

Delegation may alternatively be disabled by providing a null reference here.

Parameters

newDelegate

If null, disables delegation; if non-null, enables delegation and sets the delegate to the supplied object.

validatedDataEvent()

void validatedDataEvent

(

@NonNull ValidatedMRZ

data

)

Callback which is invoked when a Machine-Readable Zone (MRZ) is read and successfully validated.

This event is triggered when the optical character recognition (OCR) module encounters an MRZ (swiped through the Grabba device's reading slot), it is able to successfully read data in one of the formats defined in ICAO 9303, and the read data passes all validation checks for that format.

This event is mutually exclusive with validationFailedEvent(); applications which handle this event should typically ignore dataEvent() and pick up validationFailedEvent() if they need to process scan failures. If dataEvent() is handled, however, it should be noted that no guarantees are made as to the order in which this event and that event will be triggered after a scan.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

Parameters

data	Passport, visa or identity card data which was read; see ValidatedMRZ for details

Implements MRZ_Interface.

validationFailedEvent()

void validationFailedEvent	(	@NonNull MRZ_Data	data,
		@NonNull String	reason
	)

Callback which is invoked when a machine-readable zone (MRZ) is read, but fails validation.

This event is triggered when the optical character recognition (OCR) module encounters an MRZ (swiped through the Grabba device's reading slot), but the data which was read does not pass validation checks. This could be due to any of the following causes:

• The scan was incomplete (e.g. one end of the MRZ did not pass the read head)
• One or more characters could not be successfully identified
• The MRZ was in a format not consistent with those defined by ICAO 9303
• The MRZ was incorrectly written (e.g. check digit incorrectly calculated)

This event is mutually exclusive with validatedDataEvent(); applications which handle this event should typically ignore dataEvent() and pick up validatedDataEvent() instead. If dataEvent() is handled, however, it should be noted that no guarantees are made as to the order in which this event and that event will be triggered after a scan.

Override this method to receive callbacks when the object is enabled (at construction or via enable()) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

Parameters

data	Passport, visa or identity card data which was read, but failed to pass validation
reason	Brief description of the validation failure reason

Implements MRZ_Interface.