com.motorola.oem.access
Class Access

java.lang.Object
  OEM
      com.motorola.oem.access.Access

public class Access
extends OEM

This class provides the ability to work with a SIM card. Access Class Restrictions:
Most of the Access class service methods are static and may be
used without creating an object.
Note: This class is implemented as a singleton and is accessible by the static method: getInstance().
The methods: (setSIMPin1LockUtility(int, java.lang.String), changeSIMPin1(java.lang.String, java.lang.String), unlockSIMPin1(java.lang.String),getMSISDN(),getGID1(),getGID2())
will block the thread until they get back a notification. Use them wisely. Calling these methods from a listener's implementation must be done on a separate thread.
Note: It is highly recommended to use this class functionality and not rely on exceptions of a non ready SIM card. If a SIM card is not ready(registered), the GSM/GPRS operations are impossible except for emergency ones.

Field Summary

static int	SIM_STATUS_BAD_CARD SIM card has some technical problem.
static int	SIM_STATUS_NO_CARD SIM card is not inserted.
static int	SIM_STATUS_PIN_BLOCKED SIM card is blocked due to 3-5 (SIM dependent) unsuccessful unlock attempts SIM PUK is required.
static int	SIM_STATUS_PIN_PERM_BLOCKED SIM card permanently blocked due to 10 (SIM dependent) unsuccessful unlock attempts
static int	SIM_STATUS_PIN_WAITING SIM card is waiting for a PIN code.
static int	SIM_STATUS_READY SIM card is ready to use.

Method Summary

void	changeSIMPin1(java.lang.String oldPIN, java.lang.String newPIN) Change PIN1 code.
java.lang.String	getCPHS() Returns the CPHS number stored in the SIM card.
java.lang.String	getGID1() Requests the GID1 number stored in the SIM card.
java.lang.String	getGID2() Requests the GID2 number stored in the SIM card.
java.lang.String	getICC_ID() Returns the ICC ID number stored in the SIM card.
java.lang.String	getICC_ID(java.lang.String pinCode) Returns the ICC ID number stored in the SIM card.
java.lang.String	getIMSI() Returns the IMSI number stored in the SIM card.
static Access	getInstance() Returns a reference to the class's single instance.
java.lang.String[]	getMSISDN() Requests up to 5 MSISDN numbers stored in the SIM card.
java.lang.String	getPreferredLanguageList() Returns preferred languages list stored in the SIM card.
java.lang.String	getPreferredLanguageList(java.lang.String pinCode) Returns preferred languages list stored in the SIM card.
boolean	getSIMPin1LockUtilityStatus() Returns SIM Pin1 Lock utility status (Enabled or Disabled).
int	getSIMStatus() Returns the SIM's status.
void	setSIMPin1LockUtility(int mode, java.lang.String pinCode) Enable/Disable SIM Pin1 Lock utility.
void	setSimStatusListener(AccessSIMStatusListener listener)
void	unlockSIMPin1(java.lang.String pinCode) Unlocks the SIM card for the current session (until the next power cycle) by supplying PIN1 code.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SIM_STATUS_READY

public static final int SIM_STATUS_READY

SIM card is ready to use.

See Also:

Constant Field Values

SIM_STATUS_PIN_WAITING

public static final int SIM_STATUS_PIN_WAITING

SIM card is waiting for a PIN code.

See Also:

Constant Field Values

SIM_STATUS_NO_CARD

public static final int SIM_STATUS_NO_CARD

SIM card is not inserted.

See Also:

Constant Field Values

SIM_STATUS_BAD_CARD

public static final int SIM_STATUS_BAD_CARD

SIM card has some technical problem.

See Also:

Constant Field Values

SIM_STATUS_PIN_BLOCKED

public static final int SIM_STATUS_PIN_BLOCKED

SIM card is blocked due to 3-5 (SIM dependent) unsuccessful unlock attempts SIM PUK is required.

See Also:

Constant Field Values

SIM_STATUS_PIN_PERM_BLOCKED

public static final int SIM_STATUS_PIN_PERM_BLOCKED

SIM card permanently blocked due to 10 (SIM dependent) unsuccessful unlock attempts

See Also:

Constant Field Values

Method Detail

getInstance

public static Access getInstance()
                          throws AccessException

Returns a reference to the class's single instance. If the instance does not exist, then one is created and its reference is returned.

Returns:

A reference to the Access instance

Throws:

AccessException - Failed to construct the Access object.

setSIMPin1LockUtility

public void setSIMPin1LockUtility(int mode,
                                  java.lang.String pinCode)
                           throws AccessException

Enable/Disable SIM Pin1 Lock utility. The change will take affect on the next Power Up.

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Parameters:

mode - 1 to enable SIM Pin lock, 0 to disable SIM Pin lock

pinCode - SIM Pin 1

Throws:

AccessException - Platform failure(error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Platform failure(error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - SIM PIN1 Invalid(error code AccessException.INVALID_PIN1_ERROR)

AccessException - Operation not allowed(error code AccessException.OPERATION_NOT_ALLOWED_ERROR)

AccessException - Invalid characters in text string(error code AccessException.PASSWORD_SYNTAX_ERROR)

AccessException - Service option not supported(error code AccessException.SERVICE_NOT_SUPPORTED_ERROR)

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - SIM not inserted(error code AccessException.NO_SIM_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

AccessException - Synchronization failure

getSIMPin1LockUtilityStatus

public boolean getSIMPin1LockUtilityStatus()
                                    throws AccessException

Returns SIM Pin1 Lock utility status (Enabled or Disabled). Reflects result of setSIMPin1LockUtility(int, java.lang.String) usage only after Power Cycle.

Returns:
Value true for Enabled, false for Disabled.

Throws:

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - SIM not inserted(error code AccessException.NO_SIM_ERROR)

unlockSIMPin1

public void unlockSIMPin1(java.lang.String pinCode)
                   throws AccessException

Unlocks the SIM card for the current session (until the next power cycle) by supplying PIN1 code.

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Parameters:

pinCode - PIN code.

Throws:

AccessException - Platform failure(error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Platform failure(error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - SIM PIN1 Invalid(error code AccessException.INVALID_PIN1_ERROR)

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - Memory operation failed(error code AccessException.MEMORY_FAIL_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - SIM not inserted(error code AccessException.NO_SIM_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

AccessException - Synchronization failure

See Also:

getSIMPin1LockUtilityStatus(), setSIMPin1LockUtility(int, java.lang.String)

getSIMStatus

public int getSIMStatus()
                 throws AccessException

Returns the SIM's status.

Returns:
one of the following:
  SIM_STATUS_READY,
  SIM_STATUS_PIN_WAITING,
  SIM_STATUS_NO_CARD,
  SIM_STATUS_BAD_CARD,
  SIM_STATUS_PIN_BLOCKED,
  SIM_STATUS_PIN_PERM_BLOCKED

Throws:

AccessException - Memory operation failed(error code AccessException.MEMORY_FAIL_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

changeSIMPin1

public void changeSIMPin1(java.lang.String oldPIN,
                          java.lang.String newPIN)
                   throws AccessException

Change PIN1 code. Operation is allowed only if Lock Utility is enabled(setSIMPin1LockUtility(int, java.lang.String)) and PIN1 is unlocked(unlockSIMPin1(java.lang.String)).

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Parameters:

oldPIN - in ascii digits.

newPIN - in ascii digits.

Throws:

AccessException - Platform failure(error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Platform failure(error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - SIM PIN1 Invalid(error code AccessException.INVALID_PIN1_ERROR)

AccessException - Invalid characters in text string(error code AccessException.PASSWORD_SYNTAX_ERROR)

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - SIM card busy(error code AccessException.SIM_BUSY_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

AccessException - SIM PIN1 is not active(error code AccessException.SIM_PIN1_IS_NOT_ACTIVE_ERROR)

AccessException - SIM PIN1 has no secret code(error code AccessException.SIM_PIN1_NO_SECRET_CODE_ERROR)

AccessException - Synchronization failure

getMSISDN

public java.lang.String[] getMSISDN()
                             throws AccessException

Requests up to 5 MSISDN numbers stored in the SIM card. In case MSISDN isn't supported, only current device phone number is returned in confirmation event.

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Returns:

String[] array of MSISDN phone numbers

Throws:

AccessException - Platform failure (error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Platform failure (error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - Phone Book read failure (error code AccessException.PHONEBOOK_READ_FAIL_ERROR)

AccessException - Synchronization failure

getIMSI

public java.lang.String getIMSI()
                         throws AccessException

Returns the IMSI number stored in the SIM card.

Returns:

IMSI number's string

Throws:

AccessException - SIM card is busy (Error code: AccessException.SIM_BUSY_ERROR)

getGID1

public java.lang.String getGID1()
                         throws AccessException

Requests the GID1 number stored in the SIM card.

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Returns:

GID1 string

Throws:

AccessException - Platform failure(error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Platform failure(error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - Synchronization failure

getGID2

public java.lang.String getGID2()
                         throws AccessException

Requests the GID2 number stored in the SIM card.

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Returns:

GID2 string

Throws:

AccessException - Platform failure(error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Platform failure(error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - Synchronization failure

getICC_ID

public java.lang.String getICC_ID()
                           throws AccessException

Returns the ICC ID number stored in the SIM card. This method should be used when SIM PIN1 lock utility is disabled.

Returns:

ICC ID number's string

Throws:

AccessException - ICC ID not available(error code AccessException.ICC_NOT_AVAIL_ERROR)

AccessException - SIM PIN1 required(error code AccessException.SIM_PIN1_REQUIRED_ERROR)

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - SIM not inserted(error code AccessException.NO_SIM_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

AccessException - Memory operation failed(error code AccessException.MEMORY_FAIL_ERROR)

See Also:

setSIMPin1LockUtility(int, java.lang.String), getSIMPin1LockUtilityStatus(), unlockSIMPin1(java.lang.String), getSIMStatus(), getICC_ID(String)

getICC_ID

public java.lang.String getICC_ID(java.lang.String pinCode)
                           throws AccessException

Returns the ICC ID number stored in the SIM card. This method should be used when SIM PIN1 lock utility is enabled.

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Parameters:

pinCode - SIM PIN1 code.

Returns:

ICC ID number's string

Throws:

AccessException - ICC ID not available(error code AccessException.ICC_NOT_AVAIL_ERROR)

AccessException - Unable to register platform confirmation event(error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Invalid platform acquire handler(error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - SIM PIN1 Invalid(error code AccessException.INVALID_PIN1_ERROR)

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - Memory operation failed(error code AccessException.MEMORY_FAIL_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - SIM not inserted(error code AccessException.NO_SIM_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

AccessException - Synchronization failure

See Also:

setSIMPin1LockUtility(int, java.lang.String), getSIMPin1LockUtilityStatus(), unlockSIMPin1(java.lang.String), getSIMStatus(), getICC_ID()

getCPHS

public java.lang.String getCPHS()
                         throws AccessException

Returns the CPHS number stored in the SIM card.

Returns:

CPHS number's string

Throws:

AccessException - CPHS not available(error code AccessException.CPHS_NOT_AVAIL_ERROR)

getPreferredLanguageList

public java.lang.String getPreferredLanguageList()
                                          throws AccessException

Returns preferred languages list stored in the SIM card. This method should be used when SIM PIN1 lock utility is disabled.

Returns:

Preffered languages list string

Throws:

AccessException - Preferred languages list not available (error code AccessException.LANG_NOT_AVAIL_ERROR)

AccessException - SIM PIN1 required(error code AccessException.SIM_PIN1_REQUIRED_ERROR)

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - SIM not inserted(error code AccessException.NO_SIM_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

AccessException - Memory operation failed(error code AccessException.MEMORY_FAIL_ERROR)

See Also:

setSIMPin1LockUtility(int, java.lang.String), getSIMPin1LockUtilityStatus(), unlockSIMPin1(java.lang.String), getSIMStatus(), getPreferredLanguageList(String)

getPreferredLanguageList

public java.lang.String getPreferredLanguageList(java.lang.String pinCode)
                                          throws AccessException

Returns preferred languages list stored in the SIM card. This method should be used when SIM PIN1 lock utility is enabled.

Important Note: This method will block the thread until it receives back a notification. If this method is called from inside a listener's implementation, it must be done in a separate thread.

Parameters:

pinCode - SIM PIN1 code.

Returns:

Preferred languages list string

Throws:

AccessException - Preferred languages list not available (error code AccessException.LANG_NOT_AVAIL_ERROR)

AccessException - Unable to register platform confirmation event(error code AccessException.UNABLE_REGISTER_CNF_EVENT_ERROR)

AccessException - Invalid platform acquire handler(error code AccessException.INVALID_ACQUIRE_HANLE_ERROR)

AccessException - SIM PIN1 Invalid(error code AccessException.INVALID_PIN1_ERROR)

AccessException - SIM PIN1 blocked(error code AccessException.PIN1_IS_BLOCKED_ERROR)

AccessException - SIM PIN1 permanently blocked(error code AccessException.PIN1_IS_PERM_BLOCKED_ERROR)

AccessException - Memory operation failed(error code AccessException.MEMORY_FAIL_ERROR)

AccessException - SIM failure(error code AccessException.SIM_FAIL_ERROR)

AccessException - SIM not inserted(error code AccessException.NO_SIM_ERROR)

AccessException - Phone failure(error code AccessException.PHONE_FAIL_ERROR)

AccessException - Synchronization failure

See Also:

setSIMPin1LockUtility(int, java.lang.String), getSIMPin1LockUtilityStatus(), unlockSIMPin1(java.lang.String), getSIMStatus(), getPreferredLanguageList()

setSimStatusListener

public void setSimStatusListener(AccessSIMStatusListener listener)