WebAPI/WebSTK

Overview

To provide DOM API for the STK(SIM Toolkit), or CAT (Card Application Toolkit), which allows web contents can interact with SIM applications.

Status

Bugzilla : https://bugzilla.mozilla.org/show_bug.cgi?id=791161
Feature List: https://docs.google.com/spreadsheet/ccc?key=0AuvgnQ-Iwb6XdGV0aHZWdGdmZVEzZUxmZWNEaGJYWkE

Interface

• These interface will be added in MozIccManager

Event handlers for receiving messages from ICC to ME

These event handlers will be invoked when there are proactive commands or session end notification sent from ICC.

Proactive Command

  /**
   * The 'stkcommand' event is notified whenever STK Proactive Command is
   * issued from ICC.
   */ 
  attribute nsIDOMEventListener onstkcommand;

Session End Notificaiton

  /**
   * 'stksessionend' event is notified whenever STK Session is terminated by 
   * ICC.
   */ 
  attribute nsIDOMEventListener onstksessionend;

Send Message from ME to ICC

There are two kinds of messages will be sent from ME to ICC

• Terminal Response
  • Once the ME has made its attempt to execute a proactive command from the ICC, the ME shall inform the ICC of the success or otherwise of that command, by using TERMINAL RESPONSE.
• Envelope command
  • Envelope command is used to transfer STK information from ME to ICC.

Send Terminal Response

  /**
   * Send the response back to ICC after an attempt to execute STK Proactive
   * Command.
   *
   * @param command
   *        Command received from ICC. See MozStkCommand.
   * @param response
   *        The response that will be sent to ICC.
   * @see MozStkResponse for the detail of response.
   */
  void sendStkResponse(in jsval command, in jsval response);

Send Envelope Command

Currently only support "Menu Selection", "Event Download"

  /**
   * Send the "Menu Selection" Envelope command to ICC for menu selection.
   *
   * @param itemIdentifier
   *        The identifier of the item selected by user.
   * @param helpRequested
   *        true if user requests to provide help information, false otherwise.
   */
  void sendStkMenuSelection(in unsigned short itemIdentifier,
                            in boolean        helpRequested);

  /**
   * Send "Event Download" Envelope command to ICC.
   * ICC will not respond with any data for this command.
   *
   * @param event
   *        one of events below:
   *        - MozStkLocationEvent
   *        - MozStkCallEvent
   */
  void sendStkEventDownload(in jsval event);

STK message format

• TS 102.223, Annex C for the structure of STK communications

The specification of the message received from ICC and sent to ICC.

Basically, a STK message is of a BER-TLV object, which contains several Comprehension-TLV objects (TLV : Tag-Length-Value)

                      ----- ----- ------------------------------------
            BER-TLV  |  T  |  L  |  V - Several Comprehension-TLVs    |
                      ----- ----- ------------------------------------
                                 /                                     \
                                /                                       \
                                ----- ----- -----       ----- ----- -----
Comprehension-TLV              |  T  |  L  |  V  | ... |  T  |  L  |  V  |
                                ----- ----- -----       ----- ----- -----

Each STK message consists of at least two mandatory Comprehension-TLVs

• Command Details
• Device Identities

The remaining Comprehension-TLVs varies according to different type of STK message.

For the "Command Details" data object,
this data object shall be identical to the command details data object (including the comprehension required flag) given by the UICC in the proactive command to which the terminal is giving the result.

And there two kinds of STK messages

• From ICC to ME
  • MozStkCommand
• From ME to ICC
  • MozStkResponse

In both MozStkCommand and MozStkResponse, we expose the content of 'Command Details' as:

• number
• type
• qualifier

So when a webapp tries to create a MozStkResponse, the webapp needs to create exactly the same 'Command Details' as it got from MozStkCommand.

From ICC to ME

The STK message sent from ICC to ME called 'Proactive Command'. And we use MozStkCommand to represent 'Proactive Command'.
For example, a Proactive Command SET_UP_MENU whose Comprehension-TLVs will be looked like

   ---------------- -------------- ------------- ----------       ----------
  | CmdDetails-TLV | DeviceId-TLV | AlphaId-TLV | Item-TLV | ... | Item-TLV |
   ---------------- -------------- ------------- ----------       ----------

