gecko/dom/icc/interfaces/nsIDOMIccManager.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsIDOMEventTarget.idl"
#include "SimToolKit.idl"

interface nsIDOMDOMRequest;
interface nsIDOMEventListener;
interface nsIDOMMozIccInfo;

[scriptable, builtinclass, uuid(50782fe0-4185-4471-a374-e362b73febdb)]
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_PROVIDE_LOCAL_INFO    = 0x26;
  const unsigned short STK_CMD_TIMER_MANAGEMENT      = 0x27;
  const unsigned short STK_CMD_SET_UP_IDLE_MODE_TEXT = 0x28;
  const unsigned short STK_CMD_OPEN_CHANNEL          = 0x30;
  const unsigned short STK_CMD_CLOSE_CHANNEL         = 0x31;
  const unsigned short STK_CMD_RECEIVE_DATA          = 0x32;
  const unsigned short STK_CMD_SEND_DATA             = 0x33;

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

  /**
   * Local Information list
   *
   * @see TS 102.223, clause 8.6
   */
  const unsigned short STK_LOCAL_INFO_LOCATION_INFO  = 0x00;
  const unsigned short STK_LOCAL_INFO_IMEI           = 0x01;
  const unsigned short STK_LOCAL_INFO_DATE_TIME_ZONE = 0x03;
  const unsigned short STK_LOCAL_INFO_LANGUAGE       = 0x04;

   /**
   * Timer Management
   */
  const unsigned short STK_TIMER_START             = 0x00;
  const unsigned short STK_TIMER_DEACTIVATE        = 0x01;
  const unsigned short STK_TIMER_GET_CURRENT_VALUE = 0x02;

  /**
   * Browser Termination Cause
   */
  const unsigned short STK_BROWSER_TERMINATION_CAUSE_USER  = 0x00;
  const unsigned short STK_BROWSER_TERMINATION_CAUSE_ERROR = 0x01;

  /**
   * 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 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 the "Timer Expiration" Envelope command to ICC for TIMER MANAGEMENT.
   *
   * @param timer
   *        The identifier and value for a timer.
   *        timerId: Identifier of the timer that has expired.
   *        timerValue: Different between the time when this command is issued
   *                    and when the timer was initially started.
   *        @see MozStkTimer
   */
  void sendStkTimerExpiration(in jsval timer);

  /**
   * 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
   *        - MozStkLanguageSelectionEvent
   *        - MozStkGeneralEvent
   *        - MozStkBrowserTerminationEvent
   */
  void sendStkEventDownload(in jsval event);

  /**
   * The 'stkcommand' event is notified whenever STK Proactive Command is
   * issued from ICC.
   */
  [implicit_jscontext] attribute jsval onstkcommand;

  /**
   * 'stksessionend' event is notified whenever STK Session is terminated by
   * ICC.
   */
  [implicit_jscontext] attribute jsval onstksessionend;

  // UICC Card Information.

  /**
   * Information stored in the device's ICC card.
   *
   * Null if the card is not detected.
   */
  readonly attribute nsIDOMMozIccInfo iccInfo;

  /**
   * The 'iccinfochange' event is notified whenever the icc info object
   * changes.
   */
  [implicit_jscontext] attribute jsval oniccinfochange;

  // UICC Card State.

  /**
   * Indicates the state of the device's ICC card.
   *
   * Possible values: null, 'illegal', 'unknown', 'absent', 'pinRequired',
   * 'pukRequired', 'personalizationInProgress', 'networkLocked',
   * 'corporateLocked', 'serviceProviderLocked', 'networkPukRequired',
   * 'corporatePukRequired', 'serviceProviderPukRequired',
   * 'personalizationReady', 'ready', 'permanentBlocked'.
   */
  readonly attribute DOMString cardState;

  /**
   * The 'cardstatechange' event is notified when the 'cardState' attribute
   * changes value.
   */
  [implicit_jscontext] attribute jsval oncardstatechange;

  // UICC Card Lock interfaces.

  /**
   * Find out about the status of an ICC lock (e.g. the PIN lock).
   *
   * @param lockType
   *        Identifies the lock type, e.g. "pin" for the PIN lock, "fdn" for
   *        the FDN lock.
   *
   * @return a DOM Request.
   *         The request's result will be an object containing
   *         information about the specified lock's status,
   *         e.g. {lockType: "pin", enabled: true}.
   */
  nsIDOMDOMRequest getCardLock(in DOMString lockType);

  /**
   * Unlock a card lock.
   *
   * @param info
   *        An object containing the information necessary to unlock
   *        the given lock. At a minimum, this object must have a
   *        "lockType" attribute which specifies the type of lock, e.g.
   *        "pin" for the PIN lock. Other attributes are dependent on
   *        the lock type.
   *
   * Examples:
   *
   * (1) Unlocking the PIN:
   *
   *   unlockCardLock({lockType: "pin",
   *                   pin: "..."});
   *
   * (2) Unlocking the PUK and supplying a new PIN:
   *
   *   unlockCardLock({lockType: "puk",
   *                   puk: "...",
   *                   newPin: "..."});
   *
   * (3) Network depersonalization. Unlocking the network control key (NCK).
   *
   *   unlockCardLock({lockType: "nck",
   *                   pin: "..."});
   *
   * (4) Corporate depersonalization. Unlocking the corporate control key (CCK).
   *
   *   unlockCardLock({lockType: "cck",
   *                   pin: "..."});
   *
   * (5) Service Provider depersonalization. Unlocking the service provider
   *     control key (SPCK).
   *
   *   unlockCardLock({lockType: "spck",
   *                   pin: "..."});
   *
   * (6) Network PUK depersonalization. Unlocking the network control key (NCK).
   *
   *   unlockCardLock({lockType: "nckPuk",
   *                   puk: "..."});
   *
   * (7) Corporate PUK depersonalization. Unlocking the corporate control key
   *     (CCK).
   *
   *   unlockCardLock({lockType: "cckPuk",
   *                   puk: "..."});
   *
   * (8) Service Provider PUK depersonalization. Unlocking the service provider
   *     control key (SPCK).
   *
   *   unlockCardLock({lockType: "spckPuk",
   *                   puk: "..."});
   *
   * @return a nsIDOMDOMRequest.
   *         The request's result will be an object containing
   *         information about the unlock operation.
   *
   * Examples:
   *
   * (1) Unlocking failed:
   *
   *     {
   *       lockType:   "pin",
   *       success:    false,
   *       retryCount: 2
   *     }
   *
   * (2) Unlocking succeeded:
   *
   *     {
   *       lockType:  "pin",
   *       success:   true
   *     }
   */
  nsIDOMDOMRequest unlockCardLock(in jsval info);

  /**
   * Modify the state of a card lock.
   *
   * @param info
   *        An object containing information about the lock and
   *        how to modify its state. At a minimum, this object
   *        must have a "lockType" attribute which specifies the
   *        type of lock, e.g. "pin" for the PIN lock. Other
   *        attributes are dependent on the lock type.
   *
   * Examples:
   *
   * (1a) Disabling the PIN lock:
   *
   *   setCardLock({lockType: "pin",
   *                pin: "...",
   *                enabled: false});
   *
   * (1b) Disabling the FDN lock:
   *
   *   setCardLock({lockType: "fdn",
   *                pin2: "...",
   *                enabled: false});
   *
   * (2) Changing the PIN:
   *
   *   setCardLock({lockType: "pin",
   *                pin: "...",
   *                newPin: "..."});
   *
   * @return a nsIDOMDOMRequest.
   *         The request's result will be an object containing
   *         information about the operation.
   *
   * Examples:
   *
   * (1) Enabling/Disabling card lock failed or change card lock failed.
   *
   *     {
   *       lockType: "pin",
   *       success: false,
   *       retryCount: 2
   *     }
   *
   * (2) Enabling/Disabling card lock succeed or change card lock succeed.
   *
   *     {
   *       lockType: "pin",
   *       success: true
   *     }
   */
  nsIDOMDOMRequest setCardLock(in jsval info);

  /**
   * Retrieve the number of remaining tries for unlocking the card.
   *
   * @param lockType
   *        Identifies the lock type, e.g. "pin" for the PIN lock, "puk" for
   *        the PUK lock.
   *
   * @return a DOM Request.
   *         If the lock type is "pin", or "puk", the request's result will be
   *         an object containing the number of retries for the specified
   *         lock. For any other lock type, the result is undefined.
   */
  nsIDOMDOMRequest getCardLockRetryCount(in DOMString lockType);

  // UICC Phonebook Interfaces.

  /**
   * Read ICC contacts.
   *
   * @param contactType
   *        One of type as below,
   *        - 'adn': Abbreviated Dialling Number
   *        - 'fdn': Fixed Dialling Number
   */
  nsIDOMDOMRequest readContacts(in DOMString contactType);

  /**
   * Update ICC Phonebook contact.
   *
   * @param contactType
   *        One of type as below,
   *        - 'adn': Abbreviated Dialling Number
   *        - 'fdn': Fixed Dialling Number
   * @param contact
   *        The contact will be updated in ICC
   * @param [optional] pin2
   *        PIN2 is only required for 'fdn'.
   */
  nsIDOMDOMRequest updateContact(in DOMString contactType,
                                 in jsval contact,
                                 [optional] in DOMString pin2);

  // End of UICC Phonebook Interfaces.

  // UICC Secure Element Interfaces

  /**
   * A secure element is a smart card chip that can hold
   * several different applications with the necessary security.
   * The most known secure element is the Universal Integrated Circuit Card (UICC)
   */

  /**
   * Send request to open a logical channel defined by its
   * application identifier (AID)
   *
   * @param aid
   *        The Application Identifier of the Applet to be selected on this channel
   * return value : An instance of Channel (channelID) if available or null.
   */
  nsIDOMDOMRequest iccOpenChannel(in DOMString aid);

  /**
   * Interface, used to communicate with an applet through the
   * Application Data Protocol Units (APDUs) and is
   * used for all data that is exchanged between the UICC card and the terminal (ME).
   *
   * @param channel
   *        The Application Identifier of the Applet to which APDU is directed
   * @param apdu
   *        Application Protocol Data Unit
   * return value : Response APDU
   */
  nsIDOMDOMRequest iccExchangeAPDU(in long channel, in jsval apdu);

  /**
   * Send request to close the selected logical channel identified by its
   * application identifier (AID)
   *
   * @param aid
   *        The Application Identifier of the Applet , to be closed
   */
  nsIDOMDOMRequest iccCloseChannel(in long channel);

  // End of UICC Secure Element Interfaces
};