ProxcardListener Class Reference

Description

Base class for receiving events related to scanning proximity/RFID cards.

The following events are supported by this class:

• dataEvent - card was scanned successfully
• errorEvent - scan encountered an error (e.g. loss of connection)
• startEvent - scan commenced
• stopEvent - scan stopped, regardless of the outcome (success, cancellation, timeout or error)
• timeoutEvent - 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 handler must inherit from a different base class
  • To use it, create an object of this class, create an object of a class which implements ProxcardInterface, then call setDelegate() to provide the necessary linkage.

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 receive event notifications from the driver for its entire lifetime; the enable() and disable() methods may be used if control is required over whether notifications are received.

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

• If setDelegate() has not been called, then take no action
• If the last call to setDelegate() accepted a null reference, then take no action
• If the last call to setDelegate() accepted a non-null object reference, then delegate to that 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 class is intended to be thread-safe; any classes deriving from it should ensure that the relevant methods are callable from any thread.

See also

ProxcardAPI for related API functions

Inheritance diagram for ProxcardListener:

Public Member Functions
	ProxcardListener ()
	Default constructor - builds a listener object then enables receipt of events from the driver.
	ProxcardListener (boolean startEnabled)
	Constructor - builds a listener object then optionally enables receipt of events from the driver. More...
void	dataEvent (@NonNull ProxcardData data)
	Callback which is invoked when an RFID tag or proxcard is successfully scanned. More...
final void	disable ()
	Disable receipt of events from the driver by this object. More...
final void	enable ()
	Enable receipt of events from the driver by this object. More...
void	errorEvent (@NonNull ErrorCode error)
	Callback which is invoked when a proxcard scan fails. More...
final void	setDelegate (Delegate newDelegate)
	Set the delegate which will receive event callbacks if default listener behaviour is not overridden. More...
void	startEvent ()
	Callback which is invoked when an RFID/proxcard scan is triggered. More...
void	stopEvent ()
	Callback which is invoked when a proxcard scan is stopped, regardless of reason. More...
void	timeoutEvent ()
	Callback which is invoked when RFID/proxcard scanning times out. More...

Constructor & Destructor Documentation

ProxcardListener()

ProxcardListener

(

boolean

startEnabled

)

Constructor - builds a listener object then optionally enables receipt of events from the driver.

Parameters

startEnabled

If set, the listener object is enabled immediately (equivalent of default constructor), otherwise it is disabled until the first call to enable()

Member Function Documentation

dataEvent()

void dataEvent

(

@NonNull ProxcardData

data

)

Callback which is invoked when an RFID tag or proxcard is successfully scanned.

This method will be triggered by the driver when a connected Grabba device successfully scans a proxcard, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via 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.

Parameters

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

Implements ProxcardInterface.

disable()

final void disable ( )

inherited

Disable receipt of events from the driver by this object.

This has no effect if the object was already disabled.

enable()

final void enable ( )

inherited

Enable receipt of events from the driver by this object.

This has no effect if the object was already enabled.

errorEvent()

void errorEvent

(

@NonNull ErrorCode

error

)

Callback which is invoked when a proxcard scan fails.

This method will be triggered by the driver when a proxcard scan on a connected Grabba device fails for any reason other than timeout or cancellation, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via 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.

Parameters

error

Error code indicating the reasons for the failure

Implements ProxcardInterface.

setDelegate()

final void setDelegate ( Delegate  newDelegate )

inherited

Set the delegate which will receive event callbacks if default listener behaviour is not overridden.

Delegation may alternatively be disabled by providing a null reference here.

Parameters

newDelegate

If null, disables delegation; if non-null, enables delegation and sets the delegate to the supplied object.

startEvent()

void startEvent

(

)

Callback which is invoked when an RFID/proxcard scan is triggered.

This method will be triggered by the driver when there is a connected Grabba device with proxcard capabilities, ProxcardAPI.startScan() is called, and the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via 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.

Implements ProxcardInterface.

stopEvent()

void stopEvent

(

)

Callback which is invoked when a proxcard scan is stopped, regardless of reason.

This method will be triggered by the driver when a proxcard scan is stopped, regardless of whether it completed successfully, providing the listener object is enabled.

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

• dataEvent will be triggered at least once if the operation successfully completed
• timeoutEvent will be triggered if the operation timed out before it could be completed (e.g. no card in range)
• 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 (at construction or via 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.

Implements ProxcardInterface.

timeoutEvent()

void timeoutEvent

(

)

Callback which is invoked when RFID/proxcard scanning times out.

This method will be triggered by the driver when a proxcard scan on a connected Grabba device times out, providing the listener object is enabled.

Override this method to receive callbacks when the object is enabled (at construction or via 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.

Implements ProxcardInterface.