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.

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 response
   *        The response that will be sent to ICC.
   * @see nsIDOMMozStkResponse for the detail of response.
   */
  void sendStkResponse(in jsval response);

Send Envelope Command

Currently only support "Menu Selection"

  /**
   * 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);

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

[Constructor (number, type, qualifier)]
interface nsIDOMMozStkResponse : nsISupports
{
  /**
   * number from MozStkCommand..
   *
   * @see nsIDOMMozStkCommand.number
   */ 
  readonly attribute unsigned short number;

  /**
   * One of nsIDOMMozStkCommand.type
   *
   * @see nsIDOMMozStkCommand.type
   */  
  readonly attribute unsigned short type; 

  /**
   * Qualifiers specific to the command.
   *
   * @see nsIDOMMozStkCommand.qualifier
   */ 
  readonly attribute unsigned short qualifier;

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

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

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

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

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

  /**
   * Packed or unpacked format.
   *
   * @see nsIDOMMozStkInput.isPacked
   */ 
  attribute 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.
   */ 
  attribute boolean hasConfirmed;
};

STK constants

For simplicity, constants are listed here.

/**
 * STK Proactive commands.
 *
 * @see TS 11.14, clause 13.4
 */
partial interface nsIDOMMozStkCommand : nsISupports
{
  /**
   * STK Proactive commands.
   *
   * @see TS 11.14, clause 13.4
   */
  const unsigned short CMD_REFRESH               = 0x01;
  const unsigned short CMD_SET_UP_CALL           = 0x10;
  const unsigned short CMD_SEND_SS               = 0x11;
  const unsigned short CMD_SEND_USSD             = 0x12;
  const unsigned short CMD_SEND_SMS              = 0x13;
  const unsigned short CMD_SEND_DTMF             = 0x14;
  const unsigned short CMD_LAUNCH_BROWSER        = 0x15;
  const unsigned short CMD_DISPLAY_TEXT          = 0x21;
  const unsigned short CMD_GET_INKEY             = 0x22;
  const unsigned short CMD_GET_INPUT             = 0x23;
  const unsigned short CMD_SELECT_ITEM           = 0x24;
  const unsigned short CMD_SET_UP_MENU           = 0x25;
  const unsigned short CMD_SET_UP_IDLE_MODE_TEXT = 0x28;
}

/**
 * STK Result code.
 *
 * @see TS 11.14, clause 12.12
 */
partial interface nsIDOMMozStkResponse : nsISupports
{
  /**
   * 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 RESULT_OK                                = 0x00;

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

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

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

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

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

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

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

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

  /** USSD or SS transaction terminated by the user */
  const unsigned short 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 RESULT_TERMINAL_CRNTLY_UNABLE_TO_PROCESS = 0x20;

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

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

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

  /** Launch browser generic error code */
  const unsigned short 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 RESULT_BEYOND_TERMINAL_CAPABILITY        = 0x30;
  
  /** Command type not understood by terminal */
  const unsigned short RESULT_CMD_TYPE_NOT_UNDERSTOOD           = 0x31;

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

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

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

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

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

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

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

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

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

Examples

Show STK menu

mozIcc.onstkcommand = function (command) {
  switch (command.type) {
    case MozStkCommand.CMD_SET_UP_MENU:
      var menu = command.menu;
      // create a Menu-like UI according to 'menu'
    break;
  }
};

Menu Selection

function menuSelection(id, helpRequested) {
  mozIcc.sendMenuSelection(id, helpRequested);
}

Select Item

// 'command' is got from onstkcommand
// and assume it's a Select Item command.
var response = new MozStkResponse(command.number, command.type, command.qualifier);
response.resultCode = MozStkResponse.RESULT_OK;
// 'id' is got from the chosen item identifier (menu.item[].identifier)
response.itemIdentifier = id;
mozIcc.sendStkResponse(response);

Get Input

mozIcc.onstkcommand = function (command) {
  switch (command.type) {
    case MozStkCommand.CMD_GET_INPUT:
      var input = command.input;
      // create a TextInput-like UI according to 'input'
    break;
  }
};

// onTextInput is the callback when user inputs complete.
function onTextInput(input) {
  var response = new MozStkResponse(command.number, command.type, command.qualifier);
  response.resultCode = MozStkResponse.RESULT_OK;
  response.input = input;
  mozIcc.sendStkResponse(response);
}

Set Up Call

mozIcc.onstkcommand = function (command) {
  switch (command.type) {
    case MozStkCommand.CMD_SET_UP_CALL:
      var call = command.call;
      // create a Text Message UI to ask user confirmation 
      // for make the MO call.
    break;
  }
};

// onUserConfirm is the callback when user confirms the call.
function onUserConfirm(confirm) {
  var response = new MozStkResponse(command.number, command.type, command.qualifier);
  response.resultCode = MozStkResponse.RESULT_OK;
  response.confirmation = confirm;
  mozIcc.sendStkResponse(response);
}

TODO

• Icon
• Duration
• Tone
• Command Qualifier in CALL_SET_UP
• multi-SIM

Reference

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