WebAPI/WebSTK: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
 
(25 intermediate revisions by one other user not shown)
Line 1: Line 1:
= Overview =
= Overview =
To provide DOM API for the STK(SIM Toolkit), or CAT (Card Application Toolkit), which allows web contents can interact with SIM applications.
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 <br>
Feature List: https://docs.google.com/spreadsheet/ccc?key=0AuvgnQ-Iwb6XdGV0aHZWdGdmZVEzZUxmZWNEaGJYWkE


= Interface =
= Interface =
Line 36: Line 40:
<pre>
<pre>
   /**
   /**
   * Send the response back to ICC after an attempt to execute STK Proactive  
   * Send the response back to ICC after an attempt to execute STK Proactive
   * Command.
   * Command.
   */  
  *
   void sendStkResponse(in nsIDOMMozStkResponse response);
  * @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);
</pre>
</pre>


=== Send Envelope Command ===
=== Send Envelope Command ===
Currently only support "Menu Selection"
Currently only support "Menu Selection", "Event Download"
<pre>
<pre>
   /**
   /**
Line 52: Line 62:
   * @param helpRequested
   * @param helpRequested
   *        true if user requests to provide help information, false otherwise.
   *        true if user requests to provide help information, false otherwise.
  *       
   */
   */  
   void sendStkMenuSelection(in unsigned short itemIdentifier,
   void sendStkMenuSelection(in unsigned short itemIdentifier, in boolean helpRequested);
                            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);
</pre>
</pre>


Line 152: Line 173:


