1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/webidl/MozIcc.webidl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,454 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this file,
1.6 + * You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +interface MozIccInfo;
1.9 +
1.10 +[Pref="dom.icc.enabled"]
1.11 +interface MozIcc : EventTarget
1.12 +{
1.13 + // Integrated Circuit Card Information.
1.14 +
1.15 + /**
1.16 + * Information stored in the device's ICC.
1.17 + *
1.18 + * Once the ICC becomes undetectable, iccinfochange event will be notified.
1.19 + * Also, the attribute is set to null and this MozIcc object becomes invalid.
1.20 + * Calling asynchronous functions raises exception then.
1.21 + */
1.22 + readonly attribute MozIccInfo? iccInfo;
1.23 +
1.24 + /**
1.25 + * The 'iccinfochange' event is notified whenever the icc info object
1.26 + * changes.
1.27 + */
1.28 + attribute EventHandler oniccinfochange;
1.29 +
1.30 + // Integrated Circuit Card State.
1.31 +
1.32 + /**
1.33 + * Indicates the state of the device's ICC.
1.34 + *
1.35 + * Possible values: 'illegal', 'unknown', 'pinRequired', 'pukRequired',
1.36 + * 'personalizationInProgress', 'networkLocked', 'network1Locked',
1.37 + * 'network2Locked', 'hrpdNetworkLocked', 'corporateLocked',
1.38 + * 'serviceProviderLocked', 'ruimCorporateLocked', 'ruimServiceProviderLocked',
1.39 + * 'networkPukRequired', 'network1PukRequired', 'network2PukRequired',
1.40 + * 'hrpdNetworkPukRequired', 'corporatePukRequired',
1.41 + * 'serviceProviderPukRequired', 'ruimCorporatePukRequired',
1.42 + * 'ruimServiceProviderPukRequired', 'personalizationReady', 'ready',
1.43 + * 'permanentBlocked'.
1.44 + *
1.45 + * Once the ICC becomes undetectable, cardstatechange event will be notified.
1.46 + * Also, the attribute is set to null and this MozIcc object becomes invalid.
1.47 + * Calling asynchronous functions raises exception then.
1.48 + */
1.49 + readonly attribute DOMString? cardState;
1.50 +
1.51 + /**
1.52 + * The 'cardstatechange' event is notified when the 'cardState' attribute
1.53 + * changes value.
1.54 + */
1.55 + attribute EventHandler oncardstatechange;
1.56 +
1.57 + // Integrated Circuit Card STK.
1.58 +
1.59 + /**
1.60 + * Send the response back to ICC after an attempt to execute STK proactive
1.61 + * Command.
1.62 + *
1.63 + * @param command
1.64 + * Command received from ICC. See MozStkCommand.
1.65 + * @param response
1.66 + * The response that will be sent to ICC.
1.67 + * @see MozStkResponse for the detail of response.
1.68 + */
1.69 + [Throws]
1.70 + void sendStkResponse(any command, any response);
1.71 +
1.72 + /**
1.73 + * Send the "Menu Selection" envelope command to ICC for menu selection.
1.74 + *
1.75 + * @param itemIdentifier
1.76 + * The identifier of the item selected by user.
1.77 + * @param helpRequested
1.78 + * true if user requests to provide help information, false otherwise.
1.79 + */
1.80 + [Throws]
1.81 + void sendStkMenuSelection(unsigned short itemIdentifier,
1.82 + boolean helpRequested);
1.83 +
1.84 + /**
1.85 + * Send the "Timer Expiration" envelope command to ICC for TIMER MANAGEMENT.
1.86 + *
1.87 + * @param timer
1.88 + * The identifier and value for a timer.
1.89 + * timerId: Identifier of the timer that has expired.
1.90 + * timerValue: Different between the time when this command is issued
1.91 + * and when the timer was initially started.
1.92 + * @see MozStkTimer
1.93 + */
1.94 + [Throws]
1.95 + void sendStkTimerExpiration(any timer);
1.96 +
1.97 + /**
1.98 + * Send "Event Download" envelope command to ICC.
1.99 + * ICC will not respond with any data for this command.
1.100 + *
1.101 + * @param event
1.102 + * one of events below:
1.103 + * - MozStkLocationEvent
1.104 + * - MozStkCallEvent
1.105 + * - MozStkLanguageSelectionEvent
1.106 + * - MozStkGeneralEvent
1.107 + * - MozStkBrowserTerminationEvent
1.108 + */
1.109 + [Throws]
1.110 + void sendStkEventDownload(any event);
1.111 +
1.112 + /**
1.113 + * The 'stkcommand' event is notified whenever STK proactive command is
1.114 + * issued from ICC.
1.115 + */
1.116 + attribute EventHandler onstkcommand;
1.117 +
1.118 + /**
1.119 + * 'stksessionend' event is notified whenever STK session is terminated by
1.120 + * ICC.
1.121 + */
1.122 + attribute EventHandler onstksessionend;
1.123 +
1.124 + // Integrated Circuit Card Lock interfaces.
1.125 +
1.126 + /**
1.127 + * Find out about the status of an ICC lock (e.g. the PIN lock).
1.128 + *
1.129 + * @param lockType
1.130 + * Identifies the lock type, e.g. "pin" for the PIN lock, "fdn" for
1.131 + * the FDN lock.
1.132 + *
1.133 + * @return a DOMRequest.
1.134 + * The request's result will be an object containing
1.135 + * information about the specified lock's status,
1.136 + * e.g. {lockType: "pin", enabled: true}.
1.137 + */
1.138 + [Throws]
1.139 + nsISupports getCardLock(DOMString lockType);
1.140 +
1.141 + /**
1.142 + * Unlock a card lock.
1.143 + *
1.144 + * @param info
1.145 + * An object containing the information necessary to unlock
1.146 + * the given lock. At a minimum, this object must have a
1.147 + * "lockType" attribute which specifies the type of lock, e.g.
1.148 + * "pin" for the PIN lock. Other attributes are dependent on
1.149 + * the lock type.
1.150 + *
1.151 + * Examples:
1.152 + *
1.153 + * (1) Unlocking the PIN:
1.154 + *
1.155 + * unlockCardLock({lockType: "pin",
1.156 + * pin: "..."});
1.157 + *
1.158 + * (2) Unlocking the PUK and supplying a new PIN:
1.159 + *
1.160 + * unlockCardLock({lockType: "puk",
1.161 + * puk: "...",
1.162 + * newPin: "..."});
1.163 + *
1.164 + * (3) Network depersonalization. Unlocking the network control key (NCK).
1.165 + *
1.166 + * unlockCardLock({lockType: "nck",
1.167 + * pin: "..."});
1.168 + *
1.169 + * (4) Network type 1 depersonalization. Unlocking the network type 1 control
1.170 + * key (NCK1).
1.171 + *
1.172 + * unlockCardLock({lockType: "nck1",
1.173 + * pin: "..."});
1.174 + *
1.175 + * (5) Network type 2 depersonalization. Unlocking the network type 2 control
1.176 + * key (NCK2).
1.177 + *
1.178 + * unlockCardLock({lockType: "nck2",
1.179 + * pin: "..."});
1.180 + *
1.181 + * (6) HRPD network depersonalization. Unlocking the HRPD network control key
1.182 + * (HNCK).
1.183 + *
1.184 + * unlockCardLock({lockType: "hnck",
1.185 + * pin: "..."});
1.186 + *
1.187 + * (7) Corporate depersonalization. Unlocking the corporate control key (CCK).
1.188 + *
1.189 + * unlockCardLock({lockType: "cck",
1.190 + * pin: "..."});
1.191 + *
1.192 + * (8) Service provider depersonalization. Unlocking the service provider
1.193 + * control key (SPCK).
1.194 + *
1.195 + * unlockCardLock({lockType: "spck",
1.196 + * pin: "..."});
1.197 + *
1.198 + * (9) RUIM corporate depersonalization. Unlocking the RUIM corporate control
1.199 + * key (RCCK).
1.200 + *
1.201 + * unlockCardLock({lockType: "rcck",
1.202 + * pin: "..."});
1.203 + *
1.204 + * (10) RUIM service provider depersonalization. Unlocking the RUIM service
1.205 + * provider control key (RSPCK).
1.206 + *
1.207 + * unlockCardLock({lockType: "rspck",
1.208 + * pin: "..."});
1.209 + *
1.210 + * (11) Network PUK depersonalization. Unlocking the network control key (NCK).
1.211 + *
1.212 + * unlockCardLock({lockType: "nckPuk",
1.213 + * puk: "..."});
1.214 + *
1.215 + * (12) Network type 1 PUK depersonalization. Unlocking the network type 1
1.216 + * control key (NCK1).
1.217 + *
1.218 + * unlockCardLock({lockType: "nck1Puk",
1.219 + * pin: "..."});
1.220 + *
1.221 + * (13) Network type 2 PUK depersonalization. Unlocking the Network type 2
1.222 + * control key (NCK2).
1.223 + *
1.224 + * unlockCardLock({lockType: "nck2Puk",
1.225 + * pin: "..."});
1.226 + *
1.227 + * (14) HRPD network PUK depersonalization. Unlocking the HRPD network control
1.228 + * key (HNCK).
1.229 + *
1.230 + * unlockCardLock({lockType: "hnckPuk",
1.231 + * pin: "..."});
1.232 + *
1.233 + * (15) Corporate PUK depersonalization. Unlocking the corporate control key
1.234 + * (CCK).
1.235 + *
1.236 + * unlockCardLock({lockType: "cckPuk",
1.237 + * puk: "..."});
1.238 + *
1.239 + * (16) Service provider PUK depersonalization. Unlocking the service provider
1.240 + * control key (SPCK).
1.241 + *
1.242 + * unlockCardLock({lockType: "spckPuk",
1.243 + * puk: "..."});
1.244 + *
1.245 + * (17) RUIM corporate PUK depersonalization. Unlocking the RUIM corporate
1.246 + * control key (RCCK).
1.247 + *
1.248 + * unlockCardLock({lockType: "rcckPuk",
1.249 + * puk: "..."});
1.250 + *
1.251 + * (18) RUIM service provider PUK depersonalization. Unlocking the service
1.252 + * provider control key (SPCK).
1.253 + *
1.254 + * unlockCardLock({lockType: "rspckPuk",
1.255 + * puk: "..."});
1.256 + *
1.257 + * @return a DOMRequest.
1.258 + * The request's result will be an object containing
1.259 + * information about the unlock operation.
1.260 + *
1.261 + * Examples:
1.262 + *
1.263 + * (1) Unlocking failed:
1.264 + *
1.265 + * {
1.266 + * lockType: "pin",
1.267 + * success: false,
1.268 + * retryCount: 2
1.269 + * }
1.270 + *
1.271 + * (2) Unlocking succeeded:
1.272 + *
1.273 + * {
1.274 + * lockType: "pin",
1.275 + * success: true
1.276 + * }
1.277 + */
1.278 + [Throws]
1.279 + nsISupports unlockCardLock(any info);
1.280 +
1.281 + /**
1.282 + * Modify the state of a card lock.
1.283 + *
1.284 + * @param info
1.285 + * An object containing information about the lock and
1.286 + * how to modify its state. At a minimum, this object
1.287 + * must have a "lockType" attribute which specifies the
1.288 + * type of lock, e.g. "pin" for the PIN lock. Other
1.289 + * attributes are dependent on the lock type.
1.290 + *
1.291 + * Examples:
1.292 + *
1.293 + * (1a) Disabling the PIN lock:
1.294 + *
1.295 + * setCardLock({lockType: "pin",
1.296 + * pin: "...",
1.297 + * enabled: false});
1.298 + *
1.299 + * (1b) Disabling the FDN lock:
1.300 + *
1.301 + * setCardLock({lockType: "fdn",
1.302 + * pin2: "...",
1.303 + * enabled: false});
1.304 + *
1.305 + * (2) Changing the PIN:
1.306 + *
1.307 + * setCardLock({lockType: "pin",
1.308 + * pin: "...",
1.309 + * newPin: "..."});
1.310 + *
1.311 + * @return a DOMRequest.
1.312 + * The request's result will be an object containing
1.313 + * information about the operation.
1.314 + *
1.315 + * Examples:
1.316 + *
1.317 + * (1) Enabling/Disabling card lock failed or change card lock failed.
1.318 + *
1.319 + * {
1.320 + * lockType: "pin",
1.321 + * success: false,
1.322 + * retryCount: 2
1.323 + * }
1.324 + *
1.325 + * (2) Enabling/Disabling card lock succeed or change card lock succeed.
1.326 + *
1.327 + * {
1.328 + * lockType: "pin",
1.329 + * success: true
1.330 + * }
1.331 + */
1.332 + [Throws]
1.333 + nsISupports setCardLock(any info);
1.334 +
1.335 + /**
1.336 + * Retrieve the number of remaining tries for unlocking the card.
1.337 + *
1.338 + * @param lockType
1.339 + * Identifies the lock type, e.g. "pin" for the PIN lock, "puk" for
1.340 + * the PUK lock.
1.341 + *
1.342 + * @return a DOMRequest.
1.343 + * If the lock type is "pin", or "puk", the request's result will be
1.344 + * an object containing the number of retries for the specified
1.345 + * lock. For any other lock type, the result is undefined.
1.346 + */
1.347 + [Throws]
1.348 + nsISupports getCardLockRetryCount(DOMString lockType);
1.349 +
1.350 + // Integrated Circuit Card Phonebook Interfaces.
1.351 +
1.352 + /**
1.353 + * Read ICC contacts.
1.354 + *
1.355 + * @param contactType
1.356 + * One of type as below,
1.357 + * - 'adn': Abbreviated Dialling Number.
1.358 + * - 'fdn': Fixed Dialling Number.
1.359 + *
1.360 + * @return a DOMRequest.
1.361 + */
1.362 + [Throws]
1.363 + nsISupports readContacts(DOMString contactType);
1.364 +
1.365 + /**
1.366 + * Update ICC Phonebook contact.
1.367 + *
1.368 + * @param contactType
1.369 + * One of type as below,
1.370 + * - 'adn': Abbreviated Dialling Number.
1.371 + * - 'fdn': Fixed Dialling Number.
1.372 + * @param contact
1.373 + * The contact will be updated in ICC.
1.374 + * @param [optional] pin2
1.375 + * PIN2 is only required for 'fdn'.
1.376 + *
1.377 + * @return a DOMRequest.
1.378 + */
1.379 + [Throws]
1.380 + nsISupports updateContact(DOMString contactType,
1.381 + any contact,
1.382 + optional DOMString? pin2 = null);
1.383 +
1.384 + // Integrated Circuit Card Secure Element Interfaces.
1.385 +
1.386 + /**
1.387 + * A secure element is a smart card chip that can hold
1.388 + * several different applications with the necessary security.
1.389 + * The most known secure element is the Universal Integrated Circuit Card
1.390 + * (UICC).
1.391 + */
1.392 +
1.393 + /**
1.394 + * Send request to open a logical channel defined by its
1.395 + * application identifier (AID).
1.396 + *
1.397 + * @param aid
1.398 + * The application identifier of the applet to be selected on this
1.399 + * channel.
1.400 + *
1.401 + * @return a DOMRequest.
1.402 + * The request's result will be an instance of channel (channelID)
1.403 + * if available or null.
1.404 + */
1.405 + [Throws]
1.406 + nsISupports iccOpenChannel(DOMString aid);
1.407 +
1.408 + /**
1.409 + * Interface, used to communicate with an applet through the
1.410 + * application data protocol units (APDUs) and is
1.411 + * used for all data that is exchanged between the UICC and the terminal (ME).
1.412 + *
1.413 + * @param channel
1.414 + * The application identifier of the applet to which APDU is directed.
1.415 + * @param apdu
1.416 + * Application protocol data unit.
1.417 + *
1.418 + * @return a DOMRequest.
1.419 + * The request's result will be response APDU.
1.420 + */
1.421 + [Throws]
1.422 + nsISupports iccExchangeAPDU(long channel, any apdu);
1.423 +
1.424 + /**
1.425 + * Send request to close the selected logical channel identified by its
1.426 + * application identifier (AID).
1.427 + *
1.428 + * @param aid
1.429 + * The application identifier of the applet, to be closed.
1.430 + *
1.431 + * @return a DOMRequest.
1.432 + */
1.433 + [Throws]
1.434 + nsISupports iccCloseChannel(long channel);
1.435 +
1.436 + // Integrated Circuit Card Helpers.
1.437 +
1.438 + /**
1.439 + * Verify whether the passed data (matchData) matches with some ICC's field
1.440 + * according to the mvno type (mvnoType).
1.441 + *
1.442 + * @param mvnoType
1.443 + * Mvno type to use to compare the match data.
1.444 + * Currently, we only support 'imsi'.
1.445 + * @param matchData
1.446 + * Data to be compared with ICC's field.
1.447 + *
1.448 + * @return a DOMRequest.
1.449 + * The request's result will be a boolean indicating the matching
1.450 + * result.
1.451 + *
1.452 + * TODO: change param mvnoType to WebIDL enum after Bug 864489 -
1.453 + * B2G RIL: use ipdl as IPC in MozIccManager
1.454 + */
1.455 + [Throws]
1.456 + nsISupports matchMvno(DOMString mvnoType, DOMString matchData);
1.457 +};
