GrabbaBarcodeListener Class Reference

Description

Base barcode-event listener class, for receiving events from the Grabba device's barcode reader.

The following events are supported by this class:

• Cancel - barcode scan was cancelled by a call to stopScan
• Data - barcode data was scanned successfully
• Error - barcode scan encountered an error (e.g. loss of connection)
• Start - barcode scan commenced
• Stop - barcode scan stopped, regardless of the outcome (success, cancellation, timeout or error)
• Timeout - barcode scan timed out

Each event may invoke callbacks in two ways:

• Subclassing - the relevant event methods (e.g. dataEvent) are called directly
  • This approach is recommended wherever feasible, due to its simplicity.
  • To use it, create an object of a suitable subclass, which overrides the desired event method(s).
• Delegation - event methods trigger method calls for a delegate object
  • This approach is only recommended when the callback class must inherit from a different base class
  • To use it, create an object of this class, create an object of a class which implements GrabbaBarcodeProtocol, then set the delegate property of the former to point to the latter.

Note

Delegation will be disabled for an event if that event's method is subclassed, unless the subclass calls the superclass' equivalent method from within its override thereof.

By default, each listener object will register itself for callbacks upon construction, and deregister itself at destruction; the enable and disable methods may be used if an object requires manual control over when its callbacks are triggered.

The default behaviour for each event, if not overridden, on an enabled listener object is as follows:

• If delegate has not been set, or has been set to null, then take no action
• If delegate has been set to a non-null pointer, then delegate to the pointed-to object

Overrides need not call the superclass' equivalent method unless it is necessary to preserve the delegation (i.e. to support both subclassing and delegation from a single object).

Thread safety: This interface is intended to be thread-safe; any classes deriving or delegating from it should ensure that the relevant methods are callable from any thread.

See also

GrabbaBarcodeAPI for related API functions

Inheritance diagram for GrabbaBarcodeListener:

Instance Methods
(void)	- cancelEvent
	Callback which is invoked when barcode scanning operations are cancelled. More...
(void)	- dataEvent:
	Callback which is invoked when a barcode is successfully scanned. More...
(void)	- disable
	Disable listening for events from this object, if not already disabled. More...
(void)	- enable
	Enable listening for events from this object, if not already enabled. More...
(void)	- errorEvent:
	Callback which is invoked when barcode scanning operations fail. More...
(instancetype _Nullable)	- init
	Default initialiser - builds an object then enables event callbacks to it. More...
(instancetype _Nullable)	- initWithEnabled:
	Initialiser which allows control over whether event callbacks should be enabled. More...
(void)	- startEvent
	Callback which is invoked when the barcode reader commences a scan. More...
(void)	- stopEvent
	Callback which is invoked when barcode scanning operations are stopped, regardless of the reason. More...
(void)	- timeoutEvent
	Callback which is invoked when barcode scanning operations time out. More...

Properties
ProtocolType _Nullable	delegate
	Delegate for receiving events from non-subclassed listener objects; defaults to nil. More...

Method Documentation

cancelEvent()

- (void) cancelEvent

Callback which is invoked when barcode scanning operations are cancelled.

Operations may be cancelled by calling stopScan . Note that this callback will only trigger in the event that a running operation was cancelled; if e.g. stopScan is called and there was no scan active at the time, then no callback will be triggered.

Override this method to receive callbacks when the object is enabled (via init or enable) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

dataEvent:()

- (void) dataEvent:

(GrabbaBarcodeData *_Nonnull)

data

Callback which is invoked when a barcode is successfully scanned.

Operations may be commenced by calling startScan. If scanning succeeds, the barcode scanner will be turned off (beyond which point calling stopScan will cease to have any effect), then this callback will be invoked.

Override this method to receive callbacks when the object is enabled (via init or enable) and the event is triggered.

Parameters

data	Contains the data which was read, along with the ID of the symbology which was detected

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

disable()

- (void) disable

Disable listening for events from this object, if not already disabled.

This will remove the listener object from the relevant event handler, if it had previously been added. Callbacks will no longer be triggered on this object, although they may be re-enabled by calling enable.

Note

This method should not be overridden.

enable()

- (void) enable

Enable listening for events from this object, if not already enabled.

This will add the listener object to the relevant event handler, if it has not already been added. Events will then trigger callbacks on this object until it is destroyed or disable is called.

Note

This method should not be overridden.

errorEvent:()

- (void) errorEvent:

(GrabbaErrorCode *_Nonnull)

error

Callback which is invoked when barcode scanning operations fail.

Scanning may be commenced by calling startScan. If scanning fails, the barcode scanner will be turned off (beyond which point calling stopScan will cease to have any effect), then this callback will be invoked.

Parameters

error

Error code indicating the reasons for the failure

Override this method to receive callbacks when the object is enabled (via init or enable) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

init()

- (instancetype _Nullable) init

Default initialiser - builds an object then enables event callbacks to it.

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

initWithEnabled:()

- (instancetype _Nullable) initWithEnabled:

(BOOL)

startEnabled

Initialiser which allows control over whether event callbacks should be enabled.

Parameters

startEnabled

If YES, the newly-allocated listener object is added to the relevant event handler, enabling receipt of event callbacks. If NO, no callbacks are received until enable is called.

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

startEvent()

- (void) startEvent

Callback which is invoked when the barcode reader commences a scan.

This event may be invoked by calling startScan when a suitable Grabba device is connected.

Override this method to receive callbacks when the object is enabled (via init or enable) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

stopEvent()

- (void) stopEvent

Callback which is invoked when barcode scanning operations are stopped, regardless of the reason.

Scanning may be commenced by calling startScan. If scanning succeeds, fails, times out or is cancelled, then the barcode reader will be turned off (beyond which point calling stopScan will cease to have any effect), then this callback will be invoked.

In addition to this callback, one other callback will be triggered, depending on the outcome of the operation:

• DataEvent will be triggered if the operation successfully completed
• TimeoutEvent will be triggered if the operation timed out before it could be completed (e.g. no barcode in range)
• CancelEvent will be triggered if the operation was cancelled by a call to stopScan
• ErrorEvent will be triggered if the operation failed for reasons other than timeout or cancellation

No guarantees are given as to the order in which the two callbacks are triggered, or whether they will be triggered on the same thread.

Override this method to receive callbacks when the object is enabled (via init or enable) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

timeoutEvent()

- (void) timeoutEvent

Callback which is invoked when barcode scanning operations time out.

Scanning may be commenced by calling startScan. If scanning times out, the barcode scanner will be turned off (beyond which point calling stopScan will cease to have any effect), then this callback will be invoked.

Override this method to receive callbacks when the object is enabled (via init or enable) and the event is triggered.

Note

Overrides of this method are required to be thread-safe; no guarantees are made about which thread(s) they will be called from.

Property Documentation

delegate

- (ProtocolType _Nullable) delegate

readwritenonatomicweakinherited

Delegate for receiving events from non-subclassed listener objects; defaults to nil.

Delegation may be used as an alternative to subclassing for receiving event callbacks. Any Grabba-defined listener class object (as opposed to a subclass thereof) will pass events on to a delegate, if one has been set and it has implemented the relevant protocol method.

If the delegate is to be written to whilst a callback to it is in progress, the write operation will block until that operation has completed. This ensures thread-safety.

Note

Delegates must provide thread-safe implementations of all protocol methods; no guarantees are made about which thread(s) they will be called from.