Description

Interface for receiving contact smart card reader events.

Objects which implement this protocol may receive callbacks when these events occur, via delegation from a GrabbaSmartcardListener object.

Note that this protocol need not be directly implemented; it may be simpler to subclass GrabbaSmartcardListener and thereby receive the events directly.

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

See also: GrabbaSmartcardAPI for related API functions

Instance Methods
(void)	- APDU_EventFromInterface:response:
	Callback which is invoked when an asynchronous APDU exchange operation completes successfully. More...

(void)	- errorEventFromInterface:error:
	Callback which is invoked when an asynchronous contact smart card operation fails, regardless of reasons. 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...

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.

Parameters

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

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

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

Parameters

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

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

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

Parameters

iface ID of the interface into which the card was inserted

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

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

Parameters

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

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

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

Parameters

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

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

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

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

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

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

Parameters

iface ID of the interface from which the card was removed

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

Description

Instance Methods

Method Documentation

◆ APDU_EventFromInterface:response:()

◆ errorEventFromInterface:error:()

◆ insertEventFromInterface:()

◆ powerDownEventFromInterface:()

◆ powerUpEventFromInterface:ATR:()

◆ PPS_EventFromInterface:T:F:D:()

◆ removeEventFromInterface:()