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

interface nsIDOMMozStkConstants : nsISupports
{
  /**
   * STK Proactive commands.
   *
   * @see TS 11.14, clause 13.4
   */ 
  const unsigned short STK_CMD_REFRESH               = 0x01;
  const unsigned short STK_CMD_SET_UP_CALL           = 0x10;
  const unsigned short STK_CMD_SEND_SS               = 0x11;
  const unsigned short STK_CMD_SEND_USSD             = 0x12;
  const unsigned short STK_CMD_SEND_SMS              = 0x13;
  const unsigned short STK_CMD_SEND_DTMF             = 0x14;
  const unsigned short STK_CMD_LAUNCH_BROWSER        = 0x15;
  const unsigned short STK_CMD_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
   */ 
  const unsigned short STK_RESULT_OK = 0x00;
  const unsigned short STK_RESULT_PRFRMD_WITH_PARTIAL_COMPREHENSION = 0x01;
  const unsigned short STK_RESULT_PRFRMD_WITH_MISSING_INFO = 0x02;
  const unsigned short STK_RESULT_PRFRMD_WITH_ADDITIONAL_EFS_READ = 0x03;
  const unsigned short STK_RESULT_PRFRMD_ICON_NOT_DISPLAYED = 0x04;
  const unsigned short STK_RESULT_PRFRMD_MODIFIED_BY_NAA = 0x05;
  const unsigned short STK_RESULT_PRFRMD_LIMITED_SERVICE = 0x06;
  const unsigned short STK_RESULT_PRFRMD_WITH_MODIFICATION = 0x07;
  const unsigned short STK_RESULT_PRFRMD_NAA_NOT_ACTIVE = 0x08;
  const unsigned short STK_RESULT_PRFRMD_TONE_NOT_PLAYED = 0x09;
  const unsigned short STK_RESULT_UICC_SESSION_TERM_BY_USER = 0x10;
  const unsigned short STK_RESULT_BACKWARD_MOVE_BY_USER = 0x11;
  const unsigned short STK_RESULT_NO_RESPONSE_FROM_USER = 0x12;
  const unsigned short STK_RESULT_HELP_INFO_REQUIRED = 0x13;
  const unsigned short STK_RESULT_USSD_SS_SESSION_TERM_BY_USER = 0x14;
  const unsigned short STK_RESULT_TERMINAL_CRNTLY_UNABLE_TO_PROCESS = 0x20;
  const unsigned short STK_RESULT_NETWORK_CRNTLY_UNABLE_TO_PROCESS = 0x21;
  const unsigned short STK_RESULT_USER_NOT_ACCEPT = 0x22;
  const unsigned short STK_RESULT_USER_CLEAR_DOWN_CALL = 0x23;
  const unsigned short STK_RESULT_CONTRADICTION_WITH_TIMER = 0x24;
  const unsigned short STK_RESULT_NAA_CALL_CONTROL_TEMPORARY = 0x25;
  const unsigned short STK_RESULT_LAUNCH_BROWSER_ERROR = 0x26;
  const unsigned short STK_RESULT_MMS_TEMPORARY = 0x27;
  const unsigned short STK_RESULT_BEYOND_TERMINAL_CAPABILITY = 0x30;
  const unsigned short STK_RESULT_CMD_TYPE_NOT_UNDERSTOOD = 0x31;
  const unsigned short STK_RESULT_CMD_DATA_NOT_UNDERSTOOD = 0x32;
  const unsigned short STK_RESULT_CMD_NUM_NOT_KNOWN = 0x33;
  const unsigned short STK_RESULT_SS_RETURN_ERROR = 0x34;
  const unsigned short STK_RESULT_SMS_RP_ERROR = 0x35;
  const unsigned short STK_RESULT_REQUIRED_VALUES_MISSING = 0x36;
  const unsigned short STK_RESULT_USSD_RETURN_ERROR = 0x37;
  const unsigned short STK_RESULT_MULTI_CARDS_CMD_ERROR = 0x38;
  const unsigned short STK_RESULT_USIM_CALL_CONTROL_PERMANENT = 0x39;
  const unsigned short STK_RESULT_BIP_ERROR = 0x3a;
  const unsigned short STK_RESULT_ACCESS_TECH_UNABLE_TO_PROCESS = 0x3b;
  const unsigned short STK_RESULT_FRAMES_ERROR = 0x3c;
  const unsigned short STK_RESULT_MMS_ERROR = 0x3d;

