Grabba Driver for iOS
Unified driver for Grabba devices on the iOS operating system
API Overview


The APIs and associated types which form the interface to the driver may be grouped as follows:

  • Core functionality - connection, disconnection, versioning, etc; relevant for all Grabba devices
  • Technology-specific APIs - contain functions specific to a particular technology, e.g. the barcode API allows the user to start or stop barcode scans
  • Listener classes - listen for events from the driver and provide callbacks to user code when they occur
  • Data classes - encapsulate data in formats associated with the driver, and provide for querying and/or manipulation of that data
  • Enumerations - several enumerated types provide lists of known or supported values, e.g. barcode symbologies

For new users, starting with the GrabbaCoreAPI and GrabbaConnectionListener classes, particularly the open and close functions, is recommended.

Naming Conventions

The entire iOS interface to the driver uses a name prefix of Grabba. Interfaces which are specific to a certain technology use more detailed prefixes, as follows:

  • GrabbaBarcode - barcode reader support
  • GrabbaButton - interfacing with the buttons on the sides of Grabba devices
  • GrabbaFingerprint - fingerprint reader support
  • GrabbaFirmware - functionality for uploading firmware to Grabba devices and querying existing firmware
  • GrabbaKeyboard - support for keyboard wedge applications or components thereof
  • GrabbaMagstripe - magnetic stripe reader support
  • GrabbaMRTD - machine-readable travel document (MRTD) high-level functions; combines MRZ and Proxcard functionality
  • GrabbaMRZ - machine-readable zone (MRZ) support
  • GrabbaProxcard - proximity/RFID card support
  • GrabbaSmartcard - contact smart card support

Each of these technologies has its main APIs in a class named <prefix>API (e.g. GrabbaBarcodeAPI for barcode reader functionality), with associated classes and protocols adding additional suffixes (e.g. GrabbaBarcodeData, GrabbaBarcodeListener, GrabbaBarcodeProtocol).


The following conventions are followed throughout the driver APIs.

Non-blocking calls: Almost all API calls are non-blocking. Any operations which do take significant time to complete (e.g. barcode scanning) return their results via callbacks to listener objects, rather than blocking the calling thread for the duration. However, some operations involved with closing or releasing resources (most notably close in GrabbaCoreAPI) do offer a blocking mode, which may be desirable when an application is suspending or shutting down.

Exceptions: Exceptions will not be thrown by these APIs except in response to erroneous input parameter values (e.g. supplying a value of 0 to a parameter with range 1-10). Any method (including constructors and property setters) which can throw an exception will be clearly documented as such. Exceptions may also be thrown by the iOS Runtime in rare scenarios (e.g. running out of memory); these will be passed through to the calling code, and should generally be considered to be fatal.

Error handling: Most error conditions (e.g. disconnection) are handled by way of error code objects (see GrabbaErrorCode for details) or sentinel values. Most methods which take error code parameters will proceed only if that error code object does not indicate any prior errors; consequently, it is possible to chain multiple operations together on the same error code object without having to check it after each call.

Thread-safety: Objects of the data classes are not thread-safe (except where immutable), and must consequently be restricted to a single thread or provided with protection. Aside from this, the remaining APIs - including all static functions and all listener classes - are fully thread-safe.

Callbacks: Callbacks may be triggered in response to driver-generated events. Callback support is managed by the listener classes, either via inheritance or delegation. Callback functions must be thread-safe, but other than that there are no other restrictions on them. The driver will not be adversely impacted if a callback function takes an extended period of time to complete execution.

Core Functionality

Core API functionality is provided by a single class, GrabbaCoreAPI.

Of particular relevance are the open and close functions, which must be used by every application which interfaces to the driver, as these manage connections to Grabba devices.

Technology-Specific API Classes

Several classes provide functions for manipulating a particular hardware component or data source. They are:

Each of these classes contain only static functions, do not require (or even support) object creation, and are fully thread-safe.

Listener Classes and Protocols

Several classes provide for user code to receive callbacks in response to driver-generated events:

Each of these inherit from generic base class GrabbaListener which provides basic functionality common to all listener classes.

Objects of each listener class must be created in order to receive the associated callbacks; each such object is fully thread-safe.

The recommended approach for receiving callbacks is to subclass the relevant listener class, and create an object of that subclass. In cases where subclassing is infeasible (e.g. if callbacks must be received by a class with a different parent), each listener class also supports delegation - to use this, a listener object must be created and then its delegate property set accordingly.

Each listener class has an associated protocol, which is implemented by the listener itself, and must also be implemented by any delegates:

Note that none of the protocols include any optional elements; this ensures that the compiler will check each implementing method has been correctly named. If an application does not require the full range of callbacks provided by a protocol, then the unused callback methods may be provided with empty implementations.

Data Classes

The data classes encapsulate data used by the API and/or listener functions, or provide convenient capabilities for extracting and processing such data. They are:

  • GrabbaBarcodeData - holds the contents and, if known, symbology ID for a scanned barcode
  • GrabbaBER_TLV - encapsulates a Basic Encoding Rule: Type, Length, Value (BER-TLV) data structure as per the X.690 standard
  • GrabbaCommandAPDU - holds a command Application Protocol Data Unit (APDU), for use with contact smart cards and selected proximity card functionality
  • GrabbaErrorCode - holds either a "no error" sentinel or an error code and associated description; used by many API functions to flag error conditions (e.g. loss of connection)
  • GrabbaFingerprintImage - holds a captured fingerprint image plus associated metadata
  • GrabbaFingerprintTemplate - holds a captured fingerprint template plus associated metadata
  • GrabbaFingerprintUserMessage - holds a user message from the fingerprint reader, plus associated parameters (if any)
  • GrabbaMagstripeData - holds the contents of a scanned magnetic stripe
  • GrabbaMRTD_Image - extracts and holds embedded images from machine-readable travel documents (MRTDs)
  • GrabbaMRZ_Data - holds raw contents of a scanned machine-readable zone (MRZ)
  • GrabbaMRZ_Validated - holds fields parsed from a validated machine-readable zone (MRZ)
  • GrabbaResponseAPDU - holds a response Application Protocol Data Unit (APDU), for use with contact smart cards and selected proximity card functionality
  • GrabbaProxcardData - holds the contents and card type ID for a scanned proximity/RFID card

Objects of these classes are not thread-safe (unless immutable), however it is safe to concurrently access distinct objects and/or call static functions from different threads.