 |
Grabba Driver for Android
Unified driver for Grabba devices on the Android operating system
|
|
|
Grabba Driver for Android
Unified driver for Grabba devices on the Android operating system
|
|
The APIs and associated types which form the interface to the driver may be grouped as follows:
For new users, starting with the CoreAPI and ConnectionListener classes, particularly the CoreAPI.open and CoreAPI.close methods, is recommended.
The entire Android interface to the driver is contained within several packages each using the com.grabba.driver prefix:
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 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) which can throw an exception will be clearly documented as such. Exceptions may also be thrown by the Android 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 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 subclassing or delegation. No restrictions are placed upon the user functions which are called, other than that they must be thread-safe. The driver will not be adversely impacted if a callback function takes an extended period of time to complete execution.
Core API functionality is provided by a single class, CoreAPI.
Of particular relevance are the CoreAPI.open and CoreAPI.close functions, which must be used by every application which interfaces to the driver, as these manage connections to Grabba devices.
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.
Several classes provide for user code to receive callbacks in response to driver-generated events:
Each of these inherit from generic base class Listener, 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 setDelegate method called.
Each listener class has an associated interface, which is implemented by the listener itself, and must also be implemented by any delegates:
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.
1.8.13