MozIcc.webidl
/* 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]
DOMRequest 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]
DOMRequest 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]
DOMRequest 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]
DOMRequest 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.
* - 'sdn': Service Dialling Number.
*
* @return a DOMRequest.
*/
[Throws]
DOMRequest 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]
DOMRequest 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]
DOMRequest 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]
DOMRequest 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]
DOMRequest 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]
DOMRequest matchMvno(DOMString mvnoType, DOMString matchData);
};
