Description

Provides access to Grabba contact smart card reader functionality, such as exchanging APDUs.

Callbacks to user-provided code may be triggered in response to relevant events, e.g. insertion of a smartcard. Refer to the GrabbaSmartcardListener 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.

Most API functions require an interface ID, so as to support Grabba devices which contain more than one contact smart card interface - e.g. a Grabba device may contain one full-sized card slot and one Secure Access Module (SAM) interface. Users of single-interface devices should use the value returned by defaultInterface (GrabbaSmartcardAPI) to populate this parameter; refer to that function and to GrabbaSmartcardInterfaceID for additional details.

Each interface may contain a smart card or not; the CardPresent() method queries this. Only full-sized card slots allow for insertion and removal when the Grabba device is powered; if this occurs, any pending actions on that interface are cancelled, and notifications are provided via any active GrabbaSmartcardListener objects.

Communication with an inserted card usually involves four steps:

Power up - call powerUp to trigger this, or powered to query whether it has occurred
PPS (settings) exchange - automatically triggered by powerUp in most cases, or can be manually triggered by exchangePPS if needed
APDU (data) exchange - call exchangeAPDU_AtInterface:command:error: or syncExchangeAPDU , repeating as needed
Power down - once all communications have finished, call powerDown to power the card down

Cards which boot up in "specific mode" (as defined in ISO/IEC 7816-3), or which do not indicate support for non-default parameters or protocols, will not accept PPS exchanges. Consequently, only three steps are needed for them - power up, APDU exchange and power down. The PPS event in GrabbaSmartcardListener (for auto PPS exchange) or the readyForPPS method (for manual PPS exchange) may be used to differentiate between cards which support PPS exchange and those which do not.

Grabba devices do not support concurrent smart card operations, even if the operations target different interfaces. Consequently, for correct operation it is necessary to wait for each power-up, power-down or APDU-exchange operation to be completed (with notifications supplied via GrabbaSmartcardListener objects for asynchronous operations) prior to launching another such operation. Failure to do so will result in DeviceBusy errors being returned to the calling code.

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 GrabbaSmartcardAPI:

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

Class Methods
(BOOL)	+ cardPresentInInterface:
	Query whether there is currently a contact smart card present in a given interface on a connected Grabba device. More...

(GrabbaSmartcardInterfaceID)	+ defaultInterface
	Obtain the ID of the default interface for a connected Grabba device. More...

(void)	+ exchangeAPDU_AtInterface:command:error:
	Asynchronously exchange an APDU (Application Protocol Data Unit) with a card in a given interface on a connected Grabba device. More...

(void)	+ exchangePPS_AtInterface:T:F:D:error:
	Asynchronously exchange a PPS (Protocol and Parameter Selection) with a card in a given interface on a connected Grabba device. More...

(void)	+ powerDownInterface:blocking:error:
	[DEPRECATED] Attempt to power down a contact smart card in a given card interface on a connected Grabba device More...

(void)	+ powerDownInterface:blocking:waitIfCardBusy:error:
	Attempt to power down a contact smart card in a given card interface on a connected Grabba device. More...

(BOOL)	+ poweredInterface:
	Query whether a contact smart card is currently powered up in a given card interface on a connected Grabba device. More...

(void)	+ powerUpInterface:autoPPS:error:
	Attempt to power up a contact smart card in a given card interface on a connected Grabba device. More...

(BOOL)	+ PPS_ExchangedAtInterface:
	Query whether a contact smart card has had a successful PPS exchange since its last power-up. More...

(BOOL)	+ readyForPPS_AtInterface:
	Query whether a contact smart card is ready for a PPS exchange. More...

(BOOL)	+ supported
	Query whether there is currently a connected Grabba device with smartcard functionality. More...

(GrabbaResponseAPDU *_Nonnull)	+ syncExchangeAPDU_AtInterface:command:error:
	Synchronously exchange an APDU (Application Protocol Data Unit) with a card in a given interface on a connected Grabba device. More...

(BOOL)	+ validInterface:
	Query whether a given interface ID represents a valid interface on a connected Grabba device. More...

Method Documentation

◆ cardPresentInInterface:()

+ (BOOL) cardPresentInInterface: (GrabbaSmartcardInterfaceID) iface

Query whether there is currently a contact smart card present in a given interface on a connected Grabba device.

This is a non-blocking call; card presence/absence information is cached internally by the driver.

Parameters

iface ID of the interface which is being queried

Returns: True if there is a connected Grabba device, the supplied interface ID is valid for that device, and that interface currently holds a card; false otherwise.

◆ defaultInterface()

+ (GrabbaSmartcardInterfaceID) defaultInterface