  /**
   * STK Menu Presentation types.
   */ 
  const unsigned short STK_MENU_PRESENTATION_TYPE_NOT_SPECIFIED = 0x00;
  const unsigned short STK_MENU_PRESENTATION_TYPE_DATA_VALUES = 0x01;
  const unsigned short STK_MENU_PRESENTATION_TYPE_NAVIGATION_OPTIONS = 0x03;
};

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;

  //TODO: duration
  //TODO: title
  //TODO: icon
};

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;

  //TODO: icon
};

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

  /**
   * Presentation type, one of STK_MENU_PRESENTATION_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;

  // TODO 
  // title icon
  // items icon
};

/**
 * RESPONSE LENGTH data object.
 * TS 11.14, clause 12.11
 */ 
interface nsIDOMMozStkResponseLength : nsISupports
{
  /**
   * Minimum length of response.
   */ 
  readonly attribute unsigned short minLength;

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

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

  /**
   * The minimum and maximum acceptable lengths in characters for the response 
   * from the user.
   */
  readonly attribute nsIDOMMozStkResponseLength responseLength;

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

  //TODO icon
};

interface nsIDOMMozStkCmdParameter : nsISupports
{
  //TODO icon
};

/**
 * Used as command parameter when typeOfCommand in nsIDOMMozStkCommand is 
 * STK_CMD_DISPLAY_TEXT, STK_CMD_SET_UP_IDLE_MODE_TEXT, STK_CMD_REFRESH and
 * STK_CMD_SEND_*.
 */ 
interface nsIDOMMozStkCmdDisplayTextParam : nsIDOMMozStkCmdParameter
{
  readonly attribute nsIDOMMozStkTextMessage textMessage;
};

/**
 * Used as command parameter when typeOfCommand in nsIDOMMozStkCommand is 
 * STK_CMD_SELECT_ITEM or STK_CMD_SET_UP_MENU.
 */ 
interface nsIDOMMozStkCmdSelectItemParam : nsIDOMMozStkCmdParameter
{
  readonly attribute nsIDOMMozStkMenu menu;

  readonly attribute boolean loadTitleIcon;
};

/**
 * Used as command parameter when typeOfCommand in nsIDOMMozStkCommand is 
 * STK_CMD_GET_INKEY or STK_CMD_GET_INPUT.
 */ 
interface nsIDOMMozStkCmdGetInputParam : nsIDOMMozStkCmdParameter
{
  readonly attribute nsIDOMMozStkInput input;
};

/**
 * Used as command parameter when typeOfCommand in nsIDOMMozStkCommand is 
 * STK_CMD_LAUNCH_BROWSER.
 */
/* TODO
interface nsIDOMMozStkCmdLaunchBrowserParam : nsIDOMMozStkCmdParameter
{

};
*/

/**
 * Used as command parameter when typeOfCommand in nsIDOMMozStkCommand is 
 * STK_CMD_SET_UP_CALL.
 */
/* TODO
interface nsIDOMMozStkCmdSetupCallParam : nsIDOMMozStkCmdParameter
{

};
*/

/**
 * Used as command parameter when typeOfCommand in nsIDOMMozStkCommand is 
 * STK_CMD_PLAY_TONE.
 */
/*
interface nsIDOMMozStkCmdPlayToneParam : nsIDOMMozStkCmdParameter
{

};
*/

interface nsIDOMMozStkCmdDetails : nsIDOMMozStkConstants 
{
  /**
   * 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 STK_CMD_*.
   */  
  readonly attribute unsigned short typeOfCommand; 

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

interface nsIDOMMozStkCommand : nsIDOMMozStkConstants 
{
  /**
   * 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
};

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

interface nsIDOMMozStkResponse : nsIDOMMozStkConstants 
{
  /**
   * 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 menu item selected by user.
   */ 
  attribute unsigned short  menuSelection;

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