• CmdDetails - Details of this proactive command.
  • typeOfCommand is SET_UP_MENU
• DeviceId - The source and destination of this proactive command.
• AlphaId - The title of this menu
• Item - The items in this menu

In designing this message format, we wrap up the Comprehension-TLVs other than "Command Details" and "Device Identities" to a more high level UI component according to the typeOfCommand.

   ---------------- -------------- --------------
  | CmdDetails-TLV | DeviceId-TLV | UI Component |
   ---------------- -------------- --------------

The UI componet includes

• Text Message
• Menu
• Input
• Call set up
• Launch Browser

So web apps can parse the UI componet according to the typeOfCommand.

In this case, web apps can display a Menu-like UI according to this UI component.

   --------
  | Title  |
   --------
  | Item 1 |
   --------
  | Item 2 |
   --------

STK Command Event

StkCommandEvent will be the parameter passed in onstkcommand handler

interface nsIDOMMozStkCommandEvent : nsIDOMEvent
{
  /**
   * See nsIDOMMozStkCommand for the detail of command.
   */
  readonly attribute jsval command;
};

STK command

dictionary nsIDOMMozStkCommand
{
  /**
   * The number of command issued by ICC. And it is assigned
   * by ICC may take any hexadecimal value betweean '01' and 'FE'.
   *
   * @see TS 11.14, clause 6.5.1
   */
  unsigned short commandNumber;

  /**
   * One of STK_CMD_*
   */
  unsigned short typeOfCommand;

  /**
   * Qualifiers specific to the command.
   */
  unsigned short commandQualifier;

  /**
   * options varies accrording to the typeOfCommand in nsIDOMMozStkCommand.
   *
   * When typeOfCommand is
   * - STK_DISPLAY_TEXT
   * - STK_SET_UP_IDLE_MODE_TEXT
   * - STK_REFRESH
   * - STK_SEND_{SS|USSD|SMS|DTMF},
   * options is nsIDOMMozStkTextMessage.
   *
   * When typeOfCommand is
   * - STK_SELECT_ITEM
   * - STK_SET_UP_MENU
   * options is nsIDOMMozStkMenu.
   *
   * When typeOfCommand is
   * - STK_GET_INKEY
   * - STK_GET_INPUT,
   * options is nsIDOMMozStkInput.
   *
   * When typeOfCommand is
   * - STK_LAUNCH_BROWSER
   * options is nsIDOMMozStkBrowserSetting.
   *
   * When typeOfCommand is
   * - STK_SET_UP_CALL
   * options is nsIDOMMozStkSetUpCall.
   */
  jsval options;
};

UI parts - The UI Component contained in MozStkCommand

Text Message

dictionary nsIDOMMozStkTextMessage
{
  /**
   * Text String.
   *
   * @see TS 11.14, clause 12.15, Text String.
   */
  DOMString text;

  /**
   * Indicate this text message is high priority or normal priority.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, Display Text, bit 1.
   *
   * High priority text shall be displayed on the screen immediately, except if
   * there is a conflict of priority level of alerting such as incoming calls
   * or a low battery warning. In that situation, the resolution is left to
   * the terminal. If the command is rejected in spite of the high priority,
   * the terminal shall inform the ICC with resultCode is
   * TERMINAL_CRNTLY_UNABLE_TO_PROCESS in MozStkResponse.
   *
   * true: high priority
   * false: normal priority
   */
  boolean isHighPriority;

  /**
   * Need to wait for user to clear message or not.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, Display Text, bit 8.
   *
   * If this attribute is true, but user doesn't give any input within a period
   * of time(said 30 secs), the terminal shall inform the ICC with resultCode
   * is NO_RESPONSE_FROM_USER in MozStkResponse.
   *
   * true: Wait for user to clear message.
   * false: clear message after a delay.
   */
  boolean userClear;

  /**
   * Need to response immediately or not.
   *
   * @see TS 11.14, clause 12.43, Immediate response.
   *
   * When this attribute is true, the terminal shall immediately send
   * MozStkResponse with resultCode is OK.
   *
   * true: The terminal shall send response immediately.
   * false: otherwise.
   */
  boolean responseNeeded;
};

Menu

dictionary nsIDOMMozStkItem
{
  /**
   * Identifier of item.
   *
   * The identifier is a single byte between '01' and 'FF'. Each item shall
   * have a unique identifier within an Item list.
   */
  unsigned short identifier;

  /**
   * Text string of item.
   */
  DOMString text;
};