Obtain the ID of the default interface for a connected Grabba device.

The default interface is as follows:

If a device contains a full-sized card slot, the default will be the first such slot (GrabbaSmartcardPrimarySlot).
If a device contains a SAM interface and no full-sized card slots, the default will be the first SAM interface (GrabbaSmartcardPrimarySAM).

The result of this function will be fixed for the lifetime of a connection; consequently, it is acceptable to cache the value and then use it for all subsequent API calls.

Note that this interface will always be a valid interface on any Grabba device with contact smart card support. This function should not be called unless such a device is currently connected.

Returns: Either GrabbaSmartcardPrimarySlot or GrabbaSmartcardPrimarySAM, depending on device capabilities

◆ exchangeAPDU_AtInterface:command:error:()

+ (void) exchangeAPDU_AtInterface:	(GrabbaSmartcardInterfaceID)	iface
command:	(GrabbaCommandAPDU *_Nonnull)	command
error:	(GrabbaErrorCode *_Nonnull)	error

Asynchronously exchange an APDU (Application Protocol Data Unit) with a card in a given interface on a connected Grabba device.

If the supplied error code indicates no prior errors, there is a connected Grabba device with contact smart card capabilities, the selected interface is valid for that device, and that interface contains a powered-on smart card, then a command APDU will be sent to that card. Following this, the result of the operation will be provided to any active GrabbaSmartcardListener objects, either as an APDU_Event if it succeeds or an ErrorEvent if it fails (regardless of reason).

If a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, the connected Grabba device lacks contact smart card capabilities, the interface ID is invalid for the device, there is no card in the selected interface, or the card has not been powered on, then the error code will be updated accordingly and no further action will be taken.

Parameters

iface	ID of the interface containing the card
command	APDU to exchange with the card
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.

See also: SyncExchangeAPDU for a synchronous (blocking) equivalent to this function.

◆ exchangePPS_AtInterface:T:F:D:error:()

+ (void) exchangePPS_AtInterface:	(GrabbaSmartcardInterfaceID)	iface
T:	(GrabbaSmartcardProtocolID)	T
F:	(GrabbaSmartcardClock)	F
D:	(GrabbaSmartcardBaud)	D
error:	(GrabbaErrorCode *_Nonnull)	error

Asynchronously exchange a PPS (Protocol and Parameter Selection) with a card in a given interface on a connected Grabba device.

If the supplied error code indicates no prior errors, there is a connected Grabba device with contact smart card capabilities, the selected interface is valid for that device, that interface contains a powered-on smart card, that card supports PPS exchanges, and no PPS or APDU exchanges have taken place since the card was powered up, then a PPS will be sent to that card.

Event notifications will be provided to any active GrabbaSmartcardListener objects as follows:

PPS_Event - if the operation is successful
ErrorEvent - if the operation fails (regardless of reason)

If a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, the connected Grabba device lacks contact smart card capabilities, the interface ID is invalid for the device, there is no card in the selected interface, the card has not been powered on, or a prior PPS or APDU exchange was triggered since power-up, then the error code will be updated accordingly and no further action will be taken.

Note: This method should only be necessary on S- and Z-series devices, and only then in cases where the card's preferred settings are not supported by the Grabba device (i.e. Fi/Di ratio below 31). In all other cases the PPS exchange can be performed automatically; see PowerUp() for details.

Parameters

iface	ID of the interface containing the card
T	Protocol selection as per ISO/IEC 7816-3
F	Clock rate conversion integer and maximum supported frequency as per ISO/IEC 7816-3
D	Baud rate adjustment integer as per ISO/IEC 7816-3
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.

◆ init()

- (instancetype _Nullable) init

Not callable (NS_UNAVAILABLE) since this is a static class.

◆ powerDownInterface:blocking:error:()

+ (void) powerDownInterface:	(GrabbaSmartcardInterfaceID)	iface
blocking:	(BOOL)	blocking
error:	(GrabbaErrorCode *_Nonnull)	error

[DEPRECATED] Attempt to power down a contact smart card in a given card interface on a connected Grabba device

This is a deprecated form of powerDown provided solely for compatibility purposes. Behaviour is identical to calling the current version of the function with its waitIfCardBusy parameter set to NO. Refer to that function's documentation for details.

Parameters

iface	ID of the interface containing the card
blocking	If true (recommended), call is blocking and operation is synchronous; if false, call is non-blocking and operation is asynchronous.
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.

◆ powerDownInterface:blocking:waitIfCardBusy:error:()

+ (void) powerDownInterface:	(GrabbaSmartcardInterfaceID)	iface
blocking:	(BOOL)	blocking
waitIfCardBusy:	(BOOL)	waitIfCardBusy
error:	(GrabbaErrorCode *_Nonnull)	error

