Description

Provides access to Grabba barcode reader functionality, such as triggering barcode scans.

Callbacks to user-provided code may be triggered in response to relevant events, e.g. successful scan of a barcode. Refer to the GrabbaBarcodeListener class for the details of these callbacks and how to enable them.

Calls to this class will not succeed until a connection to a Grabba device has been established. Refer to the GrabbaCoreAPI class for details of how to establish or query this connection.

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 GrabbaBarcodeAPI:

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

Class Methods
(void)	+ startScanWithError:
	Start an asynchronous barcode scan. More...

(void)	+ stopScanWithBlocking:error:
	Cancel an existing barcode scan. More...

(BOOL)	+ supported
	Query whether there is currently a connected Grabba device with barcode functionality. More...

Method Documentation

◆ init()

- (instancetype _Nullable) init

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

◆ startScanWithError:()

+ (void) startScanWithError: (GrabbaErrorCode *_Nonnull) error

Start an asynchronous barcode scan.

If the supplied error code indicates no prior errors, there is a connected Grabba device with barcode capabilities, and no barcode scan is currently active, then a barcode scan will be commenced.

If a barcode scan is already active, or a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, or if the connected Grabba device lacks barcode capabilities, then the error code will be updated accordingly.

If the scan is commenced, then the GrabbaNoError code is returned, and the barcode reader will attempt to scan a barcode. There are four possible outcomes:

A barcode is successfully scanned, or
The scan operation fails, or
The scan operation is cancelled by stopScan, or
The time limit elapses

Note that any error conditions detected during the scan will not be reported by this function (as it is non-blocking). Instead, feedback is given by way of callbacks to active GrabbaBarcodeListener objects. Each such object will receive a Start event when the scan process commences, a Stop event when it completes (regardless of the reason), and either a Data, Error, Cancel or Timeout event depending on the outcome of the scan.

Parameters

error Error code; operation proceeds only if set to GrabbaNoError. If an error is detected when starting the operation, then this will be updated with the details.

◆ stopScanWithBlocking:error:()

+ (void) stopScanWithBlocking:	(BOOL)	blocking
error:	(GrabbaErrorCode *_Nonnull)	error

Cancel an existing barcode scan.

If the supplied error code indicates no prior errors, there is a connected Grabba device with barcode capabilities, and a barcode scan is currently active, then that scan will be cancelled. The error code will be updated if any errors are detected during the cancellation.

If no barcode scan is currently active, or a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, or if the connected Grabba device lacks barcode capabilities, then the error code will be updated accordingly.

Note: This operation is only likely to be useful when shutting down an application or a component thereof, or if letting a user "press to scan"; during normal barcode operations, each scan operation will either complete or time out, and there is no need to explicitly cancel it.

Parameters

blocking	If true (recommended), this call will not return until any active scan has been cancelled, and all associated internal resources have been cleaned up. If false, cancellation and cleanup will occur in the background, and this call will return prior to their completion.
error	Error code; operation proceeds only if set to GrabbaNoError. If an error is detected during the operation, then this will be updated with the details.

◆ supported()

+ (BOOL) supported

Query whether there is currently a connected Grabba device with barcode functionality.

This is a non-blocking call; device capabilities are cached internally by the driver.

Returns: YES if there is a connected Grabba device and that device supports barcode functionality; NO otherwise.