<pre>
<pre>
interface nsIDOMMozStkCommandEvent : nsIDOMEvent  
interface nsIDOMMozStkCommandEvent : nsIDOMEvent
{
{
   readonly attribute nsIDOMMozStkCommand command;
  /**
  * See nsIDOMMozStkCommand for the detail of command.
  */
   readonly attribute jsval command;
};
};
</pre>
</pre>
Line 160: Line 184:
=== STK command ===
=== STK command ===
<pre>
<pre>
interface nsIDOMMozStkCommand : nsISupports
dictionary MozStkCommand
{
{
   /**
   /**
   * The number of command issued by ICC. And it is assigned  
   * The number of command issued by ICC. And it is assigned
   * by ICC may take any hexadecimal value betweean '01' and 'FE'.
   * by ICC may take any hexadecimal value betweean '01' and 'FE'.
   *
   *
   * @see TS 11.14, clause 6.5.1
   * @see TS 11.14, clause 6.5.1
   */  
   */
   readonly attribute unsigned short number;
   unsigned short commandNumber;


   /**
   /**
   * One of CMD_*
   * One of STK_CMD_*
   */
   */
   readonly attribute unsigned short type;  
   unsigned short typeOfCommand;


   /**
   /**
   * Qualifiers specific to the command.
   * Qualifiers specific to the command.
  */
  readonly attribute unsigned short qualifier;
 
  /**
  * Used when type in nsIDOMMozStkCommand is
  * DISPLAY_TEXT, SET_UP_IDLE_MODE_TEXT, REFRESH and SEND_*.
   */
   */
   readonly attribute nsIDOMMozStkTextMessage textMessage;
   unsigned short commandQualifier;
  /**
  * Used when type in nsIDOMMozStkCommand is
  * SELECT_ITEM or SET_UP_MENU.
  */ 
  readonly attribute nsIDOMMozStkMenu menu;


   /**
   /**
   * Used when type in nsIDOMMozStkCommand is  
   * options varies accrording to the typeOfCommand in MozStkCommand.
   * GET_INKEY or GET_INPUT.
  *
   */
  * When typeOfCommand is
  readonly attribute nsIDOMMozStkInput input;
  * - STK_CMD_DISPLAY_TEXT
  * - STK_CMD_SET_UP_IDLE_MODE_TEXT
  /**
  * - STK_CMD_SEND_{SS|USSD|SMS|DTMF},
   * Used when type in nsIDOMMozStkCommand is  
  * options is MozStkTextMessage.
   * LAUNCH_BROWSER.
  *
   */
  * When typeOfCommand is
  readonly attribute nsIDOMMozStkBrowserSetting setting;
  * - STK_CMD_SELECT_ITEM
  * - STK_CMD_SET_UP_MENU
  /**
  * options is MozStkMenu.
   * Used when type in nsIDOMMozStkCommand is  
  *
   * SET_UP_CALL.
  * When typeOfCommand is
   */  
  * - STK_CMD_GET_INKEY
   readonly attribute nsIDOMMozStkSetUpCall call;
  * - STK_CMD_GET_INPUT,
  * options is MozStkInput.
  *
  * When typeOfCommand is
  * - STK_CMD_LAUNCH_BROWSER
  * options is MozStkBrowserSetting.
  *
  * When typeOfCommand is
  * - STK_CMD_SET_UP_CALL
  * options is MozStkSetUpCall.
   *
  * When typeOfCommand is
  * - STK_CMD_SET_UP_EVENT_LIST
  * options is MozStkSetUpEventList.
   *
  * When typeOfCommand is
  * - STK_CMD_PLAY_TONE
  * options is MozStkPlayTone.
  *
   * When typeOfCommand is
   * - STK_CMD_POLL_INTERVAL
  * options is MozStkDuration.
   *
  * When typeOfCommand is
  * - STK_CMD_POLL_OFF
  * options is null.
  *
   * When typeOfCommand is
   * - STK_CMD_REFRESH
  * options is null.
   */
   jsval options;
};
};
</pre>
</pre>
Line 215: Line 258:
===== Text Message =====
===== Text Message =====
<pre>
<pre>
interface nsIDOMMozStkTextMessage : nsISupports
dictionary MozStkTextMessage
{
{
   /**
   /**
Line 221: Line 264:
   *
   *
   * @see TS 11.14, clause 12.15, Text String.
   * @see TS 11.14, clause 12.15, Text String.
   */  
   */
   readonly attribute DOMString text;
   DOMString text;


   /**
   /**
Line 229: Line 272:
   * @see TS 11.14, clause 12.6, Command Qualifier, Display Text, bit 1.
   * @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  
   * 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  
   * 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  
   * 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. If the command is rejected in spite of the high priority,
   * the terminal shall inform the ICC with resultCode is
   * the terminal shall inform the ICC with resultCode is
   * TERMINAL_CRNTLY_UNABLE_TO_PROCESS in MozStkResponse.
   * TERMINAL_CRNTLY_UNABLE_TO_PROCESS in MozStkResponse.
Line 238: Line 281:
   * true: high priority
   * true: high priority
   * false: normal priority
   * false: normal priority
   */  
   */
   readonly attribute boolean isHighPriority;
   boolean isHighPriority;


   /**
   /**
Line 247: Line 290:
   *
   *
   * If this attribute is true, but user doesn't give any input within a period
   * 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  
   * of time(said 30 secs), the terminal shall inform the ICC with resultCode
   * is NO_RESPONSE_FROM_USER in MozStkResponse.
   * is NO_RESPONSE_FROM_USER in MozStkResponse.
   *
   *
   * true: Wait for user to clear message.
   * true: Wait for user to clear message.
   * false: clear message after a delay.
   * false: clear message after a delay.
   */  
   */
   readonly attribute boolean userClear;
   boolean userClear;


   /**
   /**
Line 260: Line 303:
   * @see TS 11.14, clause 12.43, Immediate response.
   * @see TS 11.14, clause 12.43, Immediate response.
   *
   *
   * When this attribute is true, the terminal shall immediately send  
   * When this attribute is true, the terminal shall immediately send
   * MozStkResponse with resultCode is OK.
   * MozStkResponse with resultCode is OK.
   *
   *
Line 266: Line 309:
   * false: otherwise.
   * false: otherwise.
   */
   */
   readonly attribute boolean responseNeeded;
   boolean responseNeeded;
};
};
</pre>
</pre>
Line 272: Line 315:
===== Menu =====
===== Menu =====
<pre>
<pre>
interface nsIDOMMozStkItem : nsISupports
dictionary MozStkItem
{
{
   /**
   /**
   * Identifier of item.
   * Identifier of item.
   *
   *
   * The identifier is a single byte between '01' and 'FF'. Each item shall  
   * The identifier is a single byte between '01' and 'FF'. Each item shall
   * have a unique identifier within an Item list.
   * have a unique identifier within an Item list.
   */  
   */
   readonly attribute unsigned short identifier;
   unsigned short identifier;
 
 
   /**
   /**
   * Text string of item.
   * Text string of item.
   */  
   */
   readonly attribute DOMString text;
   DOMString text;
};
};
</pre>
</pre>


