com.linuxnet.jpcsc
Class Context

java.lang.Object
  com.linuxnet.jpcsc.Context

public final class Context

extends java.lang.Object

The Context class wraps the PCSC functions related to connecting/disconnecting to the PCSC service and card readers. An invocation of Connect() returns a connection to a Card allowing for the transmission of APDUs.

Constructor Summary

Context()
Constructor.

Method Summary

void	Cancel() Cancel all pending GetStatusChange() calls.
Card	Connect() Connect to a reader.
Card	Connect(int dwShareMode, int dwPreferredProtocols) Connect to a reader.
Card	Connect(java.lang.String szReader) Connect to a reader.
Card	Connect(java.lang.String szReader, int dwShareMode, int dwPreferredProtocols) Connect to a reader and return handle to card.
void	EstablishContext(int dwScope, java.lang.String pvReserved1, java.lang.String pvReserved2) Establish PCSC context.
protected void	finalize() Cleanup operation.
boolean	GetStatusChange(int timeout, State[] readerStates) Return status change of a set of readers.
java.lang.String[]	ListReaderGroups() List all reader groups known to the system.
java.lang.String[]	ListReaders() List all readers in all existing groups.
java.lang.String[]	ListReaders(java.lang.String group) List all readers in the given group.
java.lang.String[]	ListReaders(java.lang.String[] groups) List all readers in the given groups.
void	ReleaseContext() Release context.
static java.lang.String	StringifyError(int code) Return symbolic representation of an error.
State	WaitForCard(int millis) This method blocks until a card is inserted into a reader, or the specified time has been expired.
State	WaitForCard(java.lang.String rdrName, int millis) This method blocks until a card is inserted into the specified reader, or the specified time has been expired.

Methods inherited from class java.lang.Object

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

Constructor Detail

Context

public Context()

Constructor. Try to use established contexts as much as possible. This keeps the number of underlying connections to the PCSC-daemon low.

Method Detail

finalize

protected final void finalize()

Cleanup operation. Destroy context we have.

EstablishContext

public final void EstablishContext(int dwScope,
                                   java.lang.String pvReserved1,
                                   java.lang.String pvReserved2)

Establish PCSC context. Note that null is also a valid context on Windows, but not on Linux.

Parameters:

dwScope - PCSC.SCOPE_USER, PCSC.SCOPE_TERMINAL, PCSC.SCOPE_SYSTEMor PCSC.SCOPE_GLOBAL.

pvReserved1 - unused, may be null.

pvReserved2 - unused, may be null.

Returns:

established context handle.

ReleaseContext

public final void ReleaseContext()

Release context.

ListReaders

public final java.lang.String[] ListReaders()

List all readers in all existing groups.

Returns:

array of Strings naming all existing readers in the system.

ListReaders

public final java.lang.String[] ListReaders(java.lang.String group)

List all readers in the given group. All existing readers are returned if the passed group is null.

Parameters:

group - name of the reader group.

Returns:

array of Strings naming the readers of the given group.

ListReaders

public final java.lang.String[] ListReaders(java.lang.String[] groups)

List all readers in the given groups. All existing readers are returned if the passed parameter is null.

Parameters:

groups - arrays of Strings naming the groups.

Returns:

array of Strings naming the readers of the given groups.

Throws:

java.lang.IllegalArgumentException - if one of the group names is null.

ListReaderGroups

public final java.lang.String[] ListReaderGroups()

List all reader groups known to the system.

Returns:

array of Strings naming the existing reader groups.

WaitForCard

public State WaitForCard(int millis)

This method blocks until a card is inserted into a reader, or the specified time has been expired. Pass PCSC.INFINITE to block indefinitely. Null is returned if no readers are available, the time has been expired or some other state change has been detected.

Parameters:

millis - Waiting time, pass PCSC.INFINITE for indefinite waiting time.

Returns:

the reader state of the reader the card has been inserted, or null if no reader is currently available, the time has been expired or some other state change has been detected.

WaitForCard

public State WaitForCard(java.lang.String rdrName,
                         int millis)

This method blocks until a card is inserted into the specified reader, or the specified time has been expired. Pass PCSC.INFINITE to block indefinitely.

Parameters:

millis - Waiting time, pass PCSC.INFINITE to wait indefinitely.

Returns:

the reader state of the reader if a card has been inserted, or null, if the the time has been expired or some other state change has been detected.

GetStatusChange

public final boolean GetStatusChange(int timeout,
                                     State[] readerStates)

Return status change of a set of readers. For each reader, a State object has to be allocated and passed. The State object must be properly instantiated, especially with the name of an existing reader. The method then blocks for the given timeout or foerever (if PCSC.INFINITE is passed) until the state of one of the readers changes according to the bits in the dwCurrentState fields in the passed State objects. Refer to the PCSClite documentation for more information about the possible values for the dwCurrentState field.
By default, PCSC.STATE_UNAWARE is set for dwCurrentField in a newly allocated State object. In this case, the method returns immediately with the current state of the readers stored in the dwEventState fields.
You may want to use WaitForCard() to block until a card is inserted in a reader.
If null is passed for the readerStates parameter, the method will block until a reader is present in the system.

Parameters:

timeout - time to wait blocked until status changes as requested.

readerStates - array of State objects naming events and readers to observe.

Returns:

true if timeout has occured, false otherwise.

Connect

public final Card Connect()

Connect to a reader. This method blocks until a reader is available in the system and a card is inserted. It then returns a shared connection to this card using either protocol T=0 or T=1.

Returns:

handle to card for APDU exchange.

Connect

public final Card Connect(int dwShareMode,
                          int dwPreferredProtocols)

Connect to a reader. This method blocks until a reader is available in the system and a card is inserted. It then returns a connection to this card with the given sharing mode and for the given protocol.

Parameters:

dwShareMode - PCSC.SHARE_EXCLUSIVE, PCSC.SHARE_SHARED or PCSC.SHARE_DIRECT.

dwPreferredProtocols - PCSC.PROTOCOL_T0, PCSC.PROTOCOL_T1, PCSC.PROTOCOL_RAW, PCSC.PROTOCOL_ANY.

Returns:

handle to card for APDU exchange.

Connect

public final Card Connect(java.lang.String szReader)

Connect to a reader. This method first blocks until a reader is available, and then tries to connect to the specified reader. If the given reader does not exist, an exception is thrown. Otherwise JPCSC tries to connect in the mode SHARE_SHARED and for the PROTOCOL_T0 or PROTOCOL_T1. An exception occurs if the connect does not succeed.

Parameters:

szReader - name of the reader, must not be null.

Returns:

handle to card for APDU exchange.

Connect

public final Card Connect(java.lang.String szReader,
                          int dwShareMode,
                          int dwPreferredProtocols)

Connect to a reader and return handle to card. Parameters are the reader name to connect to, sharing mode (exclusive, shared, direct), and preferred protocol (PROTOCOL_T0, PROTOCOL_T1, PROTOCOL_RAW, PROTOCOL_ANY).

Parameters:

szReader - name of the reader, must not be null

dwShareMode - PCSC.SHARE_EXCLUSIVE, PCSC.SHARE_SHARED or PCSC.SHARE_DIRECT.

dwPreferredProtocols - PCSC.PROTOCOL_T0, PCSC.PROTOCOL_T1, PCSC.PROTOCOL_RAW, PCSC.PROTOCOL_ANY.

Returns:

handle to card for APDU exchange.

Cancel

public final void Cancel()

Cancel all pending GetStatusChange() calls.

StringifyError

public static java.lang.String StringifyError(int code)

Return symbolic representation of an error. Uses pcsc_stringify_error() on Linux.