dictionary nsIDOMMozStkMenu
{
  /**
   * Array of nsIDOMMozStkItem.
   *
   * @see TS 11.14, clause 12.9
   */
  jsval items; // nsIDOMMozStkItem[]

  /**
   * Presentation type, one of TYPE_*.
   */
  unsigned short presentationType;

  /**
   * Title of the menu.
   */
  DOMString title;

  /**
   * Default item identifier of the menu.
   */
  unsigned short defaultItem;

  /**
   * Help information available or not.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, SET UP MENU, bit 8.
   *
   * true: help information available.
   * false: no help information available.
   */
  boolean isHelpAvailable;
};

Input

dictionary nsIDOMMozStkInput
{
  /**
   * Text for the ME to display in conjunction with asking the user to respond.
   */
  DOMString text;

  /**
   * Minimum length of response.
   */
  unsigned short minLength;

  /**
   * Maximum length of response.
   */
  unsigned short maxLength;

  /**
   * Text for the ME to display, corresponds to a default text string offered
   * by the ICC.
   */
  DOMString defaultText;

  /**
   * Input format.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT, bit 1.
   *
   * true: Alphabet set.
   * false: Digits only.
   */
  boolean isAlphabet;

  /**
   * Alphabet encoding.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT, bit 2.
   *
   * true: UCS2 alphabet.
   * false: default SMS alphabet.
   */
  boolean isUCS2;

  /**
   * Visibility of input.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT, bit 3.
   *
   * true: User input shall not be revealed in any way.
   * false: ME may echo user input on the display.
   */
  boolean hideInput;

  /**
   * Yes/No response is requested.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INKEY, bit 3.
   *
   * true: Yes/No response is requested, and character sets
   *       (Alphabet set and UCS2) are disabled.
   * false: Character sets (Alphabet set and UCS2) are enabled.
   */
  boolean isYesNoRequested;

  /**
   * User input in packed or unpacked format.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT, bit 4.
   *
   * true: User input to be in SMS packed format.
   * false: User input to be in unpacked format.
   */
  boolean isPacked;

  /**
   * Help information available or not.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT/GET INKEY, bit 8.
   *
   * true: help information available.
   * false: no help information available.
   */
  boolean isHelpAvailable;
};

Browser Settings

dictionary nsIDOMMozStkBrowserSetting
{
  /**
   * Confirm message to launch browser.
   *
   * @see nsIDOMMozStkTextMessage for the detail specification of
   *      confirmMessage.
   */
  jsval confirmMessage;

  /**
   * The URL to be opened by browser.
   */
  DOMString url;

  /**
   * One of STK_BROWSER_MODE_*.
   *
   * @see nsIDOMMozIccManager.STK_BROWSER_MODE_*
   */
  unsigned short mode;
};

Set Up Call

dictionary nsIDOMMozStkSetUpCall
{
  /**
   * The Dialling number.
   */
  DOMString address;

  /**
   * The text message used in user confirmation phase.
   *
   * @see nsIDOMMozStkTextMessage for the detail specification of
   *      confirmMessage.
   */
  jsval confirmMessage;

  /**
   * The text message used in call set up phase.
   *
   * @see nsIDOMMozStkTextMessage for the detail specification of
   *      callMessage.
   */
  jsval callMessage;
};

From ME to ICC

• Terminal Response
• Envelope Command

STK response

dictionary nsIDOMMozStkResponse
{
  /**
   * commandNumber from MozStkCommand.
   *
   * @see nsIDOMMozStkCommand.commandNumber
   */
  unsigned short commandNumber;

  /**
   * One of nsIDOMMozStkCommand.typeOfCommand
   *
   * @see nsIDOMMozStkCommand.typeOfCommand
   */
  unsigned short typeOfCommand;

  /**
   * Qualifiers specific to the command.
   *
   * @see nsIDOMMozStkCommand.commandQualifier
   */
  unsigned short commandQualifier;

  /**
   * One of RESULT_*
   */
  unsigned short resultCode;

  /**
   * The identifier of the item selected by user.
   *
   * @see nsIDOMMozStkItem.identifier
   */
  unsigned short itemIdentifier;

  /**
   * User input.
   */
  DOMString input;

  /**
   * Alphabet encoding.
   *
   * @see nsIDOMMozStkInput.isUCS2
   */
  boolean isUCS2;

  /**
   * YES/NO response.
   *
   * @see nsIDOMMozStkInput.isYesNoRequested
   */
  boolean isYesNo;

  /**
   * Packed or unpacked format.
   *
   * @see nsIDOMMozStkInput.isPacked
   */
  boolean isPacked;

  /**
   * User has confirmed or rejected the call during STK_CMD_CALL_SET_UP.
   *
   * @see RIL_REQUEST_STK_HANDLE_CALL_SETUP_REQUESTED_FROM_SIM
   *
   * true: Confirmed by User.
   * false: Rejected by User.
   */
  boolean hasConfirmed;
};

