dom/webidl/MozIcc.webidl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 interface MozIccInfo;
   6
   7 [Pref="dom.icc.enabled"]
   8 interface MozIcc : EventTarget
   9 {
  10   // Integrated Circuit Card Information.
  11
  12   /**
  13    * Information stored in the device's ICC.
  14    *
  15    * Once the ICC becomes undetectable, iccinfochange event will be notified.
  16    * Also, the attribute is set to null and this MozIcc object becomes invalid.
  17    * Calling asynchronous functions raises exception then.
  18    */
  19   readonly attribute MozIccInfo? iccInfo;
  20
  21   /**
  22    * The 'iccinfochange' event is notified whenever the icc info object
  23    * changes.
  24    */
  25   attribute EventHandler oniccinfochange;
  26
  27   // Integrated Circuit Card State.
  28
  29   /**
  30    * Indicates the state of the device's ICC.
  31    *
  32    * Possible values: 'illegal', 'unknown', 'pinRequired', 'pukRequired',
  33    * 'personalizationInProgress', 'networkLocked', 'network1Locked',
  34    * 'network2Locked', 'hrpdNetworkLocked', 'corporateLocked',
  35    * 'serviceProviderLocked', 'ruimCorporateLocked', 'ruimServiceProviderLocked',
  36    * 'networkPukRequired', 'network1PukRequired', 'network2PukRequired',
  37    * 'hrpdNetworkPukRequired', 'corporatePukRequired',
  38    * 'serviceProviderPukRequired', 'ruimCorporatePukRequired',
  39    * 'ruimServiceProviderPukRequired', 'personalizationReady', 'ready',
  40    * 'permanentBlocked'.
  41    *
  42    * Once the ICC becomes undetectable, cardstatechange event will be notified.
  43    * Also, the attribute is set to null and this MozIcc object becomes invalid.
  44    * Calling asynchronous functions raises exception then.
  45    */
  46   readonly attribute DOMString? cardState;
  47
  48   /**
  49    * The 'cardstatechange' event is notified when the 'cardState' attribute
  50    * changes value.
  51    */
  52   attribute EventHandler oncardstatechange;
  53
  54   // Integrated Circuit Card STK.
  55
  56   /**
  57    * Send the response back to ICC after an attempt to execute STK proactive
  58    * Command.
  59    *
  60    * @param command
  61    *        Command received from ICC. See MozStkCommand.
  62    * @param response
  63    *        The response that will be sent to ICC.
  64    *        @see MozStkResponse for the detail of response.
  65    */
  66   [Throws]
  67   void sendStkResponse(any command, any response);
  68
  69   /**
  70    * Send the "Menu Selection" envelope command to ICC for menu selection.
  71    *
  72    * @param itemIdentifier
  73    *        The identifier of the item selected by user.
  74    * @param helpRequested
  75    *        true if user requests to provide help information, false otherwise.
  76    */
  77   [Throws]
  78   void sendStkMenuSelection(unsigned short itemIdentifier,
  79                             boolean helpRequested);
  80
  81   /**
  82    * Send the "Timer Expiration" envelope command to ICC for TIMER MANAGEMENT.
  83    *
  84    * @param timer
  85    *        The identifier and value for a timer.
  86    *        timerId: Identifier of the timer that has expired.
  87    *        timerValue: Different between the time when this command is issued
  88    *                    and when the timer was initially started.
  89    *        @see MozStkTimer
  90    */
  91   [Throws]
  92   void sendStkTimerExpiration(any timer);
  93
  94   /**
  95    * Send "Event Download" envelope command to ICC.
  96    * ICC will not respond with any data for this command.
  97    *
  98    * @param event
  99    *        one of events below:
 100    *        - MozStkLocationEvent
 101    *        - MozStkCallEvent
 102    *        - MozStkLanguageSelectionEvent
 103    *        - MozStkGeneralEvent
 104    *        - MozStkBrowserTerminationEvent
 105    */
 106   [Throws]
 107   void sendStkEventDownload(any event);
 108
 109   /**
 110    * The 'stkcommand' event is notified whenever STK proactive command is
 111    * issued from ICC.
 112    */
 113   attribute EventHandler onstkcommand;
 114
 115   /**
 116    * 'stksessionend' event is notified whenever STK session is terminated by
 117    * ICC.
 118    */
 119   attribute EventHandler onstksessionend;
 120
 121   // Integrated Circuit Card Lock interfaces.
 122
 123   /**
 124    * Find out about the status of an ICC lock (e.g. the PIN lock).
 125    *
 126    * @param lockType
 127    *        Identifies the lock type, e.g. "pin" for the PIN lock, "fdn" for
 128    *        the FDN lock.
 129    *
 130    * @return a DOMRequest.
 131    *         The request's result will be an object containing
 132    *         information about the specified lock's status,
 133    *         e.g. {lockType: "pin", enabled: true}.
 134    */
 135   [Throws]
 136   DOMRequest getCardLock(DOMString lockType);
 137
 138   /**
 139    * Unlock a card lock.
 140    *
 141    * @param info
 142    *        An object containing the information necessary to unlock
 143    *        the given lock. At a minimum, this object must have a
 144    *        "lockType" attribute which specifies the type of lock, e.g.
 145    *        "pin" for the PIN lock. Other attributes are dependent on
 146    *        the lock type.
 147    *
 148    * Examples:
 149    *
 150    * (1) Unlocking the PIN:
 151    *
 152    *   unlockCardLock({lockType: "pin",
 153    *                   pin: "..."});
 154    *
 155    * (2) Unlocking the PUK and supplying a new PIN:
 156    *
 157    *   unlockCardLock({lockType: "puk",
 158    *                   puk: "...",
 159    *                   newPin: "..."});
 160    *
 161    * (3) Network depersonalization. Unlocking the network control key (NCK).
 162    *
 163    *   unlockCardLock({lockType: "nck",
 164    *                   pin: "..."});
 165    *
 166    * (4) Network type 1 depersonalization. Unlocking the network type 1 control
 167    *     key (NCK1).
 168    *
 169    *   unlockCardLock({lockType: "nck1",
 170    *                   pin: "..."});
 171    *
 172    * (5) Network type 2 depersonalization. Unlocking the network type 2 control
 173    *     key (NCK2).
 174    *
 175    *   unlockCardLock({lockType: "nck2",
 176    *                   pin: "..."});
 177    *
 178    * (6) HRPD network depersonalization. Unlocking the HRPD network control key
 179    *     (HNCK).
 180    *
 181    *   unlockCardLock({lockType: "hnck",
 182    *                   pin: "..."});
 183    *
 184    * (7) Corporate depersonalization. Unlocking the corporate control key (CCK).
 185    *
 186    *   unlockCardLock({lockType: "cck",
 187    *                   pin: "..."});
 188    *
 189    * (8) Service provider depersonalization. Unlocking the service provider
 190    *     control key (SPCK).
 191    *
 192    *   unlockCardLock({lockType: "spck",
 193    *                   pin: "..."});
 194    *
 195    * (9) RUIM corporate depersonalization. Unlocking the RUIM corporate control
 196    *     key (RCCK).
 197    *
 198    *   unlockCardLock({lockType: "rcck",
 199    *                   pin: "..."});
 200    *
 201    * (10) RUIM service provider depersonalization. Unlocking the RUIM service
 202    *      provider control key (RSPCK).
 203    *
 204    *   unlockCardLock({lockType: "rspck",
 205    *                   pin: "..."});
 206    *
 207    * (11) Network PUK depersonalization. Unlocking the network control key (NCK).
 208    *
 209    *   unlockCardLock({lockType: "nckPuk",
 210    *                   puk: "..."});
 211    *
 212    * (12) Network type 1 PUK depersonalization. Unlocking the network type 1
 213    *      control key (NCK1).
 214    *
 215    *   unlockCardLock({lockType: "nck1Puk",
 216    *                   pin: "..."});
 217    *
 218    * (13) Network type 2 PUK depersonalization. Unlocking the Network type 2
 219    *      control key (NCK2).
 220    *
 221    *   unlockCardLock({lockType: "nck2Puk",
 222    *                   pin: "..."});
 223    *
 224    * (14) HRPD network PUK depersonalization. Unlocking the HRPD network control
 225    *      key (HNCK).
 226    *
 227    *   unlockCardLock({lockType: "hnckPuk",
 228    *                   pin: "..."});
 229    *
 230    * (15) Corporate PUK depersonalization. Unlocking the corporate control key
 231    *      (CCK).
 232    *
 233    *   unlockCardLock({lockType: "cckPuk",
 234    *                   puk: "..."});
 235    *
 236    * (16) Service provider PUK depersonalization. Unlocking the service provider
 237    *      control key (SPCK).
 238    *
 239    *   unlockCardLock({lockType: "spckPuk",
 240    *                   puk: "..."});
 241    *
 242    * (17) RUIM corporate PUK depersonalization. Unlocking the RUIM corporate
 243    *      control key (RCCK).
 244    *
 245    *   unlockCardLock({lockType: "rcckPuk",
 246    *                   puk: "..."});
 247    *
 248    * (18) RUIM service provider PUK depersonalization. Unlocking the service
 249    *      provider control key (SPCK).
 250    *
 251    *   unlockCardLock({lockType: "rspckPuk",
 252    *                   puk: "..."});
 253    *
 254    * @return a DOMRequest.
 255    *         The request's result will be an object containing
 256    *         information about the unlock operation.
 257    *
 258    * Examples:
 259    *
 260    * (1) Unlocking failed:
 261    *
 262    *     {
 263    *       lockType:   "pin",
 264    *       success:    false,
 265    *       retryCount: 2
 266    *     }
 267    *
 268    * (2) Unlocking succeeded:
 269    *
 270    *     {
 271    *       lockType:  "pin",
 272    *       success:   true
 273    *     }
 274    */
 275   [Throws]
 276   DOMRequest unlockCardLock(any info);
 277
 278   /**
 279    * Modify the state of a card lock.
 280    *
 281    * @param info
 282    *        An object containing information about the lock and
 283    *        how to modify its state. At a minimum, this object
 284    *        must have a "lockType" attribute which specifies the
 285    *        type of lock, e.g. "pin" for the PIN lock. Other
 286    *        attributes are dependent on the lock type.
 287    *
 288    * Examples:
 289    *
 290    * (1a) Disabling the PIN lock:
 291    *
 292    *   setCardLock({lockType: "pin",
 293    *                pin: "...",
 294    *                enabled: false});
 295    *
 296    * (1b) Disabling the FDN lock:
 297    *
 298    *   setCardLock({lockType: "fdn",
 299    *                pin2: "...",
 300    *                enabled: false});
 301    *
 302    * (2) Changing the PIN:
 303    *
 304    *   setCardLock({lockType: "pin",
 305    *                pin: "...",
 306    *                newPin: "..."});
 307    *
 308    * @return a DOMRequest.
 309    *         The request's result will be an object containing
 310    *         information about the operation.
 311    *
 312    * Examples:
 313    *
 314    * (1) Enabling/Disabling card lock failed or change card lock failed.
 315    *
 316    *     {
 317    *       lockType: "pin",
 318    *       success: false,
 319    *       retryCount: 2
 320    *     }
 321    *
 322    * (2) Enabling/Disabling card lock succeed or change card lock succeed.
 323    *
 324    *     {
 325    *       lockType: "pin",
 326    *       success: true
 327    *     }
 328    */
 329   [Throws]
 330   DOMRequest setCardLock(any info);
 331
 332   /**
 333    * Retrieve the number of remaining tries for unlocking the card.
 334    *
 335    * @param lockType
 336    *        Identifies the lock type, e.g. "pin" for the PIN lock, "puk" for
 337    *        the PUK lock.
 338    *
 339    * @return a DOMRequest.
 340    *         If the lock type is "pin", or "puk", the request's result will be
 341    *         an object containing the number of retries for the specified
 342    *         lock. For any other lock type, the result is undefined.
 343    */
 344   [Throws]
 345   DOMRequest getCardLockRetryCount(DOMString lockType);
 346
 347   // Integrated Circuit Card Phonebook Interfaces.
 348
 349   /**
 350    * Read ICC contacts.
 351    *
 352    * @param contactType
 353    *        One of type as below,
 354    *        - 'adn': Abbreviated Dialling Number.
 355    *        - 'fdn': Fixed Dialling Number.
 356    *        - 'sdn': Service Dialling Number.
 357    *
 358    * @return a DOMRequest.
 359    */
 360   [Throws]
 361   DOMRequest readContacts(DOMString contactType);
 362
 363   /**
 364    * Update ICC Phonebook contact.
 365    *
 366    * @param contactType
 367    *        One of type as below,
 368    *        - 'adn': Abbreviated Dialling Number.
 369    *        - 'fdn': Fixed Dialling Number.
 370    * @param contact
 371    *        The contact will be updated in ICC.
 372    * @param [optional] pin2
 373    *        PIN2 is only required for 'fdn'.
 374    *
 375    * @return a DOMRequest.
 376    */
 377   [Throws]
 378   DOMRequest updateContact(DOMString contactType,
 379                            any contact,
 380                            optional DOMString? pin2 = null);
 381
 382   // Integrated Circuit Card Secure Element Interfaces.
 383
 384   /**
 385    * A secure element is a smart card chip that can hold
 386    * several different applications with the necessary security.
 387    * The most known secure element is the Universal Integrated Circuit Card
 388    * (UICC).
 389    */
 390
 391   /**
 392    * Send request to open a logical channel defined by its
 393    * application identifier (AID).
 394    *
 395    * @param aid
 396    *        The application identifier of the applet to be selected on this
 397    *        channel.
 398    *
 399    * @return a DOMRequest.
 400    *         The request's result will be an instance of channel (channelID)
 401    *         if available or null.
 402    */
 403   [Throws]
 404   DOMRequest iccOpenChannel(DOMString aid);
 405
 406   /**
 407    * Interface, used to communicate with an applet through the
 408    * application data protocol units (APDUs) and is
 409    * used for all data that is exchanged between the UICC and the terminal (ME).
 410    *
 411    * @param channel
 412    *        The application identifier of the applet to which APDU is directed.
 413    * @param apdu
 414    *        Application protocol data unit.
 415    *
 416    * @return a DOMRequest.
 417    *         The request's result will be response APDU.
 418    */
 419   [Throws]
 420   DOMRequest iccExchangeAPDU(long channel, any apdu);
 421
 422   /**
 423    * Send request to close the selected logical channel identified by its
 424    * application identifier (AID).
 425    *
 426    * @param aid
 427    *        The application identifier of the applet, to be closed.
 428    *
 429    * @return a DOMRequest.
 430    */
 431   [Throws]
 432   DOMRequest iccCloseChannel(long channel);
 433
 434   // Integrated Circuit Card Helpers.
 435
 436   /**
 437    * Verify whether the passed data (matchData) matches with some ICC's field
 438    * according to the mvno type (mvnoType).
 439    *
 440    * @param mvnoType
 441    *        Mvno type to use to compare the match data.
 442    *        Currently, we only support 'imsi'.
 443    * @param matchData
 444    *        Data to be compared with ICC's field.
 445    *
 446    * @return a DOMRequest.
 447    *         The request's result will be a boolean indicating the matching
 448    *         result.
 449    *
 450    * TODO: change param mvnoType to WebIDL enum after Bug 864489 -
 451    *       B2G RIL: use ipdl as IPC in MozIccManager
 452    */
 453   [Throws]
 454   DOMRequest matchMvno(DOMString mvnoType, DOMString matchData);
 455 };