diff -r 000000000000 -r 6474c204b198 dom/webidl/MozIcc.webidl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dom/webidl/MozIcc.webidl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,454 @@ +/* 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); +};