net.rim.device.api.smartcard
Class SmartCardReaderSession

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.