Attempt to power down a contact smart card in a given card interface on a connected Grabba device.

If the supplied error code indicates no prior errors, there is a connected Grabba device with contact smart card capabilities, the given interface is valid, and that interface contains a smart card, then an attempt will be made to power that card down. The results of this operation will be communicated as events to any active GrabbaSmartcardListener objects:

PowerDownEvent will trigger if the operation succeeds
ErrorEvent will trigger if the operation fails

If a prior error is indicated, or if the card in question is already powered down, then no action is taken, and the error code will not be updated.

If there is no connection, the connected Grabba device lacks contact smart card capabilities, the given interface ID is invalid for that device, or there is no card in the selected interface, then the error code will be updated accordingly and no further action will be taken.

This operation may be performed either synchronously or asynchronously:

Synchronous mode: This call blocks until either an error is detected or the operation is successfully completed. Any detected errors will be returned via the error parameter; no error events will be sent to GrabbaSmartcardListener objects. However, the PowerDownEvent will still trigger if/when the communication session is stopped.
Asynchronous mode: This call is non-blocking, and can only detect a small subset of possible error conditions. If the operation is successfully commenced, then GrabbaNoError is returned, and notifications will be sent to GrabbaSmartcardListener objects when the operation completes:
- PowerDownEvent will be triggered if the operation succeeds
- ErrorEvent will be triggered if the operation fails

Parameters

iface	ID of the interface containing the card
blocking	If true (recommended), call is blocking and operation is synchronous; if false, call is non-blocking and operation is asynchronous.
waitIfCardBusy	Modifies behaviour as follows: If power-down call occurs when card is inactive: parameter has no effect If card is busy with another operation (e.g. APDU exchange): If parameter is true (recommended): power-down is triggered after earlier operation completes If blocking parameter is also true, then this call will block through the earlier op and then the power-down op If parameter is false: GrabbaDeviceBusy error is returned; power-down does not occur
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.

◆ poweredInterface:()

+ (BOOL) poweredInterface: (GrabbaSmartcardInterfaceID) iface

Query whether a contact smart card is currently powered up in a given card interface on a connected Grabba device.

This is a non-blocking call; communication status is cached internally by the driver.

Parameters

iface ID of the interface which is being queried

Returns: True if there is a connected Grabba device, the supplied interface ID is valid for that device, and that interface currently holds a card which has been powered up; false otherwise.

◆ powerUpInterface:autoPPS:error:()

+ (void) powerUpInterface:	(GrabbaSmartcardInterfaceID)	iface
autoPPS:	(BOOL)	autoPPS
error:	(GrabbaErrorCode *_Nonnull)	error

Attempt to power up a contact smart card in a given card interface on a connected Grabba device.

If the supplied error code indicates no prior errors, there is a connected Grabba device with contact smart card capabilities, the given interface is valid, and that interface contains a smart card, then an attempt will be made to power that card up, and if that succeeds then a Protocol and Parameter Selection (PPS) message exchange will optionally be triggered.

If a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, the connected Grabba device lacks contact smart card capabilities, there is no card in the selected interface, or the card in question is already powered on, then the error code will be updated accordingly and no further action will be taken.

The results of the operation, if attempted, will be communicated as events to any active GrabbaSmartcardListener objects:

If the card supports PPS exchange, and parameter autoPPS == true:
- PowerUpEvent is triggered if power-up and PPS exchange both completed successfully
- PPS_Event is triggered if power-up and PPS exchange both completed successfully
- ErrorEvent is triggered if either power-up or PPS exchange failed
If the card does not support PPS exchange, or parameter autoPPS == false:
- PowerUpEvent is triggered if the card is successfully powered up
- ErrorEvent is triggered if the power-up operation fails

The triggering of PowerUpEvent may be used to inform the calling code as to the card's state - if that event doesn't trigger, then the card can be assumed to be powered down at the end of the operation.

The parameters selected for automatic PPS exchange (if enabled and supported) will be as follows:

If card's indicated parameter values are supported by the Grabba device, then they will be used
- Note that this should always be the case for S2- and GT-series devices
Otherwise, the default parameter values will be used (Fd = 372, Dd = 1, f_max = 5MHz, protocol T0 unless card only supports T1)

If the PPS exchange fails, then it is still possible to use the card; call PowerUp again with autoPPS set to false, then call exchangePPS with appropriate settings to manually configure the session protocol and parameters. However, if the card cannot be powered up in the first place then it is probably unusable.

Parameters

