Package org.eclipse.keyple.plugin.pcsc

Interface PcscReader

All Superinterfaces:

org.eclipse.keyple.core.common.KeypleReaderExtension

public interface PcscReader
extends org.eclipse.keyple.core.common.KeypleReaderExtension

PC/SC specific KeypleReaderExtension.

Provides specific settings and methods for configuring a PC/SC reader.

Since:

2.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	PcscReader.DisconnectionMode	Action to be taken after the card is disconnected.
static class	PcscReader.IsoProtocol	Available transmission protocols as defined by the PC/SC standard.
static class	PcscReader.SharingMode	Connection mode to indicate if the application is willing to share the card with other applications.

Method Summary

Modifier and Type	Method	Description
int	getIoctlCcidEscapeCommandId()	Helper method that return the PC/SC IOCTL CCID "Escape" command identifier.
PcscReader	setContactless(boolean contactless)	Sets the reader transmission mode.
PcscReader	setDisconnectionMode(PcscReader.DisconnectionMode disconnectionMode)	Changes the action to be taken after disconnection (default value PcscReader.DisconnectionMode.LEAVE).
PcscReader	setIsoProtocol(PcscReader.IsoProtocol isoProtocol)	Changes the protocol to be used by the PC/SC reader when connecting to the card (PcscReader.IsoProtocol.T0, PcscReader.IsoProtocol.T1, or PcscReader.IsoProtocol.TCL), or PcscReader.IsoProtocol.ANY to connect using any available protocol (default value PcscReader.IsoProtocol.ANY).
PcscReader	setSharingMode(PcscReader.SharingMode sharingMode)	Changes the PC/SC sharing mode (default value PcscReader.SharingMode.EXCLUSIVE).
byte[]	transmitControlCommand(int commandId, byte[] command)	Transmits a control command to the terminal device.

Method Detail

setSharingMode

PcscReader setSharingMode(PcscReader.SharingMode sharingMode)

Changes the PC/SC sharing mode (default value PcscReader.SharingMode.EXCLUSIVE).

This mode will be used when a new Card is created.

If a card is already inserted, changes immediately the mode in the current Card object.

Parameters:

sharingMode - The PcscReader.SharingMode to use (must be not null).

Returns:

This instance.

Throws:

java.lang.IllegalArgumentException - If sharingMode is null

java.lang.IllegalStateException - If the sharing mode setting failed.

Since:

2.0.0

setContactless

PcscReader setContactless(boolean contactless)

Sets the reader transmission mode.

A PC/SC reader can be contact or contactless. There is no way by generic programming to know what type of technology a reader uses.

Thus, it is the responsibility of the application to give the reader the means to know his own type.

This can be done in two ways:

• by invoking this method,
• by giving the plugin the means to determine the type from the name of the reader. In the latter case, the application does not need to call this method, the reader will determine its type itself using the plugin parameters (see PcscPluginFactoryBuilder.

The default mode is the name-based determination performed by the plugin. See PcscPluginFactoryBuilder.Builder.useContactlessReaderIdentificationFilter(String).

Parameters:

contactless - true to set contactless mode, false to set contact mode.

Returns:

This instance.

Since:

2.0.0

setIsoProtocol

PcscReader setIsoProtocol(PcscReader.IsoProtocol isoProtocol)

Changes the protocol to be used by the PC/SC reader when connecting to the card (PcscReader.IsoProtocol.T0, PcscReader.IsoProtocol.T1, or PcscReader.IsoProtocol.TCL), or PcscReader.IsoProtocol.ANY to connect using any available protocol (default value PcscReader.IsoProtocol.ANY).

Parameters:

isoProtocol - The PcscReader.IsoProtocol to use (must be not null).

Returns:

This instance.

Throws:

java.lang.IllegalArgumentException - If isoProtocol is null

Since:

2.0.0

setDisconnectionMode

PcscReader setDisconnectionMode(PcscReader.DisconnectionMode disconnectionMode)

Changes the action to be taken after disconnection (default value PcscReader.DisconnectionMode.LEAVE).

The card is either reset or left as is.

The default value for this parameter if this method is not called is PcscReader.DisconnectionMode.LEAVE.

Parameters:

disconnectionMode - The PcscReader.DisconnectionMode to use (must be not null).

Returns:

This instance.

Throws:

java.lang.IllegalArgumentException - If disconnectionMode is null

Since:

2.0.0

transmitControlCommand

byte[] transmitControlCommand(int commandId,
                              byte[] command)

Transmits a control command to the terminal device.

This can be used to access specific features of the reader such as setting parameters, controlling LEDs, a buzzer or any other proprietary function defined by the reader manufacturer.

The supplied command identifier is internally converted into a control code expected by the current platform. Its actual value differs if the platform is Windows.

Parameters:

commandId - The command identifier.

command - A not null byte array containing the command data.

Returns:

The response data.

Throws:

java.lang.IllegalStateException - If the communication with the reader has failed.

Since:

2.1.0

getIoctlCcidEscapeCommandId

int getIoctlCcidEscapeCommandId()

Helper method that return the PC/SC IOCTL CCID "Escape" command identifier.

The PC/SC IOCTL CCID "Escape" command exists for all platforms but the value of its identifier differs from one to another (3500 for Windows, 1 for linux/MacOS).

Returns:

The IOCTL CCID "Escape" command identifier adapted to the OS.

Since:

2.1.0