SmartCardSession (BlackBerry JDE 7.1.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.smartcard
Class SmartCardSession

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

Direct Known Subclasses:: CryptoSmartCardSession

public abstract class SmartCardSession
extends Object
extends Object

A SmartCardSession represents a communications session with a physical smartcard. Over this session, APDUs may be exchanged with the smartcard to provide the desired functionality. Subclasses may provide additional functions.

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:: SmartCardReaderSession
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

Field Summary
	`static int`	`DECRYPT_OPERATION` Indicates that this session will be used for a decryption operation.
	`static int`	`FINGERPRINT_CONTEXT_AUTHENTICATION` The fingerprints are being requested for use with authentication to the BlackBerry or an application.
	`static byte`	`INS_APPEND_RECORD` Append Record INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_ENVELOPE` Envelope INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_ERASE_BINARY` Erase Binary INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_EXTERNAL_AUTHENTICATE` External Authenticate INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_GET_CHALLENGE` Get Challenge INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_GET_DATA` Get Data INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_GET_RESPONSE` Get Response INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_INTERNAL_AUTHENTICATE` Internal Authenticate INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_MANAGE_CHANNEL` Manage Channel INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_PUT_DATA` Put Data INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_READ_BINARY` Read Binary INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_READ_RECORD` Read Record INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_SELECT_FILE` Select File INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_UPDATE_BINARY` Update Binary INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_UPDATE_RECORD` Update Record INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_VERIFY` Verify INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_WRITE_BINARY` Write Binary INS code as defined by ISO/IEC 7816-4.
	`static byte`	`INS_WRITE_RECORD` Write Record INS code as defined by ISO/IEC 7816-4.
	`static int`	`KEY_GENERATION_OPERATION` Indicates that this session will be used for a user key generation operation.
	`static int`	`NON_CRYPTO_OPERATION` Indicates that this session will be used for a non-cryptographic operation, for example, importing the certificates off the smartcard.
	`static int`	`SIGN_OPERATION` Indicates that this session will be used for a signing operation.
	`static int`	`UNKNOWN_OPERATION` Indicates that this session will be used for a unknown operation.
	`static int`	`USER_AUTHENTICATION_OPERATION` Indicates that this session will be used for a user authentication operation.

Constructor Summary
	`protected`	`SmartCardSession(SmartCard smartCard, SmartCardReaderSession readerSession)` Creates a new `SmartCardSession`.

Method Summary
	`void`	`close()` Closes the session, and the underlying `SmartCardReaderSession`.
	`protected abstract void`	`closeImpl()` Closes the session with the smartcard.
	`FingerprintBiometricData[]`	`getFingerprints(int context)` Retrieve sampled fingerprint data from the smart card.
	`protected FingerprintBiometricData[]`	`getFingerprintsImpl(int context)` Provide sampled fingerprint data from the smart card.
	`int`	`getMaxLoginAttempts()` Returns the maximum number of login attempts allowed, or Integer.MAX_VALUE if an infinite number of attempts are allowed.
	`protected abstract int`	`getMaxLoginAttemptsImpl()` Returns the maximum number of login attempts allowed, or Integer.MAX_VALUE if an infinite number of attempts are allowed.
	`int`	`getRemainingLoginAttempts()` Returns the remaining number of login attempts allowed before the smartcard will lock, or Integer.MAX_VALUE if the smartcard will not lock.
	`protected abstract int`	`getRemainingLoginAttemptsImpl()` Returns the remaining number of login attempts allowed before the smartcard will lock, or Integer.MAX_VALUE if the smart card will not lock.
	`SmartCard`	`getSmartCard()` Returns the associated `SmartCard`.
	`SmartCardID`	`getSmartCardID()` Get a `SmartCardID` associated with the specific smart card which this session is using.
	`protected abstract SmartCardID`	`getSmartCardIDImpl()` Get a `SmartCardID` associated with the specific smart card which this session is using.
	`SmartCardReaderSession`	`getSmartCardReaderSession()` Returns the underlying `SmartCardReaderSession`.
	`boolean`	`isLoggedIn()` Returns true if the session is open and user is logged into the smartcard, otherwise false.
	`boolean`	`isOpen()` Returns true if the session is open, otherwise false.
	`boolean`	`login(String password, int operation)` Attempts to log the user into the smartcard with the given password.
	`protected abstract boolean`	`loginImpl(String password)` Attempts to log the user into the smartcard with the given password.
	`void`	`loginPrompt(String accessReason, int operation)` Prompts the user for their password, and attempts to log the user into the smartcard.
	`protected void`	`sendAPDU(CommandAPDU commandAPDU, ResponseAPDU responseAPDU)` Transmits an APDU to the smartcard, and blocks until a response is received.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

INS_ERASE_BINARY

public static final byte INS_ERASE_BINARY

Erase Binary INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_VERIFY

public static final byte INS_VERIFY

Verify INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_MANAGE_CHANNEL

public static final byte INS_MANAGE_CHANNEL

Manage Channel INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_EXTERNAL_AUTHENTICATE

public static final byte INS_EXTERNAL_AUTHENTICATE

External Authenticate INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_GET_CHALLENGE

public static final byte INS_GET_CHALLENGE

Get Challenge INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_INTERNAL_AUTHENTICATE

public static final byte INS_INTERNAL_AUTHENTICATE

Internal Authenticate INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_SELECT_FILE

public static final byte INS_SELECT_FILE

Select File INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_READ_BINARY

public static final byte INS_READ_BINARY

Read Binary INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_READ_RECORD

public static final byte INS_READ_RECORD

Read Record INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_GET_RESPONSE

public static final byte INS_GET_RESPONSE

Get Response INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_ENVELOPE

public static final byte INS_ENVELOPE

Envelope INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_GET_DATA

public static final byte INS_GET_DATA

Get Data INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_WRITE_BINARY

public static final byte INS_WRITE_BINARY

Write Binary INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_WRITE_RECORD

public static final byte INS_WRITE_RECORD

Write Record INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_UPDATE_BINARY

public static final byte INS_UPDATE_BINARY

Update Binary INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_PUT_DATA

public static final byte INS_PUT_DATA

Put Data INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_UPDATE_RECORD

public static final byte INS_UPDATE_RECORD

Update Record INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

INS_APPEND_RECORD

public static final byte INS_APPEND_RECORD

Append Record INS code as defined by ISO/IEC 7816-4.

See Also:: Constant Field Values
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.2.0, 4.1.1

FINGERPRINT_CONTEXT_AUTHENTICATION

public static final int FINGERPRINT_CONTEXT_AUTHENTICATION

The fingerprints are being requested for use with authentication to the BlackBerry or an application.

See Also:: SmartCardSession.getFingerprints(int), Constant Field Values
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

UNKNOWN_OPERATION

public static final int UNKNOWN_OPERATION

Indicates that this session will be used for a unknown operation.

See Also:: Constant Field Values
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

NON_CRYPTO_OPERATION

public static final int NON_CRYPTO_OPERATION

Indicates that this session will be used for a non-cryptographic operation, for example, importing the certificates off the smartcard.

See Also:: Constant Field Values
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

SIGN_OPERATION

public static final int SIGN_OPERATION

Indicates that this session will be used for a signing operation.

See Also:: Constant Field Values
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

DECRYPT_OPERATION

public static final int DECRYPT_OPERATION

Indicates that this session will be used for a decryption operation.

See Also:: Constant Field Values
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

USER_AUTHENTICATION_OPERATION

public static final int USER_AUTHENTICATION_OPERATION

Indicates that this session will be used for a user authentication operation.

See Also:: Constant Field Values
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

KEY_GENERATION_OPERATION

public static final int KEY_GENERATION_OPERATION

Indicates that this session will be used for a user key generation operation.

See Also:: Constant Field Values
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 Detail

SmartCardSession

protected SmartCardSession(SmartCard smartCard,
                           SmartCardReaderSession readerSession)

Creates a new SmartCardSession.

Parameters:: smartCard - The SmartCard object associated with this session.; readerSession - The underlying reader 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

Method Detail

close

public final void close()

Closes the session, and the underlying SmartCardReaderSession. Sessions should be closed promptly when no longer needed.

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 the session with the smartcard. Implementations should not close the underlying SmartCardReaderSession.

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

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

Transmits an APDU to the smartcard, and blocks until a response is received.

Parameters:: commandAPDU - The commandAPDU to send. Must be non null.; responseAPDU - The responseAPDU received back from the reader. Must be non null.
Throws:: SmartCardException - Thrown if an error occurs with the smart card.; SmartCardSessionClosedException - if this SmartCardSession is 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

getMaxLoginAttempts

public final int getMaxLoginAttempts()
                              throws SmartCardException

Returns the maximum number of login attempts allowed, or Integer.MAX_VALUE if an infinite number of attempts are allowed.

Returns:: An integer representing the maximum number of login attempts.
Throws:: SmartCardException - Thrown if an error occurs with the smart card.; SmartCardUnsupportedOperationException - Thrown in the card does not support returning the maximum number of attempts
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

getMaxLoginAttemptsImpl

protected abstract int getMaxLoginAttemptsImpl()
                                        throws SmartCardException

Returns the maximum number of login attempts allowed, or Integer.MAX_VALUE if an infinite number of attempts are allowed.

Implementation should not bring up UI.

Returns:: An integer representing the maximum number of login attempts.
Throws:: SmartCardException - Thrown if an error occurs with the smart card.; SmartCardUnsupportedOperationException - Thrown in the card does not support returning the maximum number of attempts
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

getRemainingLoginAttempts

public final int getRemainingLoginAttempts()
                                    throws SmartCardException

Returns the remaining number of login attempts allowed before the smartcard will lock, or Integer.MAX_VALUE if the smartcard will not lock.

Returns:: An integer representing the remaining number of login attempts.
Throws:: SmartCardException - Thrown if an error occurs with the smart card.; SmartCardUnsupportedOperationException - Thrown in the card does not support returning the remaining login attempts
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

getRemainingLoginAttemptsImpl

protected abstract int getRemainingLoginAttemptsImpl()
                                              throws SmartCardException

Returns the remaining number of login attempts allowed before the smartcard will lock, or Integer.MAX_VALUE if the smart card will not lock. Implementation should not bring up UI.

Returns:: An integer representing the remaining number of login attempts.
Throws:: SmartCardException - Thrown if an error occurs with the smart card.; SmartCardUnsupportedOperationException - Thrown in the card does not support returning the remaining login attempts
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

isLoggedIn

public final boolean isLoggedIn()

Returns true if the session is open and user is logged into the smartcard, otherwise false.

Returns:: A boolean that determines whether or not the user is logged in.
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

login

public final boolean login(String password,
                           int operation)
                    throws SmartCardException

Attempts to log the user into the smartcard with the given password.

Parameters:: password - The password used to login to the smart card.; operation - One of the possible *_OPERATION values.
Returns:: true if the user was successfully logged in, false otherwise.
Throws:: SmartCardException - Thrown if an error occurs while reading the smart card.; SmartCardSessionClosedException - Thrown if this session is 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

loginImpl

protected abstract boolean loginImpl(String password)
                              throws SmartCardException

Attempts to log the user into the smartcard with the given password. Implementation should not bring up UI.

Parameters:: password - The password attempt. The password will always be non-null.
Returns:: true if the user was successfully logged, or false otherwise.
Throws:: SmartCardException - Thrown if an error occurs while reading the smart card.; SmartCardLockedException - Thrown if the card becomes locked because the password was incorrect.
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

loginPrompt

public final void loginPrompt(String accessReason,
                              int operation)
                       throws SmartCardException

Prompts the user for their password, and attempts to log the user into the smartcard. On the last login before the card is locked, a dialog is displayed indicating to the user that this is their last login attempt.

This method will loop until one of the following occurs:

the user successfully logs into the smartcard.
the user cancels the operation, and a SmartCardCancelException is thrown.
the smartcard becomes locked after the maximum number of login attempts is reached, and a SmartCardLockedException is thrown.

Parameters:: accessReason - The reason for logging into the card. The reason is displayed to the user when prompting for the PIN. May be null.; operation - One of the possible *_OPERATION values.
Throws:: SmartCardException - Thrown if an error occurs while reading the smart card.; SmartCardLockedException - Thrown if the card becomes locked because of incorrect passwords being entered; SmartCardSessionClosedException - Thrown if this session is closed.; SmartCardCancelException - Thrown if the user cancels the login.
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()

Returns the associated SmartCard.

Returns:: The SmartCard.
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

getSmartCardReaderSession

public final SmartCardReaderSession getSmartCardReaderSession()

Returns the underlying SmartCardReaderSession.

Returns:: The associated reader 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

getSmartCardID

public final SmartCardID getSmartCardID()
                                 throws SmartCardException

Get a SmartCardID associated with the specific smart card which this session is using.

Returns:: A SmartCardID object associated with the specific smart card which this session is using.
Throws:: SmartCardException - Thrown if an error occurs with the smart card.; SmartCardUnsupportedOperationException - Thrown if the smartcard does not support retrieving a unique identifier.; SmartCardSessionClosedException - Thrown if this session is 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

getSmartCardIDImpl

protected abstract SmartCardID getSmartCardIDImpl()
                                           throws SmartCardException

Get a SmartCardID associated with the specific smart card which this session is using. The implementation should not bring up any UI. The information on the smartcard used to create the SmartCardID should be available while the user is not logged in to the card.

Returns:: A SmartCardID object associated with the specific smart card which this session is using, or null if the identifier cannot be retrieved..
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

getFingerprints

public final FingerprintBiometricData[] getFingerprints(int context)
                                                 throws SmartCardException

Retrieve sampled fingerprint data from the smart card.

Parameters:: context - the context/reason the fingerprints are being requested. Currently only FINGERPRINT_CONTEXT_AUTHENTICATION is used.
Returns:: Fingerprint sample data stored on the smart card, or null, if no fingerprints are present on the card.
Throws:: SmartCardException - if an error occurs when communicating with the smart card.; SmartCardUnsupportedOperationException - if the smart card driver does not suport the extraction of fingerprints from the card.
See Also:: SmartCardSession.getFingerprintsImpl(int)
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

getFingerprintsImpl

protected FingerprintBiometricData[] getFingerprintsImpl(int context)
                                                  throws SmartCardException

Provide sampled fingerprint data from the smart card.

Implementors should extend this method to provide support for extracting fingerprint sample data from a smart card.

Parameters:: context - the context/reason the fingerprints are being requested. Currently only FINGERPRINT_CONTEXT_AUTHENTICATION is used.
Returns:: Throws an unsupported operation exception by default; supporting implementations should return the fingerprint sample data stored on the smart card, or null, if the card has no stored fingerprint sample data.
Throws:: SmartCardException - if an error occurs when communicating with the smart card.; SmartCardUnsupportedOperationException - if the smart card driver does not support the extraction of fingerprints from the card.
See Also:: SmartCardSession.getFingerprints(int)
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