MRTD_API Class Reference

Description

Provides access to Grabba Machine-Readable Zone (MRTD) functionality Provides access to Grabba Machine-Readable Travel Document (MRTD) functionality.

This API provides the ability to read images from MRTDs on Grabba devices which support it.

Callbacks to user-provided code may be triggered in response to relevant events, e.g. progress updates on MRTD image reads. Refer to the MRTD_Listener class for the details of these callbacks and how to enable them.

Calls to this class will not succeed until a connection to a Grabba device has been established. Refer to the CoreAPI class for details of how to establish or query this connection.

Thread safety: Everything in this class is fully thread-safe.

Note

This class has no non-static methods or data; consequently, object creation is disabled.

See also

MRZ_API and MRZ_Listener, which provide the ability to read Machine-Readable Zones (MRZs).

Static Public Member Functions
static void	startRead (@NonNull ValidatedMRZ data, int fileID, @NonNull ErrorCode error)
	Start an asynchronous MRTD read. More...
static void	startRead (@NonNull String trackData, int fileID, @NonNull ErrorCode error)
	[DEPRECATED] Start an asynchronous MRTD read More...
static void	stopRead (boolean blocking, @NonNull ErrorCode error)
	Cancel an existing MRTD read. More...
static boolean	supported ()
	Query whether there is currently a connected Grabba device with the ability to fully read an MRTD. More...

Member Function Documentation

startRead() [1/2]

static void startRead ( @NonNull ValidatedMRZ  data, int  fileID, @NonNull ErrorCode  error  )

static

Start an asynchronous MRTD read.

If the supplied error code indicates no prior errors, there is a connected Grabba device with MRTD capabilities, and no MRTD operations are already in progress, then an attempt will be made to read a file from that MRTD.

If an MRTD operation is already active, or a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, or if the connected Grabba device lacks MRTD capabilities, then the error code will be updated accordingly.

If the read is commenced, then the reader hardware will attempt to download a file from the MRTD until either:

• The read is successfully completed, or
• The time limit elapses, or
• stopRead() is called

Read operations run asynchronously; consequently, only some error conditions can be detected and reported by this function. To detect other errors or process the results of successful reads, callbacks are triggered via the MRTD_Listener class.

Parameters

data	Validated MRZ data, from which user information is read
fileID	ID of the file to be read from the MRTD; valid range 0-65535
error	Error code; operation proceeds only if set to NO_ERROR. If an error is detected when starting the operation, then this will be updated with the details.

See also

stopRead() for the converse to this operation

startRead() [2/2]

static void startRead ( @NonNull String  trackData, int  fileID, @NonNull ErrorCode  error  )

static

[DEPRECATED] Start an asynchronous MRTD read

This is a deprecated form of the startRead() function, provided solely for backward compatibility. Behaviour is equivalent to that of startRead() with the supplied track data string converted to a ValidatedMRZ, and the supplied ErrorCode updated if the conversion (and concomitant verification) fails to complete successfully.

Parameters

trackData	Contents of the MRZ track, with CR line ending delimiters
fileID	ID of the file to be read from the MRTD; valid range 0-65535
error	Error code; operation proceeds only if set to NO_ERROR. If an error is detected when starting the operation, then this will be updated with the details.

See also

stopRead() for the converse to this operation

stopRead()

static void stopRead ( boolean  blocking, @NonNull ErrorCode  error  )

static

Cancel an existing MRTD read.

If the supplied error code indicates no prior errors, there is a connected Grabba device with MRTD capabilities, and an MRTD read is currently active, then that operation will be cancelled. The error code will be updated if any errors are detected during the cancellation.

If no MRTD is currently active, or a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, or if the connected Grabba device lacks MRTD capabilities, then the error code will be updated accordingly.

Note

This operation is only likely to be useful when shutting down an application or a component thereof; during normal MRTD operations, each read operation will either succeed or time out, and there is no need to cancel it.

Parameters

blocking	If true (recommended), this call will not return until any active read has been cancelled, and all associated internal resources have been cleaned up. If false, cancellation and cleanup will occur in the background, and this call will return prior to their completion.
error	Error code; operation proceeds only if set to NO_ERROR. If an error is detected when starting the operation, then this will be updated with the details.

See also

startRead() for the converse to this operation

supported()

static boolean supported ( )

static

Query whether there is currently a connected Grabba device with the ability to fully read an MRTD.

This is a non-blocking call; device capabilities are cached internally by the driver.

Returns

True if there is a connected Grabba device and that device supports all MRTD functionality; false otherwise.