Description

Base class for receiving events related to the smartcard reader on a Grabba device.

The following events are supported by this class:

insertEvent - a card was inserted into a reader slot (note: SAM interfaces will never generate this event)
removeEvent - a card was removed from a reader slot (note: SAM interfaces will never generate this event)
powerUpEvent - a card was powered up
powerDownEvent - a card was powered down
PPS_Event - a PPS exchange operation completed successfully
APDU_Event - an asynchronous APDU exchange operation completed successfully
errorEvent - an asynchronous operation failed, regardless of reasons

Each event may invoke callbacks in two ways:

Subclassing - the relevant event methods (e.g. APDU_Event) 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 SmartcardInterface, 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: SmartcardAPI for related API functions

Inheritance diagram for SmartcardListener:

Public Member Functions
	SmartcardListener ()
	Default constructor - builds a listener object then enables receipt of events from the driver.

	SmartcardListener (boolean startEnabled)
	Constructor - builds a listener object then optionally enables receipt of events from the driver. More...

void	APDU_Event (@NonNull SmartcardInterfaceID iface, @NonNull ResponseAPDU response)
	Callback which is invoked when an asynchronous APDU exchange operation completes successfully. 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 SmartcardInterfaceID iface, @NonNull ErrorCode error)
	Callback which is invoked when an asynchronous contact smart card operation fails, regardless of reasons. More...

void	insertEvent (@NonNull SmartcardInterfaceID iface)
	Callback which is invoked when a contact smart card is inserted into a reader slot on the Grabba device. More...

void	powerDownEvent (@NonNull SmartcardInterfaceID iface)
	Callback which is invoked when a contact smart card is powered down, regardless of reasons. More...

void	powerUpEvent (@NonNull SmartcardInterfaceID iface, @NonNull byte[] ATR)
	Callback which is invoked when a contact smart card is powered up. More...

void	PPS_Event (@NonNull SmartcardInterfaceID iface, @NonNull SmartcardProtocol T, @NonNull SmartcardClock F, @NonNull SmartcardBaud D)
	Callback which is invoked when a PPS exchange operation completes successfully. More...

void	removeEvent (@NonNull SmartcardInterfaceID iface)
	Callback which is invoked when a contact smart card is removed from a reader slot on the Grabba device. More...

final void	setDelegate (Delegate newDelegate)
	Set the delegate which will receive event callbacks if default listener behaviour is not overridden. More...

Constructor & Destructor Documentation

◆ SmartcardListener()

SmartcardListener ( 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

◆ APDU_Event()

void APDU_Event	(	@NonNull SmartcardInterfaceID	iface,
		@NonNull ResponseAPDU	response
	)

Callback which is invoked when an asynchronous APDU exchange operation completes successfully.

This event is triggered after a call to SmartcardAPI.exchangeAPDU has been made and the associated response is received from the card.

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

iface	ID of the interface in which the operation occurred
response	APDU received by the Grabba device from the smart card

Implements SmartcardInterface.

◆ 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 SmartcardInterfaceID	iface,
		@NonNull ErrorCode	error
	)

Callback which is invoked when an asynchronous contact smart card operation fails, regardless of reasons.

This event is triggered when a call to SmartcardAPI.powerUp, SmartcardAPI.powerDown (if blocking parameter set false), SmartcardAPI.exchangePPS or SmartcardAPI.exchangeAPDU triggers an operation, but that operation does not complete successfully.

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. Also, if an operation fails due to card removal, no guarantees are made about the order in which powerDownEvent, removeEvent and errorEvent are triggered.

Parameters

iface	ID of the interface in which the operation failed
error	Information about the error condition which caused the operation to fail

Implements SmartcardInterface.

◆ insertEvent()

void insertEvent ( @NonNull SmartcardInterfaceID iface )

Callback which is invoked when a contact smart card is inserted into a reader slot on the Grabba device.

This event will never be triggered on SAM interfaces, since they do not allow for insertion or removal of cards whilst the device is powered on.

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

iface ID of the interface into which the card was inserted

Implements SmartcardInterface.

◆ powerDownEvent()

void powerDownEvent ( @NonNull SmartcardInterfaceID iface )

Callback which is invoked when a contact smart card is powered down, regardless of reasons.

This event may be triggered under any of the following circumstances:

SmartcardAPI.powerDown or CoreAPI.close are called
The card is removed from the reader and it was previously powered up
An unexpected error is detected by the card reader or driver when communicating with this card

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. Also note that, if a card is removed when powered, no guarantees are made about the order in which removeEvent and powerDownEvent are triggered.

Parameters

iface ID of the interface for which the card has been powered down

Implements SmartcardInterface.

◆ powerUpEvent()

void powerUpEvent	(	@NonNull SmartcardInterfaceID	iface,
		@NonNull byte []	ATR
	)

Callback which is invoked when a contact smart card is powered up.

This event is typically triggered in response to a call to SmartcardAPI.powerUp, and will only be triggered if the card has been successfully powered up (including associated PPS exchange if requested). If the power-up operation failed (including failure of the associated PPS exchange if requested), then errorEvent will be triggered instead.

This event indicates that the card is ready for a manual PPS exchange if:

SmartcardAPI.powerUp was called with parameter autoPPS set to false
The card supports PPS exchange (i.e. starts up in negotiable mode, and indicates support for non-default parameters)

This event indicates that the card is ready to start APDU exchanges in either of the following cases:

SmartcardAPI.powerUp was called with parameter autoPPS set to true
The card does not support PPS exchange (i.e. starts up in specific mode, or does not indicate support for non-default parameters)

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. Also note that, when this event is triggered after a successful PPS exchange, no guarantees are made about the order in which powerUpEvent and PPS_Event will be triggered.

Parameters

iface	ID of the interface for which the card has been powered up
ATR	Answer-to-Reset (ATR) data received from the card

Implements SmartcardInterface.

◆ PPS_Event()

void PPS_Event	(	@NonNull SmartcardInterfaceID	iface,
		@NonNull SmartcardProtocol	T,
		@NonNull SmartcardClock	F,
		@NonNull SmartcardBaud	D
	)

Callback which is invoked when a PPS exchange operation completes successfully.

PPS exchanges are triggered either by SmartcardAPI.powerUp (with the autoPPS option enabled, as it is by default) or SmartcardAPI.exchangePPS. This event is triggered whenever such an exchange completes successfully.

This event indicates that the card is ready to start APDU exchanges.

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. Also, when triggered in conjunction with a power-up operation, no guarantees are made about the order in which powerUpEvent and PPS_Event will be triggered.

Parameters

iface	ID of the interface in which the operation occurred
T	Selected protocol (T) - should match that of the request
F	Clock rate conversion integer and associated maximum frequency - should match that of the request
D	Baud rate adjustment integer - should match that of the request

Implements SmartcardInterface.

◆ removeEvent()

void removeEvent ( @NonNull SmartcardInterfaceID iface )

Callback which is invoked when a contact smart card is removed from a reader slot on the Grabba device.

This event will never be triggered on SAM interfaces, since they do not allow for insertion or removal of cards whilst the device is powered on.

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

iface ID of the interface from which the card was removed

Implements SmartcardInterface.

◆ 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.

Description

Public Member Functions

Constructor & Destructor Documentation

◆ SmartcardListener()

Member Function Documentation

◆ APDU_Event()

◆ disable()

◆ enable()

◆ errorEvent()

◆ insertEvent()

◆ powerDownEvent()

◆ powerUpEvent()

◆ PPS_Event()

◆ removeEvent()

◆ setDelegate()