net.rim.device.api.smartcard
Class SmartCardReaderSession

java.lang.Object
  net.rim.device.api.smartcard.SmartCardReaderSession

public abstract class SmartCardReaderSession
extends Object

Represents a communications session with a physical smartcard reader. Over this session, APDUs may be exchanged with the reader and smartcard to provide the desired functionality.

Sessions should not be held open when not in use. As a security precaution, only one open session is allowed to exist per SmartCardReader, and subsequent openSession requests will block until the current session is closed.

Note to implementors: Most, if not all, UI functionality has been implemented in the base class. Typically, subclasses should not need to implement any UI.

See Also:

SmartCardSession

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

Constructor Summary
	protected	SmartCardReaderSession(SmartCardReader reader) Construct a new SmartCardReaderSession.

Method Summary
	void	close() Closes this session, and unblocks a pending session.
	protected abstract void	closeImpl() Closes this session.
	AnswerToReset	getAnswerToReset() Returns the AnswerToReset provided by the physical smartcard present in the reader.
	protected abstract AnswerToReset	getAnswerToResetImpl() Returns the AnswerToReset provided by the physical smartcard present in the reader.
	SmartCard	getSmartCard() Returns the SmartCard driver that is able to communicate with the smart card present in the reader.
	SmartCardReader	getSmartCardReader() Returns the associated SmartCardReader.
	SmartCard[]	getSmartCards() Returns the SmartCard drivers that are able to communicate with the smart card present in the reader.
	boolean	isOpen() Returns true if the session is open, otherwise false.
	protected abstract void	negotiateProtocolImpl(SmartCardCapabilities cardCapabilities) Attempts to negotate a new protocol with the smartcard if desired.
	void	sendAPDU(CommandAPDU commandAPDU, ResponseAPDU responseAPDU) Transmits an APDU to the reader and blocks waiting for a response.
	protected abstract void	sendAPDUImpl(CommandAPDU commandAPDU, ResponseAPDU responseAPDU) Transmits an APDU to the reader and blocks waiting for a response.

Methods inherited from class java.lang.Object

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

Constructor Detail

SmartCardReaderSession

protected SmartCardReaderSession(SmartCardReader reader)

Construct a new SmartCardReaderSession.

Parameters:

reader - The associated SmartCardReader.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

Method Detail

close

public final void close()

Closes this session, and unblocks a pending session.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

closeImpl

protected abstract void closeImpl()

Closes this session.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

isOpen

public final boolean isOpen()

Returns true if the session is open, otherwise false.

Returns:

A boolean that determines if the session is currently open.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

sendAPDU

public final void sendAPDU(CommandAPDU commandAPDU,
                           ResponseAPDU responseAPDU)
                    throws SmartCardException

Transmits an APDU to the reader and blocks waiting for a response.

Parameters:

commandAPDU - The CommandAPDU to send.

responseAPDU - The ResponseAPDU received back from the reader.

Throws:

SmartCardException - Thrown if an error occurs while reading the smart card.

SmartCardSessionClosedException - Thrown if the reader session is already closed.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

sendAPDUImpl

protected abstract void sendAPDUImpl(CommandAPDU commandAPDU,
                                     ResponseAPDU responseAPDU)
                              throws SmartCardException

Transmits an APDU to the reader and blocks waiting for a response.

Parameters:

commandAPDU - The commandAPDU to send.

responseAPDU - The responseAPDU to send.

Throws:

SmartCardException - Thrown if an error occurs while reading the smart card.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

negotiateProtocolImpl

protected abstract void negotiateProtocolImpl(SmartCardCapabilities cardCapabilities)
                                       throws SmartCardException

Attempts to negotate a new protocol with the smartcard if desired. The reader and the smartcard should negotiate the best protocol that both support.

Parameters:

cardCapabilities - The SmartCardCapabilities the capabilities of the card.

Throws:

SmartCardException - Thrown if an error occurs with the smart card.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

getSmartCard

public final SmartCard getSmartCard()
                             throws SmartCardException

Returns the SmartCard driver that is able to communicate with the smart card present in the reader.

The driver returned is the first smart card driver which indicates that is capable of communicating with the card.

The user may be prompted to insert their smartcard.

Returns:

A SmartCard that is currently present in the reader.

Throws:

SmartCardException - Thrown if an error occurs while reading the smart card.

SmartCardSessionClosedException - Thrown if this reader session is closed.

See Also:

getSmartCards

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

getSmartCards

public final SmartCard[] getSmartCards()
                                throws SmartCardException

Returns the SmartCard drivers that are able to communicate with the smart card present in the reader.

The user may be prompted to insert their smartcard.

Returns:

The SmartCard drivers that are able to communicate with the card that is currently present in the reader.

Throws:

SmartCardException - Thrown if an error occurs while reading the smart card.

SmartCardSessionClosedException - Thrown if this reader session is closed.

See Also:

getSmartCard

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 5.0.0

getSmartCardReader

public final SmartCardReader getSmartCardReader()

Returns the associated SmartCardReader.

Returns:

A SmartCardReader.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

getAnswerToReset

public final AnswerToReset getAnswerToReset()
                                     throws SmartCardException

Returns the AnswerToReset provided by the physical smartcard present in the reader. The user may be prompted to insert their smartcard.

Returns:

The AnswerToReset provided by smart card in the reader.

Throws:

SmartCardException - Thrown if an error occurs while reading the smart card.

SmartCardSessionClosedException - Thrown if this reader session is closed.

SmartCardNoCardPresentException - Thrown if no card is currently present in the reader.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0

getAnswerToResetImpl

protected abstract AnswerToReset getAnswerToResetImpl()
                                               throws SmartCardException

Returns the AnswerToReset provided by the physical smartcard present in the reader. Implementations should not bring up UI.

Returns:

The AnswerToReset provided by the smart card in the reader.

Throws:

SmartCardException - Thrown if an error occurs while reading the smart card.

SmartCardNoCardPresentException - Thrown if no card is currently present in the reader.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.1.0