GrabbaSmartcardListener Class Reference

Description

Base magstripe-event listener class, for receiving events from the Grabba device's contact smart card reader.

The following events are supported by this class:

• Insert - a card was inserted into a reader slot (note: SAM interfaces will never generate this event)
• Remove - a card was removed from a reader slot (note: SAM interfaces will never generate this event)
• PowerUp - a card was powered up
• PowerDown - a card was powered down
• PPS - a PPS exchange operation completed successfully
• APDU - an asynchronous APDU exchange operation completed successfully
• Error - an asynchronous operation failed, regardless of reasons

Each event may invoke callbacks in two ways:

• Subclassing - the relevant event methods (e.g. insertEvent) 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 GrabbaSmartcardProtocol, 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

GrabbaSmartcardAPI for related API functions

Inheritance diagram for GrabbaSmartcardListener:

Instance Methods
(void)	- APDU_EventFromInterface:response:
	Callback which is invoked when an asynchronous APDU exchange operation completes successfully. 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)	- errorEventFromInterface:error:
	Callback which is invoked when an asynchronous contact smart card operation fails, regardless of reasons. 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)	- insertEventFromInterface:
	Callback which is invoked when a contact smart card is inserted into a reader slot on the Grabba device. More...
(void)	- powerDownEventFromInterface:
	Callback which is invoked when a contact smart card is powered down, regardless of reasons. More...
(void)	- powerUpEventFromInterface:ATR:
	Callback which is invoked when a contact smart card is powered up. More...
(void)	- PPS_EventFromInterface:T:F:D:
	Callback which is invoked when a PPS exchange operation completes successfully. More...
(void)	- removeEventFromInterface:
	Callback which is invoked when a contact smart card is removed from a reader slot on the Grabba device. More...

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

Method Documentation

APDU_EventFromInterface:response:()

- (void) APDU_EventFromInterface:		(GrabbaSmartcardInterfaceID)	iface
response:		(GrabbaResponseAPDU *_Nonnull)	response

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

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

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.

Parameters

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

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.

errorEventFromInterface:error:()

- (void) errorEventFromInterface:		(GrabbaSmartcardInterfaceID)	iface
error:		(GrabbaErrorCode *_Nonnull)	error

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

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

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

Parameters

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

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

insertEventFromInterface:()

- (void) insertEventFromInterface:

(GrabbaSmartcardInterfaceID)

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

Parameters

iface

ID of the interface into which the card was inserted

powerDownEventFromInterface:()

- (void) powerDownEventFromInterface:

(GrabbaSmartcardInterfaceID)

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:

• powerDown or 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

If a card is removed when powered, both powerDownEvent and removeEvent will be triggered; no guarantees are made about the order in which that occurs.

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.

Parameters

iface

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

powerUpEventFromInterface:ATR:()

- (void) powerUpEventFromInterface:		(GrabbaSmartcardInterfaceID)	iface
ATR:		(NSData *_Nonnull)	ATR

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

This event is typically triggered in response to a call to 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:

• 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)

When triggered after a successful PPS exchange, no guarantees are made about the order in which powerUpEvent and PPS_Event 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.

Parameters

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

PPS_EventFromInterface:T:F:D:()

- (void) PPS_EventFromInterface:		(GrabbaSmartcardInterfaceID)	iface
T:		(GrabbaSmartcardProtocolID)	T
F:		(GrabbaSmartcardClock)	F
D:		(GrabbaSmartcardBaud)	D

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

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

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

When triggered in conjunction with a power-up operation, both PPS_Event and powerUpEvent will be called; no guarantees are made about the order in which that occurs.

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.

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

removeEventFromInterface:()

- (void) removeEventFromInterface:

(GrabbaSmartcardInterfaceID)

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

Parameters

iface

ID of the interface from which the card was removed

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.