Grabba Driver for iOS
Unified driver for Grabba devices on the iOS operating system
Migration Guide

Migration guides are provided for the following transitions:

Others will be added when there are any API changes which deprecate or break compatibility with earlier releases.

v2.0.0-alpha-9 to v2.0.0-alpha-10

Addition of MRZ Parsing and Validation Support

New APIs have been added to support MRZ parsing and validation. These take the form of new methods in GrabbaMRZ_Data, a new class GrabbaMRZ_Validated for MRZ data which has been parsed and validated, and a pair of new events in GrabbaMRZ_Listener which trigger when scanned MRZ data either passes or fails validation against the ICAO 9303 standard.

Existing code which uses the GrabbaMRZ_Listener class (either via overloading or delegation) must be updated to receive the new events. For many applications this may supersede the existing handler for dataEvent. Code using the GrabbaMRZ_Data class should also be updated to use the new per-line access methods and constructor rather than the now-deprecated all-in-one equivalents.

The MRTD APIs have also been updated to match the changed MRZ APIs; for most users, passing the GrabbaMRZ_Validated object received upon a successful MRZ read will suffice to start an MRTD read, replacing the old approach of passing the raw MRZ text. The new approach reduces the range of error conditions which may prevent the MRTD read from occurring successfully, since the MRZ data is guaranteed to already be valid.

Improved Smart Card Power Down Operation

The 2.0.0-alpha-10 release adds an extra parameter to GrabbaDriver::Smartcard::API::PowerDown. A deprecated overload of this function is provided to allow it to be called using the older signature; this sets new parameter waitIfCardBusy to false. Code using this function should be able to build using the deprecated overload without any changes.

To migrate away from the now-deprecated form of the function, calling code should be modified to include the extra parameter - setting it to false retains the existing behaviour; setting it to true will ensure that the power-down operation takes place even if the card is presently busy with another operation.

v2.0.0-alpha-8 to v2.0.0-alpha-9

The 2.0.0-alpha-9 release changes the behaviour of the data property in GrabbaFingerprintImage; it will now hold raw 8bpp grayscale data in all uncompressed formats. Users requiring BMP-format data should use the generateBitmap method to supply it; this method now supports all fingerprint image types except for the V1 compression format.

This release also removes the barcode symbology ID "OCR". Any references to this in calling code should be deleted; it should be noted that this ID was never returned by the driver, so its removal should have no real impact on application behaviour.

v2.0.0-alpha-5 to v2.0.0-alpha-6

New Open and Close APIs

The open and close methods in GrabbaCoreAPI are now parameterless. The old forms, each of which required a GrabbaErrorCode parameter, remain for backward compatibility but have been marked as deprecated.

Changed Signature for Fingerprint Abort Operation

The abort method in GrabbaFingerprintAPI has had a new parameter added to its signature, which allows selection between blocking and non-blocking operation. Any existing code which calls this method should be modified to supply the new parameter; NO will keep the existing behaviour, or YES will utilise the new (blocking) mode.

1.0 series to 2.0 series

The 2.0 series is built atop Grabba's Unified %Driver Architecture, which involves significant changes to the APIs from the 1.0 series or earlier driver releases, but brings greater similarities between the Grabba driver releases on different platforms.

Driver API calls will need to be adjusted to account for the following changes:

  • The 'GRGrabba' prefix is now abbreviated to 'Grabba'
  • API classes which don't store data or provide callbacks now have an 'API' suffix for clarity
  • The GRGrabba class has been replaced by GrabbaCoreAPI
  • The 'Passport' technology name has been renamed to 'MRZ', to avoid confusion vs MRTD
  • Singletons have been replaced by static methods, so it is no longer necessary to access e.g. sharedGrabba
  • Event callbacks are now managed by thread-safe listener classes (e.g. GrabbaBarcodeListener):
    • The recommended approach is to subclass the desired listener class, then make an object of that subclass
    • Registration for callbacks is automatic when the listener-class/listener-subclass object is initialised
    • Delegation is not required, although it is supported as an alternative to listener subclassing
  • API and listener classes are now all fully thread-safe (data classes are not though)
  • Some features (e.g. preferences) are not supported yet, so any code which uses them may need to be disabled

There have also been changes to methods and identifiers in various classes, so it will be necessary to refer to the documentation for each class to see how to interact with it.