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 for dealing with SmartCard objects.

See Also:

SmartCardReaderFactory

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 Summary
	static boolean	addSmartCard(SmartCard newCard) Register a smart card driver with the smart card and user authenticator frameworks.
	static boolean	addSmartCard(SmartCard newCard, boolean addSmartCardUserAuthenticator) Register a smart card driver with the smart card framework.
	static SmartCard	chooseSmartCard() Prompt the user to select an attached smart card reader.
	static int	getNumSmartCards() Retrieve the number of registered smart card drivers.
	static SmartCard	getSmartCard(AnswerToReset atr) Retrieve registered smart card driver that supports provided answer-to-reset code.
	static SmartCardSession	getSmartCardSession(AnswerToReset atr) Request an open session with a smart card possessing provided answer-to-reset code.
	static SmartCardSession	getSmartCardSession(SmartCard card) Request an open session with a smart card.
	static SmartCardSession	getSmartCardSession(SmartCardID smartCardID) Request an open session with a smart card, identified by provided smart card ID.
	static SmartCard[]	getSmartCards() Retrieve the list of registered smart card drivers.
	static SmartCard[]	getSmartCards(AnswerToReset atr) Retrieve registered smart card drivers that support the provided answer-to-reset code.

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)

Register a smart card driver with the smart card and user authenticator frameworks.

Before you can use a smart card driver within the smart card framework, you must register it. This method also registers the smart card driver with the user authentication framework.

Note: This method is a wrapper for addSmartCard(newCard, true).

Parameters:

newCard - Smart card driver to register.

Returns:

True if the card was added and registered with both frameworks; false if the smart card has already been registered.

Throws:

ControlledAccessException - If the provided card is registered with the smart card framework but could not be registered with the user authentication framework (because of restricted permissions).

IllegalArgumentException - If the newCard parameter is null or represents a non-persistable 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

addSmartCard

public static boolean addSmartCard(SmartCard newCard,
                                   boolean addSmartCardUserAuthenticator)

Register a smart card driver with the smart card framework.

Before you can use a smart card driver within the smart card framework, you must register it.

Providing the driver to the user authenticator framework

If the invoker provides true for this method's second parameter, this method will register the smart card driver as a user authenticator with the user authenticator framework. Driver implementors may choose to provide false for this method, if they wish to provide a separate user authenticator for additional user-authentication functionality.

Parameters:

newCard - Smart card driver to register.

addSmartCardUserAuthenticator - True if this method should register the smart card driver with the user authenticator framework; otherwise, false.

Returns:

True if the card was added and registered; false if the smart card has already been registered.

Throws:

ControlledAccessException - If the provided card is registered with the smart card framework but could not be registered with the user authentication framework (because of restricted permissions).

IllegalArgumentException - If the newCard parameter is null or represents a non-persistable smart card.

See Also:

net.rim.device.api.userauthenticator

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

chooseSmartCard

public static SmartCard chooseSmartCard()
                                 throws SmartCardException

Prompt the user to select an attached smart card reader.

If the device is not attached to a reader, this method first prompts the user to attach a reader. If the device is attached to more than one reader, this method prompts the user to choose one of the readers.

Note: this method blocks while the selected reader has a currently open session.

Returns:

A smart card driver for interacting with the smart card in the attached reader.

Throws:

SmartCardException - If an error occurs while reading the smart card.

SmartCardCancelException - If the user cancels when asked to insert their smart card.

SmartCardNoReaderPresentException - If no readers are registered.

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

getSmartCardSession

public static SmartCardSession getSmartCardSession(SmartCard card)
                                            throws SmartCardException

Request an open session with a smart card.

This method may prompt the user to attach the reader or insert the smart card, in order to retrieve an open session.

Parameters:

card - Card driver to use for opening session to card.

Returns:

Open session with card.

Throws:

SmartCardException - If an error occurs while reading from the smart card.

SmartCardCancelException - If the user cancels when asked to insert their smart card or reader.

SmartCardNoReaderPresentException - If there are no readers registered in which to establish a connection.

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

getSmartCardSession

public static SmartCardSession getSmartCardSession(AnswerToReset atr)
                                            throws SmartCardException

Request an open session with a smart card possessing provided answer-to-reset code.

This method may prompt the user to attach the reader or insert the smart card, in order to retrieve an open session.

Parameters:

atr - Answer-to-reset code used to identify the smart card for the session.

Returns:

Open session with card possessing the provided answer-to-reset code.

Throws:

SmartCardException - If an error occurs while reading the smart card.

SmartCardCancelException - If the user cancels when asked to insert their smart card or reader.

SmartCardNoCardPresentException - If no registered smart card supports the answer-to-reset code.

SmartCardNoReaderPresentException - If there are no registered smart card readers present.

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

getSmartCardSession

public static SmartCardSession getSmartCardSession(SmartCardID smartCardID)
                                            throws SmartCardException

Request an open session with a smart card, identified by provided smart card ID.

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

Parameters:

smartCardID - ID that identifies the smart card for the session.

Returns:

Open session with card.

Throws:

SmartCardException - If an error occurs while reading the smart card.

SmartCardCancelException - If the user cancels when asked to insert their smart card or reader.

SmartCardNoReaderPresentException - If there are no registered smart card readers present.

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 static SmartCard getSmartCard(AnswerToReset atr)

Retrieve registered smart card driver that supports provided answer-to-reset code.

This method searches the list of registered smart cards drivers, and returns the first implementation that indicates it can communicate with a physical smart card possessing the given answer-to-reset code.

Parameters:

atr - Answer-to-reset code to identify the smart card for the open session.

Returns:

Smart card driver that supports cards with the provided answer-to-reset code; null, if no such smart card driver is yet registered.

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 static SmartCard[] getSmartCards(AnswerToReset atr)

Retrieve registered smart card drivers that support the provided answer-to-reset code.

This method searches the list of registered smart cards drivers, and returns all of the smart cards that indicate that they can communicate with a physical smart card possessing the given answer-to-reset code.

Parameters:

atr - Answer-to-reset code to identify the smart card for the open session.

Returns:

The smart card drivers that support cards with the provided answer-to-reset code; null, if no such smart card drivers are yet registered.

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

getSmartCards

public static SmartCard[] getSmartCards()

Retrieve the list of registered smart card drivers.

Returns:

Array of registered smart card drivers; if no drivers registered, the returned array will be empty.

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

getNumSmartCards

public static int getNumSmartCards()

Retrieve the number of registered smart card drivers.

Returns:

Number of smart card drivers currently registered.

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