 |
Grabba Driver for iOS
Unified driver for Grabba devices on the iOS operating system
|
|
|
Grabba Driver for iOS
Unified driver for Grabba devices on the iOS 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 GrabbaCoreAPI and GrabbaConnectionListener classes, particularly the open and close functions, is recommended.
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:
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 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.
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 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.
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