GrabbaMRTD_API Class Reference

Description

Provides access to Grabba MRTD reader functionality, such as triggering MRTD scans.

Callbacks to user-provided code may be triggered in response to relevant events, e.g. successful scan of a MRTD. Refer to the GrabbaMRTD_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 GrabbaCoreAPI class for details of how to establish or query this connection.

Note

This is a static class; object construction is unnecessary and consequently disabled. Subclassing is strongly discouraged.

Thread safety: This class is fully thread-safe.

Inheritance diagram for GrabbaMRTD_API:

Instance Methods
(instancetype _Nullable)	- init
	Not callable (NS_UNAVAILABLE) since this is a static class. More...

Class Methods
(void)	+ startReadWithTrackData:fileID:error:
	[DEPRECATED] Start an asynchronous MRTD read More...
(void)	+ startReadWithValidatedData:fileID:error:
	Start an asynchronous MRTD read given a validated MRZ. More...
(void)	+ stopReadWithBlocking:error:
	Cancel an existing MRTD read. More...
(BOOL)	+ supported
	Query whether there is currently a connected Grabba device with MRTD functionality. More...

Method Documentation

init()

- (instancetype _Nullable) init

Not callable (NS_UNAVAILABLE) since this is a static class.

startReadWithTrackData:fileID:error:()

+ (void) startReadWithTrackData:		(NSString *_Nonnull)	trackData
fileID:		(uint16_t)	fileID
error:		(GrabbaErrorCode *_Nonnull)	error

[DEPRECATED] Start an asynchronous MRTD read

This is a deprecated form of startRead which is provided solely for backward compatibility purposes.

Behaviour is identical to that of startRead with the supplied track data converted to a GrabbaMRZ_Validated object, and the supplied GrabbaErrorCode updated if the conversion (and concomitant verification) fails to complete successfully.

Parameters

trackData	Contents of the MRZ track, with lines delimited by CR characters
fileID	ID of the file to be read from the MRTD
error	Error code; operation proceeds only if set to GrabbaNoError. If an error is detected when starting the operation, then this will be updated with the details.

startReadWithValidatedData:fileID:error:()

+ (void) startReadWithValidatedData:		(GrabbaMRZ_Validated *_Nonnull)	data
fileID:		(uint16_t)	fileID
error:		(GrabbaErrorCode *_Nonnull)	error

Start an asynchronous MRTD read given a validated MRZ.

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
• stopScan 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 GrabbaMRTD_Listener class.

Parameters

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

stopReadWithBlocking:error:()

+ (void) stopReadWithBlocking:		(BOOL)	blocking
error:		(GrabbaErrorCode *_Nonnull)	error

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 GrabbaNoError. If an error is detected when starting the operation, then this will be updated with the details.

supported()

+ (BOOL) supported

Query whether there is currently a connected Grabba device with MRTD functionality.

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

Returns

YES if there is a connected Grabba device and that device supports MRTD functionality; NO otherwise.