STK constants

For simplicity, constants are listed here.

partial interface nsIDOMMozIccManager : nsIDOMEventTarget
{
  /**
   * STK Menu Presentation types.
   */
  const unsigned short STK_MENU_TYPE_NOT_SPECIFIED      = 0x00;
  const unsigned short STK_MENU_TYPE_DATA_VALUES        = 0x01;
  const unsigned short STK_MENU_TYPE_NAVIGATION_OPTIONS = 0x03;

  /**
   * Browser launch mode.
   */
  const unsigned short STK_BROWSER_MODE_LAUNCH_IF_NOT_ALREADY_LAUNCHED = 0x00;
  const unsigned short STK_BROWSER_MODE_USING_EXISTING_BROWSER         = 0x02;
  const unsigned short STK_BROWSER_MODE_USING_NEW_BROWSER              = 0x03;
 
  /**
   * STK Proactive commands.
   *
   * @see TS 11.14, clause 13.4
   */
  const unsigned short STK_CMD_REFRESH               = 0x01;
  const unsigned short STK_CMD_SET_UP_CALL           = 0x10;
  const unsigned short STK_CMD_SEND_SS               = 0x11;
  const unsigned short STK_CMD_SEND_USSD             = 0x12;
  const unsigned short STK_CMD_SEND_SMS              = 0x13;
  const unsigned short STK_CMD_SEND_DTMF             = 0x14;
  const unsigned short STK_CMD_LAUNCH_BROWSER        = 0x15;
  const unsigned short STK_CMD_DISPLAY_TEXT          = 0x21;
  const unsigned short STK_CMD_GET_INKEY             = 0x22;
  const unsigned short STK_CMD_GET_INPUT             = 0x23;
  const unsigned short STK_CMD_SELECT_ITEM           = 0x24;
  const unsigned short STK_CMD_SET_UP_MENU           = 0x25;
  const unsigned short STK_CMD_SET_UP_IDLE_MODE_TEXT = 0x28;

  /**
   * STK Result code.
   *
   * @see TS 11.14, clause 12.12
   *
   * Results '0X' and '1X' indicate that the command has been performed.
   */
  /** Command performed successfully */
  const unsigned short STK_RESULT_OK                                = 0x00;

  /** Command performed with partial comprehension */
  const unsigned short STK_RESULT_PRFRMD_WITH_PARTIAL_COMPREHENSION = 0x01;

  /** Command performed, with missing information */
  const unsigned short STK_RESULT_PRFRMD_WITH_MISSING_INFO          = 0x02;

  /** REFRESH performed with additional EFs read */
  const unsigned short STK_RESULT_PRFRMD_WITH_ADDITIONAL_EFS_READ   = 0x03;

  /** Command performed successfully, limited service */
  const unsigned short STK_RESULT_PRFRMD_LIMITED_SERVICE            = 0x06;

  /** Proactive UICC session terminated by the user */
  const unsigned short STK_RESULT_UICC_SESSION_TERM_BY_USER         = 0x10;

  /** Backward move in the proactive UICC session requested by the user */
  const unsigned short STK_RESULT_BACKWARD_MOVE_BY_USER             = 0x11;

  /** No response from user */
  const unsigned short STK_RESULT_NO_RESPONSE_FROM_USER             = 0x12;

  /** Help information required by the user */
  const unsigned short STK_RESULT_HELP_INFO_REQUIRED                = 0x13;

  /** USSD or SS transaction terminated by the user */
  const unsigned short STK_RESULT_USSD_SS_SESSION_TERM_BY_USER      = 0x14;

