com.ibm.jc
Class JCTerminal

java.lang.Object
  com.ibm.jc.JCTerminal

Direct Known Subclasses:

NativeJCTerminal, OCFJCTerminal, PCSCJCTerminal, RemoteJCTerminal, TimeJCTerminal, TraceJCTerminal

public abstract class JCTerminal

extends java.lang.Object

Terminal abstraction for smart card communications. All Java-based off-card components rely on this abstract class to communicate with a card terminal of some smart card. This class offers a very simple and easy to use API. It addresses the standard functionality required by most smart card aware applications and the features offered by normal card terminals.

Field Summary

static int	CARD_PRESENT Terminal state: card present in terminal slot (0x04).
static int	ERROR Terminal state: some communication error happened (0x08).
static int	NOT_CONNECTED Terminal state: process is not connected to terminal (0x01).
static int	PROTOCOL_T0 Protocol type for PPS: T=0 (0x00)
static int	PROTOCOL_T1 Protocol type for PPS: T=1 (0x01)
static int	PROTOCOL_TCL Protocol type for PPS: T=CL (0x05)
static int	SLOT_EMPTY Terminal state: no card present in terminal slot (0x02).

Constructor Summary

JCTerminal()

Method Summary

abstract void	close() Close connection to card terminal.
JCTerminal	filterFor() Determine if terminal is a filter.
JCTerminal	filterFor(JCTerminal term) Attache some terminal to this terminal filter.
void	generateParityError(int n) Schedule generation of parity error for the n-th character to be transmitted (in or out).
java.lang.String	getErrorMessage()
static JCTerminal	getInstance(java.lang.String spec, java.lang.String param) Create an instance of the specified terminal.
abstract int	getState()
JCTerminal	init(java.lang.Object param) Initialize terminal.
byte[]	ioctl(int req, byte[] param, int off, int len) Perform terminal-dependent action...
abstract void	open() Open the card terminal.
void	pps(int protocol, int parameter) Select protocol and parameters for subsequent communication (can only be applied immediately after card reset).
abstract byte[]	send(int nad, byte[] toSend, int offset, int len) Send data to the card (using the negotiated protocol).
byte[]	send(int nad, int cla, int ins, int p1, int p2, int p3, byte[] toSend, int offset, int le) Send data to the card terminal.
byte[]	sendraw(byte[] data, int off, int len, int timeout) Send data to the card (using *no* protocol, raw bytes are transmitted without modification).
java.lang.String	toString()
abstract byte[]	waitForCard(int time) Wait for insertion of a card and return ATR (answer to reset).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NOT_CONNECTED

public static final int NOT_CONNECTED

Terminal state: process is not connected to terminal (0x01).

See Also:

Constant Field Values

SLOT_EMPTY

public static final int SLOT_EMPTY

Terminal state: no card present in terminal slot (0x02). The terminal cannot detect card presence if this bit is zero together with CARD_PRESENT.

See Also:

Constant Field Values

CARD_PRESENT

public static final int CARD_PRESENT

Terminal state: card present in terminal slot (0x04). The terminal cannot detect card presence if this bit is zero together with SLOT_EMPTY.

See Also:

Constant Field Values

ERROR

public static final int ERROR

Terminal state: some communication error happened (0x08).

See Also:

Constant Field Values

PROTOCOL_T0

public static final int PROTOCOL_T0

Protocol type for PPS: T=0 (0x00)

See Also:

Constant Field Values

PROTOCOL_T1

public static final int PROTOCOL_T1

Protocol type for PPS: T=1 (0x01)

See Also:

Constant Field Values

PROTOCOL_TCL

public static final int PROTOCOL_TCL

Protocol type for PPS: T=CL (0x05)

See Also:

Constant Field Values

Constructor Detail

JCTerminal

public JCTerminal()

Method Detail

getInstance

public static JCTerminal getInstance(java.lang.String spec,
                                     java.lang.String param)

Create an instance of the specified terminal. The terminal specifier is first checked against the definitions in the system and personal setup files. The referred setup value or the supplied specifier is evaluated as listed below:

null, ""

A null reference or an empty string refer to the default terminal. The default terminal is defined in the system or personal terminal properties file.

DLL:API

A NativeJCTerminal is instanciated. DLL refers to the DLLs to used and API is the number of the API to be used with this DLL.

NICKNAME

