SHOW Signed
 

net.rim.device.api.smartcard
Class SmartCardFactory

java.lang.Object
  |
  +--net.rim.device.api.smartcard.SmartCardFactory

public final class SmartCardFactory
extends Object

Provides factory functions in dealing with SmartCard objects.

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:
JDE 4.1.0
See Also:
SmartCard, SmartCardReaderFactory

Method Summary
 Category: Signed static boolean addSmartCard(SmartCard newCard)
          Adds the given smart card to the list of registered smart cards.
 Category: Signed static SmartCard chooseSmartCard()
          Prompts the user to select a smart card in an attached reader.
 Category: Signed static int getNumSmartCards()
          Returns the number of registered smart cards.
 Category: Signed static SmartCard getSmartCard(AnswerToReset atr)
          Searches the registered list of SmartCards and returns the first implementation that indicates that it can communicate with a physical smart card possessing the given AnswerToReset, otherwise null.
 Category: Signed static SmartCard[] getSmartCards()
          Returns the set of registered SmartCards.
 Category: Signed static SmartCardSession getSmartCardSession(AnswerToReset atr)
          Returns a smart card communication session given an AnswerToReset.
 Category: Signed static SmartCardSession getSmartCardSession(SmartCard card)
          Returns a smart card communication session given an SmartCard.
 Category: Signed static SmartCardSession getSmartCardSession(SmartCardID smartCardID)
          Returns a communication session given a SmartCardID.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

addSmartCard

public static boolean addSmartCard(SmartCard newCard)
Adds the given smart card to the list of registered smart cards. A smart card implementation must be registered before it can be used within the SmartCard API.

This method will also register the smart card driver with the user authentication framework. If a ControlledAccessException is thrown, the card was registered with the SmartCard API, but could not be registered with the authentication framework due to restricted permissions.

Parameters:
newCard - The smart card driver to add.
Returns:
true if the card was added and registered with the user authenticator and false if the smart card has already been registered.
Since:
JDE 4.1.0
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.

chooseSmartCard

public static SmartCard chooseSmartCard()
                                 throws SmartCardException
Prompts the user to select a smart card in an attached reader. If there are no readers attached to the device, then the user will be prompted to attach a reader. If there are multiple readers attached to the device, the user will be prompted to choose one of the readers.

Note: This call blocks while the selected reader has a currently open session.

Returns:
A SmartCard object that represents the physical smart card.
Throws:
SmartCardException - Thrown if an error occurs while reading the smart card.
SmartCardCancelException - Thrown is the user cancels when asked to insert their smart card.
SmartCardNoReaderPresentException - Thrown if no readers are registered.
Since:
JDE 4.1.0
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.

getNumSmartCards

public static int getNumSmartCards()
Returns the number of registered smart cards.

Returns:
The number of registered smart cards
Since:
JDE 4.1.0
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.

getSmartCard

public static SmartCard getSmartCard(AnswerToReset atr)
Searches the registered list of SmartCards and returns the first implementation that indicates that it can communicate with a physical smart card possessing the given AnswerToReset, otherwise null.
Parameters:
atr - The AnswerToReset with which to start a communication session.
Returns:
A SmartCard object that supports this AnswerToReset
Since:
JDE 4.1.0
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.

getSmartCards

public static SmartCard[] getSmartCards()
Returns the set of registered SmartCards.

Returns:
An array of smart cards. If no cards are registered an empty array gets returned.
Since:
JDE 4.1.0
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.

getSmartCardSession

public static SmartCardSession getSmartCardSession(AnswerToReset atr)
                                            throws SmartCardException
Returns a smart card communication session given an AnswerToReset.

This function may prompt the user to attach the reader or insert the smart card.

Parameters:
atr - The AnswerToReset with which to start a communication session.
Returns:
A smart card communication session.
Throws:
SmartCardException - Thrown if an error occurs while reading the smart card.
SmartCardNoCardPresentException - Thrown if none of the smart cards registed supports the atr
SmartCardCancelException - Thrown if the user cancels when asked to insert their smart card or reader
SmartCardNoReaderPresentException - Thrown if there are no readers registered in which to establish a connection.
Since:
JDE 4.1.0
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.

getSmartCardSession

public static SmartCardSession getSmartCardSession(SmartCard card)
                                            throws SmartCardException
Returns a smart card communication session given an SmartCard.

This function may prompt the user to attach the reader or insert the smart card.

Parameters:
card - The smart card with which to start a communication session.
Returns:
A communication session.
Throws:
SmartCardException - Thrown if an error occurs while reading from the smart card.
SmartCardCancelException - Thrown if the user cancels when asked to insert their smart card or reader
SmartCardNoReaderPresentException - Thrown if there are no readers registered in which to establish a connection.
Since:
JDE 4.1.0
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.

getSmartCardSession

public static SmartCardSession getSmartCardSession(SmartCardID smartCardID)
                                            throws SmartCardException
Returns a communication session given a SmartCardID.

This function may prompt the user to attach the reader or insert the specific smart card identified by the smart card ID.

Parameters:
smartCardID - The specific smart card in which to open up a session with
Returns:
A smart card communication session.
Throws:
SmartCardException - Thrown if an error occurs while reading the smart card.
SmartCardCancelException - Thrown if the user cancels when asked to insert their smart card or reader
SmartCardNoReaderPresentException - Thrown if there are no readers registered in which to establish a connection.
Since:
JDE 4.1.0
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.



Copyright 1999-2008 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.