  /**
   * Results '2X' indicate to the UICC that it may be worth re-trying the
   * command at a later opportunity.
   */
  /** Terminal currently unable to process command */
  const unsigned short STK_RESULT_TERMINAL_CRNTLY_UNABLE_TO_PROCESS = 0x20;

  /** Network currently unable to process command */
  const unsigned short STK_RESULT_NETWORK_CRNTLY_UNABLE_TO_PROCESS  = 0x21;

  /** User did not accept the proactive command */
  const unsigned short STK_RESULT_USER_NOT_ACCEPT                   = 0x22;

  /** User cleared down call before connection or network release */
  const unsigned short STK_RESULT_USER_CLEAR_DOWN_CALL              = 0x23;

  /** Launch browser generic error code */
  const unsigned short STK_RESULT_LAUNCH_BROWSER_ERROR              = 0x26;

  /**
   * Results '3X' 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.
   */
  /** Command beyond terminal's capabilities */
  const unsigned short STK_RESULT_BEYOND_TERMINAL_CAPABILITY        = 0x30;

  /** Command type not understood by terminal */
  const unsigned short STK_RESULT_CMD_TYPE_NOT_UNDERSTOOD           = 0x31;

  /** Command data not understood by terminal */
  const unsigned short STK_RESULT_CMD_DATA_NOT_UNDERSTOOD           = 0x32;

  /** Command number not known by terminal */
  const unsigned short STK_RESULT_CMD_NUM_NOT_KNOWN                 = 0x33;

  /** SS Return Error */
  const unsigned short STK_RESULT_SS_RETURN_ERROR                   = 0x34;

  /** SMS RP-ERROR */
  const unsigned short STK_RESULT_SMS_RP_ERROR                      = 0x35;

  /** Error, required values are missing */
  const unsigned short STK_RESULT_REQUIRED_VALUES_MISSING           = 0x36;

  /** USSD Return Error */
  const unsigned short STK_RESULT_USSD_RETURN_ERROR                 = 0x37;

  /** MultipleCard commands error */
  const unsigned short STK_RESULT_MULTI_CARDS_CMD_ERROR             = 0x38;

  /**
   * Interaction with call control by USIM or MO short message control by
   * USIM, permanent problem
   */
  const unsigned short STK_RESULT_USIM_CALL_CONTROL_PERMANENT       = 0x39;

  /** Bearer Independent Protocol error */
  const unsigned short STK_RESULT_BIP_ERROR                         = 0x3a;
};

Examples

Show STK menu

var icc = navigator.mozMobileConnection.icc;
icc.onstkcommand = function (command) {
  switch (command.typeOfCommand) {
    case icc.STK_CMD_SET_UP_MENU:
      var menu = command.options;
      // create a Menu-like UI according to 'menu'
    break;
  }
};

Menu Selection

/**
 * onMenuSelected is the callback when some item of the menu is selected.
 * @param id    The index of the item being selected.
 * @param helpRequested     Request for help.
 */ 
function onMenuSelected(id, helpRequested) {
  var icc = navigator.mozMobileConnection.icc;
  icc.sendStkMenuSelection(id, helpRequested);
}

Select Item

// 'command' is got from onstkcommand
// and assume it's a Select Item command.
var icc = navigator.mozMobileConnection.icc;
var response = {
  resultCode : icc.STK_RESULT_OK,
  // 'id' is got from the choosed item identifier (menu.item[].identifier)
  itemIdentifier: id
};
mozIcc.sendStkResponse(command, response);

Get Input

var icc = navigator.mozMobileConnection.icc;
icc.onstkcommand = function (command) {
  switch (command.typeOfCommand) {
    case icc.STK_CMD_GET_INPUT:
      var input = command.options;
      // create a TextInput-like UI according to 'input'
    break;
  }
};

// onTextInput is the callback when user inputs complete.
var icc = navigator.mozMobileConnection.icc;
function onTextInput(input) {
  var response = {
    resultCode : mozICC.STK_RESULT_OK,
    input: input
  };
  mozIcc.sendStkResponse(command, response);
}

TODO

• Icon
• Duration
• Tone
• multi-SIM

Reference

• TS 11.14
• TS 102.223
• http://www.kandroid.org/online-pdk/guide/stk.html