org.eclipse.keyple.core.card.message

Interface ProxyReader

All Superinterfaces:

Reader

All Known Subinterfaces:

SmartSelectionReader

All Known Implementing Classes:

AbstractLocalReader, AbstractObservableLocalAutonomousReader, AbstractObservableLocalReader, AbstractReader

public interface ProxyReader
extends Reader

Defines the methods of a Reader for communicating with cards.

Exchanges are made using CardSelectionRequest/CardRequest which in return result in CardSelectionResponse/CardResponse.
The CardSelectionRequest includes the card selection data and an optional APDU list.
The CardSelectionRequest contains the result of the selection and the optional responses to the APDUs.

The CardRequest are transmitted individually (transmitCardRequest(CardRequest, ChannelControl) or by a list transmitCardSelectionRequests(List, MultiSelectionProcessing, ChannelControl) allowing applications to provide several selection patterns with various options.

releaseChannel() is used to control the closing of logical and physical channels taking into account the observation mechanisms potentially in progress.

Since:

0.9

Method Summary

Modifier and Type	Method and Description
void	releaseChannel() Release the communication channel previously established with the card.
CardResponse	transmitCardRequest(CardRequest cardRequest, ChannelControl channelControl) Transmits a single CardRequest passed as an argument and returns a CardResponse.
java.util.List<CardSelectionResponse>	transmitCardSelectionRequests(java.util.List<CardSelectionRequest> cardSelectionRequests, MultiSelectionProcessing multiSelectionProcessing, ChannelControl channelControl) Transmits the list of CardSelectionRequest and gets in return a list of CardSelectionResponse.

Methods inherited from interface org.eclipse.keyple.core.service.Reader

activateProtocol, deactivateProtocol, getName, isCardPresent, isContactless

Method Detail

transmitCardSelectionRequests

java.util.List<CardSelectionResponse> transmitCardSelectionRequests(java.util.List<CardSelectionRequest> cardSelectionRequests,
                                                                    MultiSelectionProcessing multiSelectionProcessing,
                                                                    ChannelControl channelControl)

Transmits the list of CardSelectionRequest and gets in return a list of CardSelectionResponse.

The actual processing of each CardSelectionRequest is similar to that performed by transmitCardRequest(CardRequest, ChannelControl) (see this method for further explanation of how the process works).

If the multiSelectionProcessing parameter equals to MultiSelectionProcessing.FIRST_MATCH, the iteration over the CardSelectionRequest list is interrupted at the first processing that leads to an open logical channel state. In this case, the list of CardSelectionResponse may be shorter than the list of CardSelectionRequest provided as input.

If it equals to MultiSelectionProcessing.PROCESS_ALL, all the CardSelectionRequest are processed and the logical channel is closed after each process.
The physical channel is managed by the ChannelControl parameter as in transmitCardRequest(CardRequest, ChannelControl).

In the case of a selection specifying a card protocol, it is imperative to activate it previously with the method Reader.activateProtocol(String, String). An IllegalStateException exception will be thrown in case of inconsistency.

Parameters:

cardSelectionRequests - A not empty list of CardSelectionRequest.

multiSelectionProcessing - The multi card processing flag (must be not null).

channelControl - indicates if the physical channel has to be closed at the end of the processing (must be not null).

Returns:

A not null response list (can be empty).

Throws:

KeypleReaderIOException - if the communication with the reader or the card has failed

java.lang.IllegalArgumentException - if one of the arguments is null.

java.lang.IllegalStateException - in case of configuration inconsistency or reader is not registered.

Since:

0.9

transmitCardRequest

CardResponse transmitCardRequest(CardRequest cardRequest,
                                 ChannelControl channelControl)

Transmits a single CardRequest passed as an argument and returns a CardResponse.

The process includes the following steps:

• Open the physical channel if it is not already open.
• If the CardRequest contains a non null CardSelector. The 3 following operations are performed in this order:
  1. If specified, check the card protocol (compare the specified protocol with the current protocol).
  2. If specified, check the ATR (test the received ATR with the regular expression from the filter)
  3. If specified, select the application by AID
  If one of the 3 operations fails, then an empty response containing the selection status is returned.
  If all executed operations are successful then a selection status is created with the corresponding data (ATR and/or FCI) and the hasMatched flag true.
• If the CardRequest contains a list of APDUs to send (ApduRequest) then each APDU is sent to the card and its response (ApduResponse is added to a new list.
• Closes the physical channel if the ChannelControl is ChannelControl.CLOSE_AFTER.
• Returns a CardResponse containing:
  • a boolean giving the current logical channel status.
  • a boolean giving the previous logical channel status.
  • if a selection has been made (CardSelector not null) a SelectionStatus object containing the elements resulting from the selection.
  • if APDUs have been transmitted to the card, the list of responses to these APDUs.

Note: in case of a communication error when sending an APDU an KeypleReaderIOException exception is thrown. Responses to previous APDUs are attached to this exception.
This allows the calling application to be tolerant to the card tearing and to recover a partial response to the CardRequest.

Parameters:

cardRequest - The CardRequest to be processed (must be not null).

channelControl - indicates if the physical channel has to be closed at the end of the processing (must be not null).

Returns:

cardResponse A not null CardResponse.

Throws:

KeypleReaderIOException - if the communication with the reader or the card has failed

java.lang.IllegalArgumentException - if one of the arguments is null or reader is not registered.

Since:

0.9

releaseChannel

void releaseChannel()

Release the communication channel previously established with the card.

If the ProxyReader is not observable the logical and physical channels must be closed instantly.
If the ProxyReader is observable, the closure of both channels must be the result of the completion of a removal sequence.

TODO check how to make this conditional on the WAIT_FOR_SE_PROCESSING state.

Since:

1.0