Description

Provides access to Grabba RFID/proximity card (proxcard) functionality, such as triggering proxcard scans.

Callbacks to user-provided code may be triggered in response to relevant events, e.g. successful scan of a proxcard. Refer to the GrabbaProxcardListener 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 GrabbaProxcardAPI:

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

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

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

(BOOL)	+ supported
	Query whether there is currently a connected Grabba device with proxcard 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 proxcard scan.

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

If a proxcard 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 proxcard capabilities, then the error code will be updated accordingly.

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

A proxcard 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 GrabbaProxcardListener 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 may give Data, Error or Timeout events depending on the outcome of the scan.

For reader modules which support concurrent scanning of multiple tags, there may also be additional Data events - e.g. if four tags are all within the scanning field, and all are read within the timeout period, then four Data events and one Stop event will be triggered.

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 proxcard scan.

If the supplied error code indicates no prior errors, there is a connected Grabba device with proxcard capabilities, and a proxcard 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 proxcard 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 proxcard 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 proxcard 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 proxcard 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 proxcard functionality; NO otherwise.