The Tor Browser / file revision

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

 interface MozIccInfo;

 [Pref="dom.icc.enabled"]

 interface MozIcc : EventTarget

 {

   // Integrated Circuit Card Information.

   /**

    * Information stored in the device's ICC.

    *

    * Once the ICC becomes undetectable, iccinfochange event will be notified.

    * Also, the attribute is set to null and this MozIcc object becomes invalid.

    * Calling asynchronous functions raises exception then.

    */

   readonly attribute MozIccInfo? iccInfo;

   /**

    * The 'iccinfochange' event is notified whenever the icc info object

    * changes.

    */

   attribute EventHandler oniccinfochange;

   // Integrated Circuit Card State.

   /**

    * Indicates the state of the device's ICC.

    *

    * Possible values: 'illegal', 'unknown', 'pinRequired', 'pukRequired',

    * 'personalizationInProgress', 'networkLocked', 'network1Locked',

    * 'network2Locked', 'hrpdNetworkLocked', 'corporateLocked',

    * 'serviceProviderLocked', 'ruimCorporateLocked', 'ruimServiceProviderLocked',

    * 'networkPukRequired', 'network1PukRequired', 'network2PukRequired',

    * 'hrpdNetworkPukRequired', 'corporatePukRequired',

    * 'serviceProviderPukRequired', 'ruimCorporatePukRequired',

    * 'ruimServiceProviderPukRequired', 'personalizationReady', 'ready',

    * 'permanentBlocked'.

    *

    * Once the ICC becomes undetectable, cardstatechange event will be notified.

    * Also, the attribute is set to null and this MozIcc object becomes invalid.

    * Calling asynchronous functions raises exception then.

    */

   readonly attribute DOMString? cardState;

   /**

    * The 'cardstatechange' event is notified when the 'cardState' attribute

    * changes value.

    */

   attribute EventHandler oncardstatechange;

   // Integrated Circuit Card STK.

   /**

    * 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.

    */

   [Throws]

   void sendStkResponse(any command, any 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.

    */

   [Throws]

   void sendStkMenuSelection(unsigned short itemIdentifier,

                             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

    */

   [Throws]

   void sendStkTimerExpiration(any 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

    */

   [Throws]

   void sendStkEventDownload(any event);

   /**

    * The 'stkcommand' event is notified whenever STK proactive command is

    * issued from ICC.

    */

   attribute EventHandler onstkcommand;

   /**

    * 'stksessionend' event is notified whenever STK session is terminated by

    * ICC.

    */

   attribute EventHandler onstksessionend;

   // Integrated Circuit 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 DOMRequest.

    *         The request's result will be an object containing

    *         information about the specified lock's status,

    *         e.g. {lockType: "pin", enabled: true}.

    */

   [Throws]

   nsISupports getCardLock(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) Network type 1 depersonalization. Unlocking the network type 1 control

    *     key (NCK1).

    *

    *   unlockCardLock({lockType: "nck1",

    *                   pin: "..."});

    *

    * (5) Network type 2 depersonalization. Unlocking the network type 2 control

    *     key (NCK2).

    *

    *   unlockCardLock({lockType: "nck2",

    *                   pin: "..."});

    *

    * (6) HRPD network depersonalization. Unlocking the HRPD network control key

    *     (HNCK).

    *

    *   unlockCardLock({lockType: "hnck",

    *                   pin: "..."});

    *

    * (7) Corporate depersonalization. Unlocking the corporate control key (CCK).

    *

    *   unlockCardLock({lockType: "cck",

    *                   pin: "..."});

    *

    * (8) Service provider depersonalization. Unlocking the service provider

    *     control key (SPCK).

    *

    *   unlockCardLock({lockType: "spck",

    *                   pin: "..."});

    *

    * (9) RUIM corporate depersonalization. Unlocking the RUIM corporate control

    *     key (RCCK).

    *

    *   unlockCardLock({lockType: "rcck",

    *                   pin: "..."});

    *

    * (10) RUIM service provider depersonalization. Unlocking the RUIM service

    *      provider control key (RSPCK).

    *

    *   unlockCardLock({lockType: "rspck",

    *                   pin: "..."});

    *

    * (11) Network PUK depersonalization. Unlocking the network control key (NCK).

    *

    *   unlockCardLock({lockType: "nckPuk",

    *                   puk: "..."});

    *

    * (12) Network type 1 PUK depersonalization. Unlocking the network type 1

    *      control key (NCK1).

    *

    *   unlockCardLock({lockType: "nck1Puk",

    *                   pin: "..."});

    *

    * (13) Network type 2 PUK depersonalization. Unlocking the Network type 2

    *      control key (NCK2).

    *

    *   unlockCardLock({lockType: "nck2Puk",

    *                   pin: "..."});

    *

    * (14) HRPD network PUK depersonalization. Unlocking the HRPD network control

    *      key (HNCK).

    *

    *   unlockCardLock({lockType: "hnckPuk",

    *                   pin: "..."});

    *

    * (15) Corporate PUK depersonalization. Unlocking the corporate control key

    *      (CCK).

    *

    *   unlockCardLock({lockType: "cckPuk",

    *                   puk: "..."});

    *

    * (16) Service provider PUK depersonalization. Unlocking the service provider

    *      control key (SPCK).

    *

    *   unlockCardLock({lockType: "spckPuk",

    *                   puk: "..."});

    *

    * (17) RUIM corporate PUK depersonalization. Unlocking the RUIM corporate

    *      control key (RCCK).

    *

    *   unlockCardLock({lockType: "rcckPuk",

    *                   puk: "..."});

    *

    * (18) RUIM service provider PUK depersonalization. Unlocking the service

    *      provider control key (SPCK).

    *

    *   unlockCardLock({lockType: "rspckPuk",

    *                   puk: "..."});

    *

    * @return a DOMRequest.

    *         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

    *     }

    */

   [Throws]

   nsISupports unlockCardLock(any 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 DOMRequest.

    *         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

    *     }

    */

   [Throws]

   nsISupports setCardLock(any 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 DOMRequest.

    *         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.

    */

   [Throws]

   nsISupports getCardLockRetryCount(DOMString lockType);

   // Integrated Circuit Card Phonebook Interfaces.

   /**

    * Read ICC contacts.

    *

    * @param contactType

    *        One of type as below,

    *        - 'adn': Abbreviated Dialling Number.

    *        - 'fdn': Fixed Dialling Number.

    *

    * @return a DOMRequest.

    */

   [Throws]

   nsISupports readContacts(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'.

    *

    * @return a DOMRequest.

    */

   [Throws]

   nsISupports updateContact(DOMString contactType,

                            any contact,

                            optional DOMString? pin2 = null);

   // Integrated Circuit Card 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 a DOMRequest.

    *         The request's result will be an instance of channel (channelID)

    *         if available or null.

    */

   [Throws]

   nsISupports iccOpenChannel(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 and the terminal (ME).

    *

    * @param channel

    *        The application identifier of the applet to which APDU is directed.

    * @param apdu

    *        Application protocol data unit.

    *

    * @return a DOMRequest.

    *         The request's result will be response APDU.

    */

   [Throws]

   nsISupports iccExchangeAPDU(long channel, any 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.

    *

    * @return a DOMRequest.

    */

   [Throws]

   nsISupports iccCloseChannel(long channel);

   // Integrated Circuit Card Helpers.

   /**

    * Verify whether the passed data (matchData) matches with some ICC's field

    * according to the mvno type (mvnoType).

    *

    * @param mvnoType

    *        Mvno type to use to compare the match data.

    *        Currently, we only support 'imsi'.

    * @param matchData

    *        Data to be compared with ICC's field.

    *

    * @return a DOMRequest.

    *         The request's result will be a boolean indicating the matching

    *         result.

    *

    * TODO: change param mvnoType to WebIDL enum after Bug 864489 -

    *       B2G RIL: use ipdl as IPC in MozIccManager

    */

   [Throws]

   nsISupports matchMvno(DOMString mvnoType, DOMString matchData);

 };