Grabba Driver for Windows
Unified driver for Grabba devices on the Windows 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 GrabbaDriver::MRZ::Data, a new class GrabbaDriver::MRZ::Validated for MRZ data which has been parsed and validated, and a pair of new events in GrabbaDriver::MRZ::Listener which are triggered when scanned MRZ data either passes or fails validation against the ICAO 9303 standard.

Existing code which uses the GrabbaDriver::MRZ::Listener class (either via a handler or events) must be updated to receive the new events. For many applications this may supersede the existing handler for DataEvent. Code using the GrabbaDriver::MRZ::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 GrabbaDriver::MRZ::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 GrabbaDriver::Fingerprint::Image; 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 renames property Data to CommandData in GrabbaDriver::CommandAPDU, with the old name marked as deprecated. All references to the old name in calling code should be updated to use the new name; the behaviour is identical.

Finally, this release removes barcode symbology OCR; any references to it in calling code should be removed. For most applications there should not be any such references, so no change should be required to support this.

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

Support for UWP and Windows 10

The 2.0.0-alpha-6 release adds a Visual Studio extension for use with Windows 10, the Universal Windows Platform (UWP), and Visual Studio 2015. With this release, to build an application targeting Windows 10 it is no longer necessary to set up a Visual Studio solution containing multiple projects; instead, a single project may be used for phones, tablets, laptops and desktops. Refer to the newly-updated getting started guide (included with the SDK) for details on how to do this.

If you wish to continue to target Windows 8.1 and/or Windows Phone 8.1 in addition to UWP, it is possible to do so

  • simply add a UWP project to your existing solution, and add a reference to your shared source project from it. Note, however, that Windows 8.1 and Windows Phone 8.1 support is now considered deprecated in the Grabba Driver, and will be removed from a subsequent release, so such a solution should only be considered a stop-gap en route to direct targeting of Windows 10 (and only Windows 10).

If you are still using Visual Studio 2013, note that it will be necessary to upgrade to Visual Studio 2015 in order to use the Grabba Driver with UWP and Windows 10. Grabba's support for Visual Studio 2013 is now deprecated, and will be removed when we drop Windows 8.1 and Windows Phone 8.1 support.

Renamed Classes and Methods

The following classes have been renamed for clarity and consistency:

In addition, the GrabbaDriver::Proxcard::Data class has had the following renames:

  • initData parameter renamed to initContents
  • DataString methods renamed to ContentsString

The old names are still usable, but deprecated; calling code should be able to be updated by a simple search and replace for each of the affected names. Note, however, that code which uses MRTD::Listener and/or MRTD::Handler will need to use the new names immediately, since the parameter types for the Data event have changed.

New Open and Close APIs

In addition to the rename, GrabbaDriver::CoreAPI now holds parameterless forms of Open() and Close(). These replace the earlier forms which took a GrabbaDriver::ErrorCode parameter.

Changed Signature for Fingerprint Abort Operation

The GrabbaDriver::Fingerprint::API::Abort() method's signature has been modified to accept a new parameter, which allows selection between blocking and non-blocking operation. Any existing code which calls this method should be modified to supply the new parameter; false will keep the existing behaviour, or true will utilise the new (blocking) mode for this method.

The existing (parameterless) form of this method has been retained, but it is now deprecated, so calling code should be modified to supply the new parameter.

v2.0.0-alpha-4 to v2.0.0-alpha-5

The per-event delegate properties used in the listener classes for v2.0.0-alpha-4 and earlier have been deprecated in v2.0.0-alpha-5. This has been replaced by an improved mechanism which provides a delegate for all events from a given listener at the same time.

To use this, classes which previously received callbacks from Grabba listeners using the old delegate properties mechanism should now inherit from the relevant interface class - e.g. GrabbaDriver::Barcode::Handler. Instead of setting one delegate property per event, only a single property per listener need be set, e.g. GrabbaDriver::Barcode::Listener::HandlerObject in the barcode case. This property should be set to the object which will accept the callbacks.