<pre>
<pre>
interface nsIDOMMozStkMenu : nsISupports
dictionary MozStkMenu
{
{
   /**
   /**
  * STK Menu Presentation types.
   * Array of MozStkItem.
  */
  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
   * @see TS 11.14, clause 12.9
   */  
   */
   readonly attribute jsval items; // nsIDOMMozStkItem[]
   jsval items; // MozStkItem[]


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


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


   /**
   /**
   * Help information available or not.
   * Help information available or not.
   *  
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, SET UP MENU, bit 8.
   * @see TS 11.14, clause 12.6, Command Qualifier, SET UP MENU, bit 8.
   *
   *
   * true: help information available.
   * true: help information available.
   * false: no help information available.
   * false: no help information available.
   */  
   */
   readonly attribute boolean isHelpAvailable;
   boolean isHelpAvailable;
};
};
</pre>
</pre>
Line 335: Line 371:
===== Input =====
===== Input =====
<pre>
<pre>
interface nsIDOMMozStkInput : nsISupports
dictionary MozStkInput
{
{
   /**
   /**
   * Text for the ME to display in conjunction with asking the user to respond.
   * Text for the ME to display in conjunction with asking the user to respond.
   */  
   */
   readonly attribute DOMString text;
   DOMString text;


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


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


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


   /**
   /**
Line 365: Line 401:
   * true: Alphabet set.
   * true: Alphabet set.
   * false: Digits only.
   * false: Digits only.
   */  
   */
   readonly attribute boolean isAlphabet;
   boolean isAlphabet;


   /**
   /**
Line 375: Line 411:
   * true: UCS2 alphabet.
   * true: UCS2 alphabet.
   * false: default SMS alphabet.
   * false: default SMS alphabet.
   */  
   */
   readonly attribute boolean isUCS2;
   boolean isUCS2;
 
 
   /**
   /**
   * Visibility of input.
   * Visibility of input.
Line 385: Line 421:
   * true: User input shall not be revealed in any way.
   * true: User input shall not be revealed in any way.
   * false: ME may echo user input on the display.
   * false: ME may echo user input on the display.
   */  
   */
   readonly attribute boolean hideInput;
   boolean hideInput;
 
 
   /**
   /**
   * Yes/No response is requested.
   * Yes/No response is requested.
Line 393: Line 429:
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INKEY, bit 3.
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INKEY, bit 3.
   *
   *
   * true: Yes/No response is requested. And character sets  
   * true: Yes/No response is requested, and character sets
   *      (Alphabet set and UCS2) are disabled.
   *      (Alphabet set and UCS2) are disabled.
   * false: Character sets (Alphabet set and UCS2) are enabled.
   * false: Character sets (Alphabet set and UCS2) are enabled.
   */  
   */
   readonly attribute boolean isYesNoRequested;
   boolean isYesNoRequested;


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


   /**
   /**
   * Help information available or not.
   * Help information available or not.
   *  
   *
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT/GET INKEY, bit 8.
   * @see TS 11.14, clause 12.6, Command Qualifier, GET INPUT/GET INKEY, bit 8.
   *
   *
   * true: help information available.
   * true: help information available.
   * false: no help information available.
   * false: no help information available.
   */  
   */
   readonly attribute boolean isHelpAvailable;
   boolean isHelpAvailable;
};
};
</pre>
</pre>
Line 423: Line 459:
===== Browser Settings =====
===== Browser Settings =====
<pre>
<pre>
interface nsIDOMMozStkBrowserSetting : nsISupports
dictionary MozStkBrowserSetting
{
{
  /**
  * Browser launch mode.
  */
  const unsigned short MODE_LAUNCH_IF_NOT_ALREADY_LAUNCHED = 0x00;
  // 0x01 is not used.
  const unsigned short MODE_USING_EXISTING_BROWSER        = 0x02;
  const unsigned short MODE_USING_NEW_BROWSER              = 0x03;
   /**
   /**
   * Confirm message to launch browser.
   * Confirm message to launch browser.
   */  
  *
   readonly attribute nsIDOMMozStkTextMessage confirmMessage;
  * @see MozStkTextMessage for the detail specification of
  *      confirmMessage.
   */
   jsval confirmMessage;


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


   /**
   /**
   * One of MODE_*.
   * One of STK_BROWSER_MODE_*.
   */  
  *
   readonly attribute unsigned short mode;
  * @see nsIDOMMozIccManager.STK_BROWSER_MODE_*
   */
   unsigned short mode;
};
};
</pre>
</pre>