iface	ID of the interface containing the card
autoPPS	This parameter controls triggering of automatic PPS exchanges; it should be set true for all card types on S2- or GT-series devices, and for most card types on S- or Z-series devices. Behaviour is as follows: If card supports PPS exchange and autoPPS == true: PPS exchange is performed automatically after a successful power-up If card supports PPS exchange and autoPPS == false: no automatic PPS exchange; exchangePPS must be called post power-up If card doesn't support PPS exchange: this parameter has no effect; no automatic PPS exchange will occur
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.

◆ PPS_ExchangedAtInterface:()

+ (BOOL) PPS_ExchangedAtInterface: (GrabbaSmartcardInterfaceID) iface

Query whether a contact smart card has had a successful PPS exchange since its last power-up.

This is a non-blocking call; PPS exchange status is cached internally by the driver.

Parameters

iface ID of the interface which is being queried

Returns: True if there is a connected Grabba device, the supplied interface ID is valid for that device, that interface currently holds a card which has been powered up, and there has been a successful PPS exchange operation since it was last powered up; false otherwise

◆ readyForPPS_AtInterface:()

+ (BOOL) readyForPPS_AtInterface: (GrabbaSmartcardInterfaceID) iface

Query whether a contact smart card is ready for a PPS exchange.

This is a non-blocking call; PPS exchange status is cached internally by the driver.

A card is ready for PPS exchange if:

It has been powered up
It supports PPS exchange - which requires:
- Card boots in negotiable mode (the vast majority of cards do this)
- Card supports non-default parameter values (e.g. for faster-than-default transfer speeds) or more than one protocol
No PPS exchanges (whether manual or automatic) have been attempted since the card was powered up
No APDU exchanges have been attempted since the card was powered up

Parameters

iface ID of the interface which is being queried

Returns: True if there is a connected Grabba device, the supplied interface ID is valid for that device, that interface currently holds a card which has been powered up, the card supports PPS exchanges, and no PPS or APDU exchanges have occurred with the card since it was powered up; false otherwise

◆ supported()

+ (BOOL) supported

Query whether there is currently a connected Grabba device with smartcard 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 smartcard functionality; NO otherwise.

◆ syncExchangeAPDU_AtInterface:command:error:()

+ (GrabbaResponseAPDU* _Nonnull) syncExchangeAPDU_AtInterface:	(GrabbaSmartcardInterfaceID)	iface
command:	(GrabbaCommandAPDU *_Nonnull)	command
error:	(GrabbaErrorCode *_Nonnull)	error

Synchronously exchange an APDU (Application Protocol Data Unit) with a card in a given interface on a connected Grabba device.

If the supplied error code indicates no prior errors, there is a connected Grabba device with contact smart card capabilities, the selected interface is valid for that device, and that interface contains a powered-on smart card, then a command APDU will be sent to that card. If the operation fails, the error code will be updated; if it succeeds, the APDU received in response will be returned.

If a prior error is indicated, then no action is taken, and the error code will not be updated.

If there is no connection, the connected Grabba device lacks contact smart card capabilities, the interface ID is invalid for the device, there is no card in the selected interface, or the card has not been powered on, then the error code will be updated accordingly and no further action will be taken.

Note: This call will not result in any events being triggered on GrabbaSmartcardListener objects; all returned information is delivered via parameters and the method result, and this call will block for as long as is necessary to complete theoperation or detect its failure. Consequently, this function should not be called from any threads which have to perform latency-sensitive tasks (e.g. UI updates).

Parameters

iface	ID of the interface containing the card
command	APDU to exchange with the card
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.

Returns: The response APDU received from the card, if the operation completed successfully, otherwise a default-initialised APDU (status 0x6F00, no response data)

See also: ExchangeAPDU for an asynchronous (non-blocking) equivalent to this function.

◆ validInterface:()

+ (BOOL) validInterface: (GrabbaSmartcardInterfaceID) iface

Query whether a given interface ID represents a valid interface on a connected Grabba device.

Parameters

iface ID of the interface which is being queried

Returns: YES if there is a connected Grabba device and the supplied ID corresponds to a valid contact smart card interface on that device; false otherwise.

Description

Instance Methods

Class Methods

Method Documentation

◆ cardPresentInInterface:()

◆ defaultInterface()

◆ exchangeAPDU_AtInterface:command:error:()

◆ exchangePPS_AtInterface:T:F:D:error:()

◆ init()

◆ powerDownInterface:blocking:error:()

◆ powerDownInterface:blocking:waitIfCardBusy:error:()

◆ poweredInterface:()

◆ powerUpInterface:autoPPS:error:()

◆ PPS_ExchangedAtInterface:()

◆ readyForPPS_AtInterface:()

◆ supported()

◆ syncExchangeAPDU_AtInterface:command:error:()

◆ validInterface:()