MozIccManager

This article is in need of a technical review.

Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

This API is available on Firefox OS for certified applications only.

The MozIccManager interface gives access to ICC related functionalities.

ICC related functionalities are known as the SIM Application Toolkit (STK) and are a set of applications built in to the SIM card. It provide basic functionalities for any phone (SMS, Contact, Tone ring change, etc.) In many cases, SmartPhones prefer to provide visual apps to access the same set of functionalities.

Interface overview

callback EventHandler = any (Event event);

interface MozIccManager : EventTarget
{
  DOMRequest iccCloseChannel(long channel);
  DOMRequest iccExchangeAPDU(long channel, object apdu);
  DOMRequest iccOpenChannel(DOMString aid);
  void sendStkEventDownload(object event);
  void sendStkMenuSelection(unsigned short itemIdentifier, boolean helpRequested);
  void sendStkResponse(object command, object respond);
  void sendStkTimerExpiration(in jsval timer);
  DOMRequest updateContact(DOMString contactType, Contact contact, optional DOMString pin2);
  DOMRequest getCardLock(DOMString lockType);
  DOMRequest unlockCardLock(object info);
  DOMRequest setCardLock(object info);

  readonly attribute DOMString cardState;
  readonly attribute MozMobileICCInfo iccInfo;

  attribute EventHandler oncardstatechange;
  attribute EventHandler oniccinfochange;
  attribute EventHandler onstkcommand;
  attribute EventHandler onstksessionend;
};

Note: MozIccManager defines many constants that are detailed hereafter but not present in this overview for clarity.

Properties

 
MozIccManager.cardState Read only
A string that indicates the state of the device's ICC card.
MozIccManager.iccInfo Read only
A MozMobileICCInfo object that gives access to information stored in the device's ICC card.
MozIccManager.oncardstatechange
A handler for the cardstatechange event. This event is fired when the cardState property changes value.
MozIccManager.oniccinfochange
A handler for the iccinfochange event. This event is fired whenever the iccInfo object changes.
MozIccManager.onstkcommand Read only
A handler for the stkcommand event. This event is notified whenever STK Proactive Command is issued from ICC.
MozIccManager.onstksessionend Read only
A handler for the stksessionend event. This event is notified whenever STK Session is terminated by ICC.

Constants

The MozIccManager defines many constants in order to provide an easy way to manage information from the STK. That information is provided as numbers so it's more convenient to have human readable constants to deal with them.

STK Menu Presentation types

  • STK_MENU_TYPE_NOT_SPECIFIED
  • STK_MENU_TYPE_DATA_VALUES
  • STK_MENU_TYPE_NAVIGATION_OPTIONS

Browser launch mode

  • STK_BROWSER_MODE_LAUNCH_IF_NOT_ALREADY_LAUNCHED
  • STK_BROWSER_MODE_USING_EXISTING_BROWSER
  • STK_BROWSER_MODE_USING_NEW_BROWSER

STK Proactive commands

  • STK_CMD_REFRESH
  • STK_CMD_POLL_INTERVAL
  • STK_CMD_POLL_OFF
  • STK_CMD_SET_UP_EVENT_LIST
  • STK_CMD_SET_UP_CALL
  • STK_CMD_SEND_SS
  • STK_CMD_SEND_USSD
  • STK_CMD_SEND_SMS
  • STK_CMD_SEND_DTMF
  • STK_CMD_LAUNCH_BROWSER
  • STK_CMD_PLAY_TONE
  • STK_CMD_DISPLAY_TEXT
  • STK_CMD_GET_INKEY
  • STK_CMD_GET_INPUT
  • STK_CMD_SELECT_ITEM
  • STK_CMD_SET_UP_MENU
  • STK_CMD_PROVIDE_LOCAL_INFO
  • STK_CMD_TIMER_MANAGEMENT
  • STK_CMD_SET_UP_IDLE_MODE_TEXT

STK Result code

The following results indicate that the command has been performed.

  • STK_RESULT_OK (Command performed successfully)
  • STK_RESULT_PRFRMD_WITH_PARTIAL_COMPREHENSION (Command performed with partial comprehension)
  • STK_RESULT_PRFRMD_WITH_MISSING_INFO (Command performed, with missing information)
  • STK_RESULT_PRFRMD_WITH_ADDITIONAL_EFS_READ (REFRESH performed with additional EFs read)
  • STK_RESULT_PRFRMD_LIMITED_SERVICE (Command performed successfully, limited service)
  • STK_RESULT_UICC_SESSION_TERM_BY_USER (Proactive UICC session terminated by the user)
  • STK_RESULT_BACKWARD_MOVE_BY_USER (Backward move in the proactive UICC session requested by the user)
  • STK_RESULT_NO_RESPONSE_FROM_USER (No response from user)
  • STK_RESULT_HELP_INFO_REQUIRED (Help information required by the user)
  • STK_RESULT_USSD_SS_SESSION_TERM_BY_USER (USSD or SS transaction terminated by the user)

The following results indicate to the UICC that it may be worth re-trying the command at a later opportunity.

  • STK_RESULT_TERMINAL_CRNTLY_UNABLE_TO_PROCESS (Terminal currently unable to process command)
  • STK_RESULT_NETWORK_CRNTLY_UNABLE_TO_PROCESS (Network currently unable to process command)
  • STK_RESULT_USER_NOT_ACCEPT (User did not accept the proactive command)
  • STK_RESULT_USER_CLEAR_DOWN_CALL (User cleared down call before connection or network release)
  • STK_RESULT_LAUNCH_BROWSER_ERROR (Launch browser generic error code)

