MozillaWiki

WebAPI/WebSTK

< WebAPI
Revision as of 03:09, 20 June 2012 by Allstars.chh (talk | contribs) (→‎STK response)

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 handler for STK events

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

Send Response from ME to SIM

  • TODO: add sendEnvelopeCommand ?
  /**
   * Send the response back to ICC after an attempt to execute STK Proactive 
   * Command.
   */ 
  void sendStkResponse(in nsIDOMMozStkResponse response);

STK message format

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

From SIM 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;

  /**
   * One of nsIDOMMozStkCmd*Param.
   */ 
  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.
   * 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.
   *
   * 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.
   */
  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;

  /**
   * Selection preference.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, SET UP MENU, bit 1.
   *
   * true: selection using soft key preferred.
   * false: no selection preference.
   */ 
  readonly attribute boolean isSoftKeyPreferred;

  /**
   * 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 SIM.
   */ 
  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;

  /**
   * Packed or unpacked.
   *
   * @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;
};

From ME to SIM

  • Terminal Response
  • Envelope Command

STK response

interface nsIDOMMozStkResponse : nsISupports
{
  /**
   * The detail information of the proactive command issued by ICC.
   */ 
  readonly attribute nsIDOMMozStkCmdDetails cmdDetails;
  
  /**
   * One of STK_RESULT_*.
   */ 
  attribute unsigned short resultCode;

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

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

  /**
   * YES/NO response.
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INKEY, bit 3. 
   *
   * true: User selects 'Yes'.
   * false: User selects 'No'.
   */ 
  attribute boolean yesNo;

  /**
   * 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
 */
[scriptable, uuid(2d442d8b-2d5f-40b6-833c-a4406abc3917)]
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
 */
[scriptable, uuid(791bdec9-ea35-429d-8673-7f352e57ce15)]
interface nsIDOMMozStkResultCode : nsISupports
{
  const unsigned short OK                                = 0x00;
  const unsigned short PRFRMD_WITH_PARTIAL_COMPREHENSION = 0x01;
  const unsigned short PRFRMD_WITH_MISSING_INFO          = 0x02;
  const unsigned short PRFRMD_WITH_ADDITIONAL_EFS_READ   = 0x03;
  const unsigned short PRFRMD_ICON_NOT_DISPLAYED         = 0x04;
  const unsigned short PRFRMD_MODIFIED_BY_NAA            = 0x05;
  const unsigned short PRFRMD_LIMITED_SERVICE            = 0x06;
  const unsigned short PRFRMD_WITH_MODIFICATION          = 0x07;
  const unsigned short PRFRMD_NAA_NOT_ACTIVE             = 0x08;
  const unsigned short PRFRMD_TONE_NOT_PLAYED            = 0x09;
  const unsigned short UICC_SESSION_TERM_BY_USER         = 0x10;
  const unsigned short BACKWARD_MOVE_BY_USER             = 0x11;
  const unsigned short NO_RESPONSE_FROM_USER             = 0x12;
  const unsigned short HELP_INFO_REQUIRED                = 0x13;
  const unsigned short USSD_SS_SESSION_TERM_BY_USER      = 0x14;
  const unsigned short TERMINAL_CRNTLY_UNABLE_TO_PROCESS = 0x20;
  const unsigned short NETWORK_CRNTLY_UNABLE_TO_PROCESS  = 0x21;
  const unsigned short USER_NOT_ACCEPT                   = 0x22;
  const unsigned short USER_CLEAR_DOWN_CALL              = 0x23;
  const unsigned short CONTRADICTION_WITH_TIMER          = 0x24;
  const unsigned short NAA_CALL_CONTROL_TEMPORARY        = 0x25;
  const unsigned short LAUNCH_BROWSER_ERROR              = 0x26;
  const unsigned short MMS_TEMPORARY                     = 0x27;
  const unsigned short BEYOND_TERMINAL_CAPABILITY        = 0x30;
  const unsigned short CMD_TYPE_NOT_UNDERSTOOD           = 0x31;
  const unsigned short CMD_DATA_NOT_UNDERSTOOD           = 0x32;
  const unsigned short CMD_NUM_NOT_KNOWN                 = 0x33;
  const unsigned short SS_RETURN_ERROR                   = 0x34;
  const unsigned short SMS_RP_ERROR                      = 0x35;
  const unsigned short REQUIRED_VALUES_MISSING           = 0x36;
  const unsigned short USSD_RETURN_ERROR                 = 0x37;
  const unsigned short MULTI_CARDS_CMD_ERROR             = 0x38;
  const unsigned short USIM_CALL_CONTROL_PERMANENT       = 0x39;
  const unsigned short BIP_ERROR                         = 0x3a;
  const unsigned short ACCESS_TECH_UNABLE_TO_PROCESS     = 0x3b;
  const unsigned short FRAMES_ERROR                      = 0x3c;
  const unsigned short MMS_ERROR                         = 0x3d;
};

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/Select Item

// 'command' is got from onstkcommand
// and assume it's a SET_UP_MENU command.
var response = new MozStkResponse(command);
response.resultCode = MozStkResultCode.RESULT_OK;
// 'id' is got from the chosen item identifier (menu.item[].identifier)
response.menuSelection = 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

Reference

Retrieved from "https://wiki.mozilla.org/index.php?title=WebAPI/WebSTK&oldid=443419"