Description

Provides access to core Grabba driver and hardware functionality, such as opening and closing communications.

This API provides access to device-wide functionality, and to selected features common to all Grabba hardware (e.g. battery level).

Callbacks to user-provided code may be triggered when the driver connects to or disconnects from the Grabba device. Refer to the GrabbaConnectionListener class for the details of these callbacks and how to enable them.

Most calls to this and other driver APIs will not succeed until a connection to a Grabba device has been established. This connection may be triggered by calling open, and then either waiting for a connection event or polling the connected method until it returns YES.

If open has been called, close or deferredClose must be called at a later time to terminate any active connections and free resources. Typically this will take the form of a call to close from the applicationDidEnterBackground method in the app delegate, however the call may occur earlier if an application no longer needs access to the Grabba Driver.

Note: This is a static class; object construction is unnecessary and consequently disabled. Subclassing is strongly discouraged.

Thread safety: This class is fully thread-safe.

Inheritance diagram for GrabbaCoreAPI:

Instance Methods
(instancetype _Nullable)	- init
	Not callable (`NS_UNAVAILABLE`) since this is a static class. More...

Class Methods
(NSUInteger)	+ batteryLevel
	Query the battery level of a connected Grabba device. More...

(void)	+ close
	Close the communication channel to the device if it has previously been opened. More...

(BOOL)	+ closePending
	Query whether a deferredClose operation is currently pending. More...

(BOOL)	+ connected
	Query whether the driver is currently connected to a Grabba device. More...

(void)	+ deferredCloseAfterInterval:
	Close the communication channel to the device if it has previously been opened, after a given interval has elapsed. More...

(NSString *_Nonnull)	+ deviceModel
	Query the model number of a connected Grabba device. More...

(NSString *_Nonnull)	+ driverVersion
	Query the version number of the Grabba driver. More...

(NSString *_Nonnull)	+ hardwareVersion
	Query the hardware version number of a connected Grabba device. More...

(BOOL)	+ open
	Attempt to open the communications channel to the device. More...

(BOOL)	+ opened
	Query whether the communication channel is currently opened. More...

(NSString *_Nonnull)	+ serialNumber
	Query the serial number of a connected Grabba device. More...

Method Documentation

◆ batteryLevel()

+ (NSUInteger) batteryLevel

Query the battery level of a connected Grabba device.

This is a non-blocking call; the driver polls the battery level at regular intervals and caches the value internally.

Returns: Battery percentage of the connected device if there is one, otherwise zero.

◆ close()

+ (void) close

Close the communication channel to the device if it has previously been opened.

If the communication channel is open (even if not connected), then this call will close it, preventing further communication with the hardware. If the communication channel is already closed, then this call has no effect.

This is a blocking call, and consequently should not be triggered from any thread or other context which is latency-sensitive (e.g. UI threads). Note, however, that it is probably acceptable (and may even be desirable) to call this from a UI thread immediately prior to application suspension or shutdown.

Note: This call will trigger a disconnection event if the communication channel was previously connected. It will block until all driver internals have completed processing of this disconnection event, but is not guaranteed to block for sufficient time to allow application code to complete its own handling of the disconnect event. If application code is relying on completion of a close operation prior to suspension or shutdown, it must ensure that any pertinent application code finishes executing before the suspension or shutdown takes place.

See also: For cases where the app may attempt to re-open comms in the very near future, use deferredClose instead.

◆ closePending()

+ (BOOL) closePending

Query whether a deferredClose operation is currently pending.

This is a non-blocking call.

Returns: YES if deferredClose has been called, it has not been cancelled by a subsequent call to open, and its interval has not yet expired; NO otherwise.

◆ connected()

+ (BOOL) connected

Query whether the driver is currently connected to a Grabba device.

This is a non-blocking call; it will return the current connection state immediately, without waiting for any in-progress open or close operations to complete.

Returns: YES if the communication channel is open and a Grabba device is connected; NO otherwise.

◆ deferredCloseAfterInterval:()

+ (void) deferredCloseAfterInterval: (unsigned) interval

Close the communication channel to the device if it has previously been opened, after a given interval has elapsed.

This call is asynchronous, and will trigger processing as follows:

If open is called prior to the given interval expiring, then deferredClose has no effect (i.e. open cancels deferredClose, channel stays open)
If close is called prior to the given interval expiring, then deferredClose has no effect (i.e. close closes the channel as usual)
If the interval expires without any calls to open or Close() in the meantime, then deferredClose will call close at that time.

Parameters

interval Duration in milliseconds which this call will wait before calling close, subject to there being no open or close calls in the meantime. The permitted range is 0-5000ms (i.e. 0-5s); any values outside that range will be clamped. Values in the 1000-2000ms (i.e. 1-2s) range are likely to be reasonable for most applications.

◆ deviceModel()

+ (NSString* _Nonnull) deviceModel

Query the model number of a connected Grabba device.

This is a non-blocking call; the driver caches the model number internally.

Returns: Model number string (e.g. "S-9472-WSQ+") of the connected device if there is one, otherwise an empty string.

◆ driverVersion()

+ (NSString* _Nonnull) driverVersion

Query the version number of the Grabba driver.

This is a non-blocking call.

Returns: Driver version number string, e.g. "2.0.0-alpha-1". See the versioning page for details of the numbering scheme.

◆ hardwareVersion()

+ (NSString* _Nonnull) hardwareVersion

Query the hardware version number of a connected Grabba device.

This is a non-blocking call; the driver caches the hardware version number internally.

Returns: Hardware version number string (e.g. "4.6") of the connected device if there is one, otherwise an empty string.

◆ init()

- (instancetype _Nullable) init

Not callable (NS_UNAVAILABLE) since this is a static class.

◆ open()

+ (BOOL) open

Attempt to open the communications channel to the device.

If the communications channel is presently closed (or has yet to be opened for the first time), and the supplied error code indicates no prior errors, then this call will attempt to open the channel.

If the communications channel is already opened, or if the supplied error code indicates a prior error, then this call has no effect other than cancelling any pending deferredClose calls.

This is a non-blocking call; consequently, it can't report on the success or failure of a connection attempt. If a connection attempt succeeds, any active GrabbaConnectionListener objects will receive events, and can trigger callbacks into application code; consequently, constructing an object of a GrabbaConnectionListener subclass is recommended prior to the first call to open.

If a connection attempt fails, or if an existing connection is lost, then the driver will automatically attempt to reconnect; there should be no need to call open again. If it is necessary to guarantee disconnection, then close should be called; open can then be called again if a subsequent reconnection is needed.

Note: If open has been called, close or deferredClose must be called before the application is suspended or terminated, even if the connection has not been established. Typically this will take the form of a call to close from the applicationDidEnterBackground method in the app delegate, however the call may occur earlier if an application no longer needs access to the Grabba Driver.

Returns: YES if this call opens the communications channel (i.e. if it was previously closed); NO if it was already opened, or if this call cancelled a deferredClose operation which was pending.

◆ opened()

+ (BOOL) opened

Query whether the communication channel is currently opened.