The following results indicate that it is not worth the UICC re-trying with an identical command, as it will only get the same response. However, the decision to retry lies with the application.

  • STK_RESULT_BEYOND_TERMINAL_CAPABILITY (Command beyond terminal's capabilities)
  • STK_RESULT_CMD_TYPE_NOT_UNDERSTOOD (Command type not understood by terminal)
  • STK_RESULT_CMD_DATA_NOT_UNDERSTOOD (Command data not understood by terminal)
  • STK_RESULT_CMD_NUM_NOT_KNOWN (Command number not known by terminal)
  • STK_RESULT_SS_RETURN_ERROR (SS Return Error)
  • STK_RESULT_SMS_RP_ERROR (SMS RP-ERROR)
  • STK_RESULT_REQUIRED_VALUES_MISSING (Error, required values are missing)
  • STK_RESULT_USSD_RETURN_ERROR (USSD Return Error)
  • STK_RESULT_MULTI_CARDS_CMD_ERROR (MultipleCard commands error)

Interaction with call control by USIM or MO short message control by USIM, permanent problem

  • STK_RESULT_USIM_CALL_CONTROL_PERMANENT
  • STK_RESULT_BIP_ERROR (Bearer Independent Protocol error)

STK Event List

  • STK_EVENT_TYPE_MT_CALL
  • STK_EVENT_TYPE_CALL_CONNECTED
  • STK_EVENT_TYPE_CALL_DISCONNECTED
  • STK_EVENT_TYPE_LOCATION_STATUS
  • STK_EVENT_TYPE_USER_ACTIVITY
  • STK_EVENT_TYPE_IDLE_SCREEN_AVAILABLE
  • STK_EVENT_TYPE_CARD_READER_STATUS
  • STK_EVENT_TYPE_LANGUAGE_SELECTION
  • STK_EVENT_TYPE_BROWSER_TERMINATION
  • STK_EVENT_TYPE_DATA_AVAILABLE
  • STK_EVENT_TYPE_CHANNEL_STATUS
  • STK_EVENT_TYPE_SINGLE_ACCESS_TECHNOLOGY_CHANGED
  • STK_EVENT_TYPE_DISPLAY_PARAMETER_CHANGED
  • STK_EVENT_TYPE_LOCAL_CONNECTION
  • STK_EVENT_TYPE_NETWORK_SEARCH_MODE_CHANGED
  • STK_EVENT_TYPE_BROWSING_STATUS
  • STK_EVENT_TYPE_FRAMES_INFORMATION_CHANGED

The service state of STK Location Status

  • STK_SERVICE_STATE_NORMAL
  • STK_SERVICE_STATE_LIMITED
  • STK_SERVICE_STATE_UNAVAILABLE

Tone type

  • STK_TONE_TYPE_DIAL_TONE
  • STK_TONE_TYPE_CALLED_SUBSCRIBER_BUSY
  • STK_TONE_TYPE_CONGESTION
  • STK_TONE_TYPE_RADIO_PATH_ACK
  • STK_TONE_TYPE_RADIO_PATH_NOT_AVAILABLE
  • STK_TONE_TYPE_ERROR
  • STK_TONE_TYPE_CALL_WAITING_TONE
  • STK_TONE_TYPE_RINGING_TONE
  • STK_TONE_TYPE_GENERAL_BEEP
  • STK_TONE_TYPE_POSITIVE_ACK_TONE
  • STK_TONE_TYPE_NEGATIVE_ACK_TONE

Time unit

  • STK_TIME_UNIT_MINUTE
  • STK_TIME_UNIT_SECOND
  • STK_TIME_UNIT_TENTH_SECOND

Local Information list

  • STK_LOCAL_INFO_LOCATION_INFO
  • STK_LOCAL_INFO_IMEI
  • STK_LOCAL_INFO_DATE_TIME_ZONE
  • STK_LOCAL_INFO_LANGUAGE

Timer Management

  • STK_TIMER_START
  • STK_TIMER_DEACTIVATE
  • STK_TIMER_GET_CURRENT_VALUE

Methods

MozIccManager.sendStkResponse()
Send the response back to ICC after an attempt to execute STK Proactive Command.
MozIccManager.sendStkMenuSelection()
Send the "Menu Selection" Envelope command to ICC for menu selection.
MozIccManager.sendStkTimerExpiration()
Send the "Timer Expiration" Envelope command to ICC for TIMER MANAGEMENT.
MozIccManager.sendStkEventDownload()
Send "Event Download" Envelope command to ICC.
MozIccManager.updateContact()
Update ICC Phonebook contact.
MozIccManager.iccOpenChannel()
Send request to open a logical channel defined by its application identifier (AID).
MozIccManager.iccExchangeAPDU()
Interface used to communicate with an applet through the Application Data Protocol Units (APDUs).
MozIccManager.iccCloseChannel()
Send request to close the selected logical channel identified by its application identifier (AID).
MozIccManager.getCardLock()
Find out about the status of an ICC lock (e.g. the PIN lock).
MozIccManager.unlockCardLock()
Unlock a card lock.
MozIccManager.setCardLock()
Modify the state of a card lock.

The MozIccManager interface also inherits from the EventTarget interface.

EventTarget.addEventListener()
Register an event handler of a specific event type on the EventTarget.
EventTarget.removeEventListener()
Removes an event listener from the EventTarget.
EventTarget.dispatchEvent()
Dispatch an event to this EventTarget.

Specification

Not part of any specification.

See also

Document Tags and Contributors

Contributors to this page: Sheppy, mikehenrty, teoli, kscarfone, Jeremie
Last updated by: mikehenrty,