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 WebMobileConnection

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.
   */ 
  void sendStkResponse(in nsIDOMMozStkResponse 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.
   *        
   */ 
  // TODO - Add deviceId for multi-SIM
  void sendStkMenuSelection(in unsigned short itemIdentifier, in boolean helpRequested);

STK message format

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

From ICC to ME

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

Basically, a Proactive command is 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 Proactive Command consists of at least two mandatory Comprehension-TLVs

• Command Details
• Device Identities

The remaining Comprehension-TLVs varies according to different type of 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 general term, MozStkCmdParameter

   ---------------- -------------- --------------------
  | CmdDetails-TLV | DeviceId-TLV | MozStkCmdParameter |
   ---------------- -------------- --------------------

So web apps can parse MozStkCmdParameter according to the typeOfCommand specified in CmdDetails. In this case, web apps can display a Menu-like UI according to this MozStkCmdParameter

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

STK Command Event

StkCommandEvent will be the parameter passed in onstkcommand handler

interface nsIDOMMozStkCommandEvent : nsIDOMEvent 
{
  readonly attribute nsIDOMMozStkCommand command;
};

STK command

• TODO: add deviceId for multi-SIM

interface nsIDOMMozStkCommand : nsISupports
{
  /**
   * The detail information of the proactive command issued by ICC.
   */ 
  readonly attribute nsIDOMMozStkCmdDetails cmdDetails;

  /**
   * The parameter of this proactive command issued by ICC.
   */ 
  readonly attribute nsIDOMMozStkCmdParameter param;

  //TODO: add deviceId for multi-SIM
};

Command Details

interface nsIDOMMozStkCmdDetails : nsISupports
{
  /**
   * Command number is 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
   */ 
  readonly attribute unsigned short commandNumber;

  /**
   * One of nsIDOMMozStkProactiveCommand.
   */  
  readonly attribute unsigned short typeOfCommand; 

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

Command Parameter

interface nsIDOMMozStkCmdParameter : nsISupports
{
  /**
   * Used when typeOfCommand in nsIDOMMozStkCommand is 
   * DISPLAY_TEXT, SET_UP_IDLE_MODE_TEXT, REFRESH and SEND_*.
   */
  readonly attribute nsIDOMMozStkTextMessage textMessage;
 
  /**
   * Used when typeOfCommand in nsIDOMMozStkCommand is 
   * SELECT_ITEM or SET_UP_MENU.
   */  
  readonly attribute nsIDOMMozStkMenu menu;

  /**
   * Used when typeOfCommand in nsIDOMMozStkCommand is 
   * GET_INKEY or GET_INPUT.
   */ 
  readonly attribute nsIDOMMozStkInput input;
 
  /**
   * Used when typeOfCommand in nsIDOMMozStkCommand is 
   * LAUNCH_BROWSER.
   */ 
  readonly attribute nsIDOMMozStkBrowserSetting setting;
 
  /**
   * Used when typeOfCommand in nsIDOMMozStkCommand is 
   * SET_UP_CALL.
   */ 
  readonly attribute nsIDOMMozStkSetUpCall setup;
};

UI parts - The detail format contained in MozStkCmdParameter

interface nsIDOMMozStkTextMessage : nsISupports
{
  /**
   * Text String.
   *
   * @see TS 11.14, clause 12.15, Text String.
   */ 
  readonly attribute 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
   */ 
  readonly attribute 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.
   */ 
  readonly attribute 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.
   */
  readonly attribute boolean responseNeeded;
};

interface nsIDOMMozStkItem : nsISupports
{
  /**
   * Identifier of item.
   *
   * The identifier is a single byte between '01' and 'FF'. Each item shall 
   * have a unique identifier within an Item list.
   */ 
  readonly attribute unsigned short identifier;
  
  /**
   * Text string of item.
   */ 
  readonly attribute DOMString text;
};

interface nsIDOMMozStkMenu : nsISupports
{
  /**
   * STK Menu Presentation types.
   */
  const unsigned short TYPE_NOT_SPECIFIED      = 0x00;
  const unsigned short TYPE_DATA_VALUES        = 0x01;
  const unsigned short TYPE_NAVIGATION_OPTIONS = 0x03;

  /**
   * Array of nsIDOMMozStkItem.
   *
   * @see TS 11.14, clause 12.9
   */ 
  readonly attribute jsval items; // nsIDOMMozStkItem[]

  /**
   * Presentation type, one of TYPE_*.
   */ 
  readonly attribute unsigned short presentationType;
  
  /**
   * Title of the menu.
   */ 
  readonly attribute DOMString title;

  /**
   * Default item identifier of the menu.
   */ 
  readonly attribute 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.
   */ 
  readonly attribute boolean isHelpAvailable;
};

interface nsIDOMMozStkInput : nsISupports
{
  /**
   * Text for the ME to display in conjunction with asking the user to respond.
   */ 
  readonly attribute DOMString text;

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

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

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

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

  /**
   * Alphabet encoding.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT, bit 2.
   *
   * true: UCS2 alphabet.
   * false: default SMS alphabet.
   */ 
  readonly attribute 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.
   */ 
  readonly attribute 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.
   * false: Character sets (Alphabet set and UCS2) are enabled.
   */ 
  readonly attribute boolean yesNo;

  /**
   * 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.
   */ 
  readonly attribute 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.
   */ 
  readonly attribute boolean isHelpAvailable;
};

From ME to ICC

• Terminal Response
• Envelope Command

STK response

[Constructor (nsIDOMMozStkCommand)]
interface nsIDOMMozStkResponse : nsISupports
{
  /**
   * The detail information of the proactive command issued by ICC.
   */ 
  readonly attribute nsIDOMMozStkCmdDetails cmdDetails;
  
  /**
   * One of nsIDOMMozStkResultCode.
   */ 
  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.yesNo
   */ 
  attribute boolean yesNo;

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

  /**
   * User has accepted 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 confirmation;

  //TODO add deviceId for multi-SIM
};

STK constants

/**
 * STK Proactive commands.
 *
 * @see TS 11.14, clause 13.4
 */
interface nsIDOMMozStkProactiveCommand : nsISupports
{
  const unsigned short REFRESH               = 0x01;
  const unsigned short SET_UP_CALL           = 0x10;
  const unsigned short SEND_SS               = 0x11;
  const unsigned short SEND_USSD             = 0x12;
  const unsigned short SEND_SMS              = 0x13;
  const unsigned short SEND_DTMF             = 0x14;
  const unsigned short LAUNCH_BROWSER        = 0x15;
  const unsigned short DISPLAY_TEXT          = 0x21;
  const unsigned short GET_INKEY             = 0x22;
  const unsigned short GET_INPUT             = 0x23;
  const unsigned short SELECT_ITEM           = 0x24;
  const unsigned short SET_UP_MENU           = 0x25;
  const unsigned short SET_UP_IDLE_MODE_TEXT = 0x28;
};

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

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

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

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

  /** Command performed, but modified by call control by NAA */
  const unsigned short PRFRMD_MODIFIED_BY_NAA            = 0x05;

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

  /** Command performed with modification */
  const unsigned short PRFRMD_WITH_MODIFICATION          = 0x07;

  /** REFRESH performed but indicated NAA was not active */
  const unsigned short PRFRMD_NAA_NOT_ACTIVE             = 0x08;

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

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

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

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

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

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

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

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

  /** Action in contradiction with the current timer state */
  const unsigned short CONTRADICTION_WITH_TIMER          = 0x24;

  /** Interaction with call control by NAA, temporary problem */
  const unsigned short NAA_CALL_CONTROL_TEMPORARY        = 0x25;

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

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

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

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

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

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

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

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

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

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

  /** Access Technology unable to process command */
  const unsigned short ACCESS_TECH_UNABLE_TO_PROCESS     = 0x3b;

  /** Frames error */
  const unsigned short FRAMES_ERROR                      = 0x3c;
};

Examples

Show STK menu

mobileConnection.onstkcommand = function (command) {
  var details = command.cmdDetails;
  switch (details.typeOfCommand) {
    case MozStkProactiveCommand.SET_UP_MENU:
      var menu = command.param.menu;
      // create a Menu-like UI according to 'menu'
    break;
  }
};

Menu Selection

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

Select Item

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

Get Input

mobileConnection.onstkcommand = function (command) {
  var details = command.cmdDetails;
  switch (details.typeOfCommand) {
    case MozStkProactiveCommand.GET_INPUT:
      var input = command.param.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);
  response.resultCode = MozStkResultCode.RESULT_OK;
  response.input = input;
  mobileConnection.sendStkResponse(response);
}

Set Up Call

mobileConnection.onstkcommand = function (command) {
  var details = command.cmdDetails;
  switch (details.typeOfCommand) {
    case MozStkProactiveCommand.SET_UP_CALL:
      var setup = command.param.setup;
      // 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);
  response.resultCode = MozStkResultCode.RESULT_OK;
  response.confirmation = confirm;
  mobileConnection.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