If the specifier does not contain a dot (`.') then a Java class named com.ibm.jc.terminal.NICKNAMEJCTerminal is instanciated. This instance must be a subclass of JCTerminal.

CLASSQUAL

If none of the above cases matches then the specifier is treated as a fully qulified class name. This class is instanciated and must be a subclass of JCTerminal.

Parameters:

spec - the terminal specifier. This parameter can be null.

param - this is used to initialize the terminal (see init method). This parameter can be null.

Throws:

java.lang.RuntimeException - various runtime exceptions if instanciation or cast to JCTerminal fails.

See Also:

JCTerminal, NativeJCTerminal

init

public JCTerminal init(java.lang.Object param)

Initialize terminal. If this method is called with null then the terminal uses some default settings.

Parameters:

param - some parameter initializing the terminal. The possible types and meanings depend on the specific terminal. It is expected that all terminals support at least some String based initialization.

Returns:

this

toString

public java.lang.String toString()

Returns:

a description of the card terminal settings and the current terminal state. The string might span multiple lines and should not end with a new line. This default implementation returns the terminal name and the state as hexdecimal value. The terminal is either the full class name or the T part if the class name is of the form com.ibm.jc.terminal.TJCTerminal.

getErrorMessage

public java.lang.String getErrorMessage()

Returns:

a description of the last error. If not error is registered or if there is not verbose description a null value is returned. This default implementation returns null.

filterFor

public JCTerminal filterFor()

Determine if terminal is a filter. A filter modifies, traces, or otherwise processes invocations to some underlying terminal.

Returns:

null if this terminal is not a filter and nonnull if it is a filter. The underlying terminal is returned.

filterFor

public JCTerminal filterFor(JCTerminal term)

Attache some terminal to this terminal filter. The default implementation throws an exception. Terminal filter classes must override this method.

Returns:

previous underlying terminal.

open

public abstract void open()

Open the card terminal. Access to the terminal by other processes usually is not possible anylonger.

close

public abstract void close()

Close connection to card terminal. The caller can reconnect to the terminal using the open() method.

See Also:

open()

waitForCard

public abstract byte[] waitForCard(int time)

Wait for insertion of a card and return ATR (answer to reset). If a card is already inserted this explicitly resets the card and returns the ATR. If no card is inserted the call blocks for a specified amount of time.

Note, not all terminals support the time parameter. It is only guaranteed that the call will not block longer than the specified time. It might return immediately with null.

Parameters:

time - the calls blocks for specified milliseconds.

Returns:

ATR (answer to reset) or null if no ATR could be retrieved. The reason might be that no card is inserted or because of communication problems.

getState

public abstract int getState()

Returns:

the status of the terminal. See constants. The status condition of the last call to the terminal.

send

public abstract byte[] send(int nad,
                            byte[] toSend,
                            int offset,
                            int len)

Send data to the card (using the negotiated protocol). (To make applications independent of logical channels JCard.send() should be used)

Parameters:

nad - node address to which data is being sent (high nibble = destination address, low = source address). Address values: 2=host, 1=terminal, 0=card. A value of 0 means from host to card.

toSend - byte array containing APDU data to be sent

offset - offset starting at which APDU data sending is to begin

len - number of bytes to be transmitted

Returns:

response APDU as a byte array

Throws:

JCException - if communication failed or if some parameters are wrong

See Also:

com.ibm.jc.JCard.send

sendraw

public byte[] sendraw(byte[] data,
                      int off,
                      int len,
                      int timeout)

Send data to the card (using *no* protocol, raw bytes are transmitted without modification).

Parameters:

data - byte array containing raw data to be sent

off - offset starting at which raw data sending is to begin

len - number of bytes to be transmitted

timeout - time to wait for response data (time unit is device-dependent, ignored by some readers)

Returns:

raw response data

Throws:

JCException - if communication failed or if some parameters are wrong

pps

public void pps(int protocol,
                int parameter)

Select protocol and parameters for subsequent communication (can only be applied immediately after card reset).

Parameters:

protocol - protocol type to be used (PROTOCOL_T0 or PROTOCOL_T1 in contact mode, PROTOCOL_TCL in contact-less mode)

parameter - baud rate

Throws:

JCException - if communication failed or if some parameters are wrong

See Also:

PROTOCOL_T0, PROTOCOL_T1, PROTOCOL_TCL, send

generateParityError

public void generateParityError(int n)

Schedule generation of parity error for the n-th character to be transmitted (in or out).

Parameters:

n - index of character to manipulate (0-based)

Throws:

JCException - if some parameters are wrong

ioctl

public byte[] ioctl(int req,
                    byte[] param,
                    int off,
                    int len)

Perform terminal-dependent action...

Parameters:

req - request code

param - array holding request parameters (may be null)

off - offset to parameters

len - length of parameters

Returns:

array holding the request response

Throws:

JCException - if some parameters are wrong

send

public final byte[] send(int nad,
                         int cla,
                         int ins,
                         int p1,
                         int p2,
                         int p3,
                         byte[] toSend,
                         int offset,
                         int le)

Send data to the card terminal. (To make applications independent of logical channels JCard.send() should be used)

Parameters:

nad - node address to which data is being sent

cla - CLA byte of APDU (byte #0)

ins - INS byte of APDU (byte #1)

p1 - P1 byte of APDU (byte #2)

p2 - P2 byte of APDU (byte #3)

p3 - P3 or LC byte of APDU (byte #4). This byte is omitted if parameter has value -1.

toSend - byte array containing command data of APDU. Command data starts at byte #5.

offset - offset starting at which data sending is to begin

le - LE byte of APDU (appended to APDU). This byte is omitted if parameter has value -1.

Returns:

response APDU as a byte array

Throws:

JCException - if communication failed or if some parameters are wrong

See Also:

com.ibm.jc.JCard.send