===== Call Set Up =====
===== Set Up Call =====
<pre>
<pre>
interface nsIDOMMozStkSetUpCall : nsISupports
dictionary MozStkSetUpCall
{
{
   /**
   /**
   * The Dialling number.
   * The Dialling number.
   */  
   */
   readonly attribute DOMString address;
   DOMString address;


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


   /**
   /**
   * The text message used in call set up phase.
   * The text message used in call set up phase.
   */  
  *
   readonly attribute nsIDOMMozStkTextMessage callMessage;
  * @see MozStkTextMessage for the detail specification of
  *      callMessage.
   */
   jsval callMessage;
};
};
</pre>
</pre>
Line 476: Line 515:
=== STK response ===
=== STK response ===
<pre>
<pre>
[Constructor (number, type, qualifier)]
dictionary MozStkResponse
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_*
   * One of RESULT_*
   */  
   */
   attribute unsigned short resultCode;
   unsigned short resultCode;


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


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


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


   /**
   /**
   * Packed or unpacked format.
   * User has confirmed or rejected the call during STK_CMD_CALL_SET_UP.
   *
   *
  * @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
   * @see RIL_REQUEST_STK_HANDLE_CALL_SETUP_REQUESTED_FROM_SIM
   *
   *
   * true: Confirmed by User.
   * true: Confirmed by User.
   * false: Rejected by User.
   * false: Rejected by User.
   */  
   */
   attribute boolean hasConfirmed;
   boolean hasConfirmed;
};
};
</pre>
</pre>
Line 553: Line 556:
For simplicity, constants are listed here.
For simplicity, constants are listed here.
<pre>
<pre>
/**
partial interface nsIDOMMozIccManager : nsIDOMEventTarget
* STK Proactive commands.
*
* @see TS 11.14, clause 13.4
*/
partial interface nsIDOMMozStkCommand : nsISupports
{
{
  /**
  * 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.
   * STK Proactive commands.
Line 565: Line 577:
   * @see TS 11.14, clause 13.4
   * @see TS 11.14, clause 13.4
   */
   */
   const unsigned short CMD_REFRESH               = 0x01;
   const unsigned short STK_CMD_REFRESH               = 0x01;
   const unsigned short CMD_SET_UP_CALL           = 0x10;
   const unsigned short STK_CMD_POLL_INTERVAL        = 0x03;
   const unsigned short CMD_SEND_SS               = 0x11;
  const unsigned short STK_CMD_POLL_OFF              = 0x04;
   const unsigned short CMD_SEND_USSD             = 0x12;
  const unsigned short STK_CMD_SET_UP_EVENT_LIST    = 0x05;
   const unsigned short CMD_SEND_SMS             = 0x13;
  const unsigned short STK_CMD_SET_UP_CALL           = 0x10;
   const unsigned short CMD_SEND_DTMF             = 0x14;
   const unsigned short STK_CMD_SEND_SS               = 0x11;
   const unsigned short CMD_LAUNCH_BROWSER       = 0x15;
   const unsigned short STK_CMD_SEND_USSD             = 0x12;
   const unsigned short CMD_DISPLAY_TEXT         = 0x21;
   const unsigned short STK_CMD_SEND_SMS             = 0x13;
   const unsigned short CMD_GET_INKEY             = 0x22;
   const unsigned short STK_CMD_SEND_DTMF             = 0x14;
   const unsigned short CMD_GET_INPUT             = 0x23;
   const unsigned short STK_CMD_LAUNCH_BROWSER       = 0x15;
   const unsigned short CMD_SELECT_ITEM           = 0x24;
   const unsigned short STK_CMD_PLAY_TONE            = 0x20;
   const unsigned short CMD_SET_UP_MENU           = 0x25;
  const unsigned short STK_CMD_DISPLAY_TEXT         = 0x21;
   const unsigned short CMD_SET_UP_IDLE_MODE_TEXT = 0x28;
   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
*/
partial interface nsIDOMMozStkResponse : nsISupports
{
   /**
   /**
   * STK Result code.
   * STK Result code.
   *
   *
   * @see TS 11.14, clause 12.12
   * @see TS 11.14, clause 12.12
   */
   *
 
  /**
   * Results '0X' and '1X' indicate that the command has been performed.
   * Results '0X' and '1X' indicate that the command has been performed.
   */
   */
   /** Command performed successfully */
   /** Command performed successfully */
   const unsigned short RESULT_OK                               = 0x00;
   const unsigned short STK_RESULT_OK                               = 0x00;


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


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


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


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


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


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


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


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


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


   /**
   /**
Line 631: Line 637:
   */
   */
   /** Terminal currently unable to process command */
   /** Terminal currently unable to process command */
   const unsigned short RESULT_TERMINAL_CRNTLY_UNABLE_TO_PROCESS = 0x20;
   const unsigned short STK_RESULT_TERMINAL_CRNTLY_UNABLE_TO_PROCESS = 0x20;


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


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


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


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


   /**
   /**
Line 651: Line 657:
   */
   */
   /** Command beyond terminal's capabilities */
   /** Command beyond terminal's capabilities */
   const unsigned short RESULT_BEYOND_TERMINAL_CAPABILITY       = 0x30;
   const unsigned short STK_RESULT_BEYOND_TERMINAL_CAPABILITY       = 0x30;
 
 
   /** Command type not understood by terminal */
   /** Command type not understood by terminal */
   const unsigned short RESULT_CMD_TYPE_NOT_UNDERSTOOD           = 0x31;
   const unsigned short STK_RESULT_CMD_TYPE_NOT_UNDERSTOOD           = 0x31;


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


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


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


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


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


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


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


   /**
   /**
Line 681: Line 687:
   * USIM, permanent problem
   * USIM, permanent problem
   */
   */
   const unsigned short RESULT_USIM_CALL_CONTROL_PERMANENT       = 0x39;
   const unsigned short STK_RESULT_USIM_CALL_CONTROL_PERMANENT       = 0x39;


   /** Bearer Independent Protocol error */
   /** Bearer Independent Protocol error */
   const unsigned short RESULT_BIP_ERROR                         = 0x3a;
   const unsigned short STK_RESULT_BIP_ERROR                         = 0x3a;
};
 
  /**
  * STK Event List
  */
  const unsigned short STK_EVENT_TYPE_MT_CALL                          = 0x00;
  const unsigned short STK_EVENT_TYPE_CALL_CONNECTED                  = 0x01;
  const unsigned short STK_EVENT_TYPE_CALL_DISCONNECTED                = 0x02;
  const unsigned short STK_EVENT_TYPE_LOCATION_STATUS                  = 0x03;
  const unsigned short STK_EVENT_TYPE_USER_ACTIVITY                    = 0x04;
  const unsigned short STK_EVENT_TYPE_IDLE_SCREEN_AVAILABLE            = 0x05;
  const unsigned short STK_EVENT_TYPE_CARD_READER_STATUS              = 0x06;
  const unsigned short STK_EVENT_TYPE_LANGUAGE_SELECTION              = 0x07;
  const unsigned short STK_EVENT_TYPE_BROWSER_TERMINATION              = 0x08;
  const unsigned short STK_EVENT_TYPE_DATA_AVAILABLE                  = 0x09;
  const unsigned short STK_EVENT_TYPE_CHANNEL_STATUS                  = 0x0a;
  const unsigned short STK_EVENT_TYPE_SINGLE_ACCESS_TECHNOLOGY_CHANGED = 0x0b;
  const unsigned short STK_EVENT_TYPE_DISPLAY_PARAMETER_CHANGED        = 0x0c;
  const unsigned short STK_EVENT_TYPE_LOCAL_CONNECTION                = 0x0d;
  const unsigned short STK_EVENT_TYPE_NETWORK_SEARCH_MODE_CHANGED      = 0x0e;
  const unsigned short STK_EVENT_TYPE_BROWSING_STATUS                  = 0x0f;
  const unsigned short STK_EVENT_TYPE_FRAMES_INFORMATION_CHANGED      = 0x10;
 
  /**
    * The service state of STK Location Status.
    */
  const unsigned short STK_SERVICE_STATE_NORMAL      = 0x00;
  const unsigned short STK_SERVICE_STATE_LIMITED    = 0x01;
  const unsigned short STK_SERVICE_STATE_UNAVAILABLE = 0x02;
 
  /**
  * Tone type.
  */
  const unsigned short STK_TONE_TYPE_DIAL_TONE                = 0x01;
  const unsigned short STK_TONE_TYPE_CALLED_SUBSCRIBER_BUSY  = 0x02;
  const unsigned short STK_TONE_TYPE_CONGESTION              = 0x03;
  const unsigned short STK_TONE_TYPE_RADIO_PATH_ACK          = 0x04;
  const unsigned short STK_TONE_TYPE_RADIO_PATH_NOT_AVAILABLE = 0x05;
  const unsigned short STK_TONE_TYPE_ERROR                    = 0x06;
  const unsigned short STK_TONE_TYPE_CALL_WAITING_TONE        = 0x07;
  const unsigned short STK_TONE_TYPE_RINGING_TONE            = 0x08;
  const unsigned short STK_TONE_TYPE_GENERAL_BEEP            = 0x10;
  const unsigned short STK_TONE_TYPE_POSITIVE_ACK_TONE        = 0x11;
  const unsigned short STK_TONE_TYPE_NEGATIVE_ACK_TONE        = 0x12;
 
  /**
  * Time unit
  */
  const unsigned short STK_TIME_UNIT_MINUTE      = 0x00;
  const unsigned short STK_TIME_UNIT_SECOND      = 0x01;
  const unsigned short STK_TIME_UNIT_TENTH_SECOND = 0x02;
}
</pre>
</pre>


Line 691: Line 747:
== Show STK menu ==
== Show STK menu ==
<pre>
<pre>
mozIcc.onstkcommand = function (command) {
var icc = navigator.mozMobileConnection.icc;
   switch (command.type) {
icc.onstkcommand = function (evt) {
     case MozStkCommand.CMD_SET_UP_MENU:
  var command = evt.command
       var menu = command.menu;
   switch (command.typeOfCommand) {
     case icc.STK_CMD_SET_UP_MENU:
       var menu = command.options;
       // create a Menu-like UI according to 'menu'
       // create a Menu-like UI according to 'menu'
     break;
     break;
Line 703: Line 761:
== Menu Selection ==  
== Menu Selection ==  
<pre>
<pre>
function menuSelection(id, helpRequested) {
/**
   mozIcc.sendMenuSelection(id, helpRequested);
* 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);
}
}
</pre>
</pre>
Line 712: Line 776:
// 'command' is got from onstkcommand
// 'command' is got from onstkcommand
// and assume it's a Select Item command.
// and assume it's a Select Item command.
var response = new MozStkResponse(command.number, command.type, command.qualifier);
var icc = navigator.mozMobileConnection.icc;
response.resultCode = MozStkResponse.RESULT_OK;
var response = {
// 'id' is got from the chosen item identifier (menu.item[].identifier)
  resultCode : icc.STK_RESULT_OK,
response.itemIdentifier = id;
  // 'id' is got from the choosed item identifier (menu.item[].identifier)
mozIcc.sendStkResponse(response);
  itemIdentifier: id
};
mozIcc.sendStkResponse(command, response);
</pre>
</pre>


== Get Input ==
== Get Input ==
<pre>
<pre>
mozIcc.onstkcommand = function (command) {
var icc = navigator.mozMobileConnection.icc;
   switch (command.type) {
icc.onstkcommand = function (evt) {
     case MozStkCommand.CMD_GET_INPUT:
  var command = evt.command
       var input = command.input;
   switch (command.typeOfCommand) {
     case icc.STK_CMD_GET_INPUT:
       var input = command.options;
       // create a TextInput-like UI according to 'input'
       // create a TextInput-like UI according to 'input'
     break;
     break;
Line 731: Line 799:


// onTextInput is the callback when user inputs complete.
// onTextInput is the callback when user inputs complete.
var icc = navigator.mozMobileConnection.icc;
function onTextInput(input) {
function onTextInput(input) {
   var response = new MozStkResponse(command.number, command.type, command.qualifier);
   var response = {
  response.resultCode = MozStkResponse.RESULT_OK;
     resultCode : mozICC.STK_RESULT_OK,
  response.input = input;
     input: input
  mozIcc.sendStkResponse(response);
   };
}
   mozIcc.sendStkResponse(command, response);
</pre>
 
== Set Up Call ==
<pre>
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);
}
}
</pre>
</pre>
Line 762: Line 811:
= TODO =
= TODO =
* Icon
* Icon
* Duration
* Timer
* Tone
* Command Qualifier in CALL_SET_UP
* multi-SIM


= Reference =
= Reference =
Line 771: Line 817:
* TS 102.223
* TS 102.223
* http://www.kandroid.org/online-pdk/guide/stk.html
* http://www.kandroid.org/online-pdk/guide/stk.html
[[Category:Web APIs]]

Latest revision as of 23:27, 1 October 2014

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 MozStkCommand
{
  /**
   * 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 MozStkCommand.
   *
   * When typeOfCommand is
   * - STK_CMD_DISPLAY_TEXT
   * - STK_CMD_SET_UP_IDLE_MODE_TEXT
   * - STK_CMD_SEND_{SS|USSD|SMS|DTMF},
   * options is MozStkTextMessage.
   *
   * When typeOfCommand is
   * - STK_CMD_SELECT_ITEM
   * - STK_CMD_SET_UP_MENU
   * options is MozStkMenu.
   *
   * When typeOfCommand is
   * - STK_CMD_GET_INKEY
   * - STK_CMD_GET_INPUT,
   * options is MozStkInput.
   *
   * When typeOfCommand is
   * - STK_CMD_LAUNCH_BROWSER
   * options is MozStkBrowserSetting.
   *
   * When typeOfCommand is
   * - STK_CMD_SET_UP_CALL
   * options is MozStkSetUpCall.
   *
   * When typeOfCommand is
   * - STK_CMD_SET_UP_EVENT_LIST
   * options is MozStkSetUpEventList.
   *
   * When typeOfCommand is
   * - STK_CMD_PLAY_TONE
   * options is MozStkPlayTone.
   *
   * When typeOfCommand is
   * - STK_CMD_POLL_INTERVAL
   * options is MozStkDuration.
   *
   * When typeOfCommand is
   * - STK_CMD_POLL_OFF
   * options is null.
   *
   * When typeOfCommand is
   * - STK_CMD_REFRESH
   * options is null.
   */
  jsval options;
};

UI parts - The UI Component contained in MozStkCommand

Text Message
dictionary MozStkTextMessage
{
  /**
   * 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 MozStkItem
{
  /**
   * 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 MozStkMenu
{
  /**
   * Array of MozStkItem.
   *
   * @see TS 11.14, clause 12.9
   */
  jsval items; // MozStkItem[]

  /**
   * 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 MozStkInput
{
  /**
   * 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 MozStkBrowserSetting
{
  /**
   * Confirm message to launch browser.
   *
   * @see MozStkTextMessage 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 MozStkSetUpCall
{
  /**
   * The Dialling number.
   */
  DOMString address;

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

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

From ME to ICC

  • Terminal Response
  • Envelope Command

STK response

dictionary MozStkResponse
{
  /**
   * One of RESULT_*
   */
  unsigned short resultCode;

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

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

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

  /**
   * 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_POLL_INTERVAL         = 0x03;
  const unsigned short STK_CMD_POLL_OFF              = 0x04;
  const unsigned short STK_CMD_SET_UP_EVENT_LIST     = 0x05;
  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_PLAY_TONE             = 0x20;
  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;

  /**
   * STK Event List
   */
   const unsigned short STK_EVENT_TYPE_MT_CALL                          = 0x00;
   const unsigned short STK_EVENT_TYPE_CALL_CONNECTED                   = 0x01;
   const unsigned short STK_EVENT_TYPE_CALL_DISCONNECTED                = 0x02;
   const unsigned short STK_EVENT_TYPE_LOCATION_STATUS                  = 0x03;
   const unsigned short STK_EVENT_TYPE_USER_ACTIVITY                    = 0x04;
   const unsigned short STK_EVENT_TYPE_IDLE_SCREEN_AVAILABLE            = 0x05;
   const unsigned short STK_EVENT_TYPE_CARD_READER_STATUS               = 0x06;
   const unsigned short STK_EVENT_TYPE_LANGUAGE_SELECTION               = 0x07;
   const unsigned short STK_EVENT_TYPE_BROWSER_TERMINATION              = 0x08;
   const unsigned short STK_EVENT_TYPE_DATA_AVAILABLE                   = 0x09;
   const unsigned short STK_EVENT_TYPE_CHANNEL_STATUS                   = 0x0a;
   const unsigned short STK_EVENT_TYPE_SINGLE_ACCESS_TECHNOLOGY_CHANGED = 0x0b;
   const unsigned short STK_EVENT_TYPE_DISPLAY_PARAMETER_CHANGED        = 0x0c;
   const unsigned short STK_EVENT_TYPE_LOCAL_CONNECTION                 = 0x0d;
   const unsigned short STK_EVENT_TYPE_NETWORK_SEARCH_MODE_CHANGED      = 0x0e;
   const unsigned short STK_EVENT_TYPE_BROWSING_STATUS                  = 0x0f;
   const unsigned short STK_EVENT_TYPE_FRAMES_INFORMATION_CHANGED       = 0x10;

   /**
    * The service state of STK Location Status.
    */
   const unsigned short STK_SERVICE_STATE_NORMAL      = 0x00;
   const unsigned short STK_SERVICE_STATE_LIMITED     = 0x01;
   const unsigned short STK_SERVICE_STATE_UNAVAILABLE = 0x02;

  /**
   * Tone type.
   */
  const unsigned short STK_TONE_TYPE_DIAL_TONE                = 0x01;
  const unsigned short STK_TONE_TYPE_CALLED_SUBSCRIBER_BUSY   = 0x02;
  const unsigned short STK_TONE_TYPE_CONGESTION               = 0x03;
  const unsigned short STK_TONE_TYPE_RADIO_PATH_ACK           = 0x04;
  const unsigned short STK_TONE_TYPE_RADIO_PATH_NOT_AVAILABLE = 0x05;
  const unsigned short STK_TONE_TYPE_ERROR                    = 0x06;
  const unsigned short STK_TONE_TYPE_CALL_WAITING_TONE        = 0x07;
  const unsigned short STK_TONE_TYPE_RINGING_TONE             = 0x08;
  const unsigned short STK_TONE_TYPE_GENERAL_BEEP             = 0x10;
  const unsigned short STK_TONE_TYPE_POSITIVE_ACK_TONE        = 0x11;
  const unsigned short STK_TONE_TYPE_NEGATIVE_ACK_TONE        = 0x12;

  /**
   * Time unit
   */
  const unsigned short STK_TIME_UNIT_MINUTE       = 0x00;
  const unsigned short STK_TIME_UNIT_SECOND       = 0x01;
  const unsigned short STK_TIME_UNIT_TENTH_SECOND = 0x02;
}

Examples

Show STK menu

var icc = navigator.mozMobileConnection.icc;
icc.onstkcommand = function (evt) {
  var command = evt.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 (evt) {
  var command = evt.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
  • Timer

Reference