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

Introduction

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
  • Delegate types - callback function signatures used by the listener classes
  • Base types - type aliases used throughout the driver interfaces

For new users, starting with the GrabbaDriver::CoreAPI and GrabbaDriver::ConnectionListener classes, particularly the GrabbaDriver::CoreAPI::Open() and GrabbaDriver::CoreAPI::Close() functions, is recommended.

Namespaces

The entire Windows interface to the driver is contained within the GrabbaDriver namespace and its children. This is structured as follows:

Conventions

The following conventions are followed throughout the driver APIs.

Cross-language APIs: These APIs use the Windows Runtime (WinRT) layer, which allows for them to be accessed from applications written in C++/CX, C#, JavaScript or VB.NET. This documentation was generated from the C++/CX version of the interfaces; the mapping from this to other languages follows Microsoft's WinRT conventions. Note that Grabba only fully supports these interfaces for the C++/CX and C# languages; JavaScript is supported only via Grabba's Cordova plugin, and VB.NET interfacing is not supported.

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 GrabbaDriver::CoreAPI::Close()) 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 Windows 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 GrabbaDriver::ErrorCode 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 delegation to a supplied function or via WinRT's event mechanism. No restrictions are placed upon the user functions which are called, other than that delegate functions must be thread-safe and that event handlers must be callable on the application's main (UI) thread. The driver will not be adversely impacted if a callback function takes an extended period of time to complete execution.

Arrays: While the driver internally generates and uses zero-length array objects, the WinRT interface layer may implicitly convert such objects to null references. Consequently, any null array references passed across the API (in either direction) should be treated identically to zero-length arrays.

Core Functionality

Core API functionality is provided by a single class, GrabbaDriver::CoreAPI.

Of particular relevance are the GrabbaDriver::CoreAPI::Open() and GrabbaDriver::CoreAPI::Close() functions, which must be used by every application which interfaces to the driver, as these manage connections to Grabba devices. Consequently, every application using the driver will need to call these functions at appropriate times.

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

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

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

Each listener class also has an associated handler interface; implementing this interface allows for an object to receive the full set of events supported by that listener. They are:

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:

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.