net.rim.device.api.smartcard
Class SmartCardReader

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.

To communicate with the reader, the developer must call openSession().

For information on implementing smart card readers, see Adding smart card reader drivers to the SmartCard API.
This tutorial describes the process of adding support for new smart card reader and smart card reader drivers to the API. A smart card reader consists of the
physical device and the software driver used to read the data from a smart card.

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.

SmartCardReader

protected SmartCardReader()

Constructs 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

Method Detail

openSession

The user may be prompted to attach the reader, if the reader could not be found.
For security reasons, only only one communication session is allowed to be open with a reader at one time.
Hence, this function will block until all other communication sessions using this reader have closed.

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.

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.

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.

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.

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.

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

isInsertionRemovalDetectable

public final boolean isInsertionRemovalDetectable()

Returns true if the reader can detect when a card is inserted in or removed
from the reader.

Some readers may recognize when a card is inserted or removed. If this functionality
is not supported by the reader, then this method must returns false.

Returns:

true if the reader can detect when a card is inserted or removed.

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

isInsertionRemovalDetectableImpl

protected abstract boolean isInsertionRemovalDetectableImpl()

Returns true if the reader can detect when a card is inserted in or removed
from the reader.

Some readers may recognize when a card is inserted or removed. If this functionality
is not supported by the reader, then this method must returns false.

Returns:

true if the reader can detect when a card is inserted or removed.

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.

getLabel

The String should not include the words "smart card reader", as this method will
be used to generate strings such as ( "Please insert your %s smart card
reader", getLabel() )

Returns:

A String representing the label of the smart card 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.

getLabelImpl

The String should not include the words "smart card reader", as this method will
be used to generate strings such as ( "Please insert your %s smart card
reader", getLabel() )

Returns:

A String representing the label of the smart card 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.

getType

A session does not need to be open to get a valid response from this method.

Returns:

A String representation of the type of 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.

getTypeImpl

A session does not need to be open to get a valid response from this method.

Returns:

A String representation of the type of 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.

addListener

Some readers may recognize when a card is inserted or removed. If this functionality
is not supported by the reader, then this method returns false.

If smart card insertions and removals are recognized, then when addListener is called,
listener.readerStatus() will be called directly with either ReaderStatus.CARD_PRESENT,
ReaderStatus.CARD_ABDSENT, or ReaderStatus.CARD_UNKNOWN if there was an exception.

When there is a change in the reader status, for example if the card is inserted or removed
listener.readerStatus() will be called with either ReaderStatus.CARD_INSERTED or
ReaderStatus.CARD_REMOVED.

Parameters:

listener - The listener to add.

Returns:

true if card insertions and removals are detectable and the listener was successfully added.
Returns false if card insertions and removals are not detectable.

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.

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

setReaderStatus

protected final void setReaderStatus(int readerStatus)

Called by the subclass implementation to notify all registered ReaderStatusListeners with the given status.
Note: all Throwable exceptions thrown by the listeners are ignored.

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

getReaderStatus

public final int getReaderStatus()

Returns the current reader status.

Returns:

An integer representing the reader status.

The state diagram represents the different possible paths to a return value.

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

displaySettings

Allows the driver to display some settings or properties.
This method will be invoked from the smart card options screen when
the user selects the driver and chooses to view the settings of that driver.
This method could be called from the event thread. The driver should not block
the event thread for long periods of time.

Parameters:

context - Reserved for future use.

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

displaySettingsImpl

Allows the driver to display some settings or properties.
This method will be invoked from the smart card options screen when
the user selects the driver and chooses to view the settings of that driver.
This method could be called from the event thread. The driver should not block
the event thread for long periods of time.

Parameters:

context - Reserved for future use.

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.

isDisplaySettingsAvailable

Allows the driver to indicate if they support displaying settings.
If this method returns true, then the method displaySettings maybe called
to show settings to the user.

Parameters:

context - Reserved for future use.

Returns:

true if the driver supports displaying settings, false otherwise.

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.

isDisplaySettingsAvailableImpl

Allows the driver to indicate if they support displaying settings.
If this method returns true, then the method displaySettings maybe called
to show settings to the user.

Parameters:

context - Reserved for future use.

Returns:

true if the driver supports displaying settings, false otherwise.

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

toString

Returns a string representation of the object. In general, the
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.

The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:

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.