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 enum IccCardState
   6 {
   7   "unknown", // ICC card state is either not yet reported from modem or in an
   8              // unknown state.
   9   "ready",
  10   "pinRequired",
  11   "pukRequired",
  12   "permanentBlocked",
  13
  14   /**
  15    * Personalization States
  16    */
  17   "personalizationInProgress",
  18   "personalizationReady",
  19
  20   // SIM Personalization States.
  21   "networkLocked",
  22   "networkSubsetLocked",
  23   "corporateLocked",
  24   "serviceProviderLocked",
  25   "simPersonalizationLocked",
  26   "networkPukRequired",
  27   "networkSubsetPukRequired",
  28   "corporatePukRequired",
  29   "serviceProviderPukRequired",
  30   "simPersonalizationPukRequired",
  31
  32   // RUIM Personalization States.
  33   "network1Locked",
  34   "network2Locked",
  35   "hrpdNetworkLocked",
  36   "ruimCorporateLocked",
  37   "ruimServiceProviderLocked",
  38   "ruimPersonalizationLocked",
  39   "network1PukRequired",
  40   "network2PukRequired",
  41   "hrpdNetworkPukRequired",
  42   "ruimCorporatePukRequired",
  43   "ruimServiceProviderPukRequired",
  44   "ruimPersonalizationPukRequired",
  45
  46   /**
  47    * Additional States.
  48    */
  49   "illegal" // See Bug 916000. An owed pay card will be rejected by the network
  50             // and fall in this state.
  51 };
  52
  53 enum IccLockType
  54 {
  55   "pin",
  56   "pin2",
  57   "puk",
  58   "puk2",
  59   "nck",      // Network depersonalization -- network control key (NCK).
  60   "nsck",     // Network subset depersonalization -- network subset control key (NSCK).
  61   "nck1",     // Network type 1 depersonalization -- network type 1 control key (NCK1).
  62   "nck2",     // Network type 2 depersonalization -- network type 2 control key (NCK2).
  63   "hnck",     // HRPD network depersonalization -- HRPD network control key (HNCK).
  64   "cck",      // Corporate depersonalization -- corporate control key (CCK).
  65   "spck",     // Service provider depersonalization -- service provider control key (SPCK).
  66   "pck",      // SIM depersonalization -- personalization control key (PCK).
  67   "rcck",     // RUIM corporate depersonalization -- RUIM corporate control key (RCCK).
  68   "rspck",    // RUIM service provider depersonalization -- RUIM service provider control key (RSPCK).
  69   "nckPuk",   // Network PUK depersonalization -- network control key (NCK).
  70   "nsckPuk",  // Network subset PUK depersonalization -- network subset control key (NSCK).
  71   "nck1Puk",  // Network type 1 PUK depersonalization -- network type 1 control key (NCK1).
  72   "nck2Puk",  // Network type 2 PUK depersonalization -- Network type 2 control key (NCK2).
  73   "hnckPuk",  // HRPD network PUK depersonalization -- HRPD network control key (HNCK).
  74   "cckPuk",   // Corporate PUK depersonalization -- corporate control key (CCK).
  75   "spckPuk",  // Service provider PUK depersonalization -- service provider control key (SPCK).
  76   "pckPuk",   // SIM PUK depersonalization -- personalization control key (PCK).
  77   "rcckPuk",  // RUIM corporate PUK depersonalization -- RUIM corporate control key (RCCK).
  78   "rspckPuk", // RUIM service provider PUK depersonalization -- service provider control key (SPCK).
  79   "fdn"
  80 };
  81
  82 enum IccContactType
  83 {
  84   "adn", // Abbreviated Dialling Number.
  85   "fdn", // Fixed Dialling Number.
  86   "sdn"  // Service Dialling Number.
  87 };
  88
  89 enum IccMvnoType
  90 {
  91   "imsi",
  92   "spn",
  93   "gid"
  94 };
  95
  96 enum IccService
  97 {
  98   "fdn"
  99 };
 100
 101 dictionary IccUnlockCardLockOptions
 102 {
 103   required IccLockType lockType;
 104
 105   DOMString? pin = null; // Necessary for lock types: "pin", "pin2", "nck",
 106                          // "nsck", "nck1", "nck2", "hnck", "cck", "spck",
 107                          // "pck", "rcck", "rspck".
 108
 109   DOMString? puk = null; // Necessary for lock types: "puk", "puk2", "nckPuk",
 110                          // "nsckPuk", "nck1Puk", "nck2Puk", "hnckPuk", "cckPuk",
 111                          // "spckPuk", "pckPuk", "rcckPuk", "rspckPuk".
 112
 113   DOMString? newPin = null; // Necessary for lock types: "puk", "puk2".
 114 };
 115
 116 dictionary IccSetCardLockOptions
 117 {
 118  required IccLockType lockType;
 119
 120  DOMString? pin = null; // Necessary for lock types: "pin", "pin2"
 121
 122  DOMString? pin2 = null; // Used for enabling/disabling operation.
 123                          // Necessary for lock types: "fdn".
 124
 125  DOMString? newPin = null; // Used for changing password operation.
 126                            // Necessary for lock types: "pin", "pin2"
 127
 128  boolean enabled; // Used for enabling/disabling operation.
 129                   // Necessary for lock types: "pin", "fdn"
 130 };
 131
 132 [Pref="dom.icc.enabled"]
 133 interface MozIcc : EventTarget
 134 {
 135   // Integrated Circuit Card Information.
 136
 137   /**
 138    * Information stored in the device's ICC.
 139    *
 140    * Once the ICC becomes undetectable, iccinfochange event will be notified.
 141    * Also, the attribute is set to null and this MozIcc object becomes invalid.
 142    * Calling asynchronous functions raises exception then.
 143    */
 144   readonly attribute (MozIccInfo or MozGsmIccInfo or MozCdmaIccInfo)? iccInfo;
 145
 146   /**
 147    * The 'iccinfochange' event is notified whenever the icc info object
 148    * changes.
 149    */
 150   attribute EventHandler oniccinfochange;
 151
 152   // Integrated Circuit Card State.
 153
 154   /**
 155    * Indicates the state of the device's ICC.
 156    *
 157    * Once the ICC becomes undetectable, cardstatechange event will be notified.
 158    * Also, the attribute is set to null and this MozIcc object becomes invalid.
 159    * Calling asynchronous functions raises exception then.
 160    */
 161   readonly attribute IccCardState? cardState;
 162
 163   /**
 164    * The 'cardstatechange' event is notified when the 'cardState' attribute
 165    * changes value.
 166    */
 167   attribute EventHandler oncardstatechange;
 168
 169   // Integrated Circuit Card STK.
 170
 171   /**
 172    * Send the response back to ICC after an attempt to execute STK proactive
 173    * Command.
 174    *
 175    * @param command
 176    *        Command received from ICC. See MozStkCommand.
 177    * @param response
 178    *        The response that will be sent to ICC.
 179    *        @see MozStkResponse for the detail of response.
 180    */
 181   [Throws]
 182   void sendStkResponse(any command, any response);
 183
 184   /**
 185    * Send the "Menu Selection" envelope command to ICC for menu selection.
 186    *
 187    * @param itemIdentifier
 188    *        The identifier of the item selected by user.
 189    * @param helpRequested
 190    *        true if user requests to provide help information, false otherwise.
 191    */
 192   [Throws]
 193   void sendStkMenuSelection(unsigned short itemIdentifier,
 194                             boolean helpRequested);
 195
 196   /**
 197    * Send the "Timer Expiration" envelope command to ICC for TIMER MANAGEMENT.
 198    *
 199    * @param timer
 200    *        The identifier and value for a timer.
 201    *        timerId: Identifier of the timer that has expired.
 202    *        timerValue: Different between the time when this command is issued
 203    *                    and when the timer was initially started.
 204    *        @see MozStkTimer
 205    */
 206   [Throws]
 207   void sendStkTimerExpiration(any timer);
 208
 209   /**
 210    * Send "Event Download" envelope command to ICC.
 211    * ICC will not respond with any data for this command.
 212    *
 213    * @param event
 214    *        one of events below:
 215    *        - MozStkLocationEvent
 216    *        - MozStkCallEvent
 217    *        - MozStkLanguageSelectionEvent
 218    *        - MozStkGeneralEvent
 219    *        - MozStkBrowserTerminationEvent
 220    */
 221   [Throws]
 222   void sendStkEventDownload(any event);
 223
 224   /**
 225    * The 'stkcommand' event is notified whenever STK proactive command is
 226    * issued from ICC.
 227    */
 228   attribute EventHandler onstkcommand;
 229
 230   /**
 231    * 'stksessionend' event is notified whenever STK session is terminated by
 232    * ICC.
 233    */
 234   attribute EventHandler onstksessionend;
 235
 236   // Integrated Circuit Card Lock interfaces.
 237
 238   /**
 239    * Find out about the status of an ICC lock (e.g. the PIN lock).
 240    *
 241    * @param lockType
 242    *        Identifies the lock type.
 243    *
 244    * @return a DOMRequest.
 245    *         The request's result will be an object containing
 246    *         information about the specified lock's status.
 247    *         e.g. {enabled: true}.
 248    */
 249   [Throws]
 250   DOMRequest getCardLock(IccLockType lockType);
 251
 252   /**
 253    * Unlock a card lock.
 254    *
 255    * @param info
 256    *        An object containing the information necessary to unlock
 257    *        the given lock.
 258    *
 259    * @return a DOMRequest.
 260    *         The request's error will be an object containing the number of
 261    *         remaining retries
 262    *         @see IccCardLockError.
 263    */
 264   [Throws]
 265   DOMRequest unlockCardLock(optional IccUnlockCardLockOptions info);
 266
 267   /**
 268    * Modify the state of a card lock.
 269    *
 270    * @param info
 271    *        An object containing information about the lock and
 272    *        how to modify its state.
 273    *
 274    * @return a DOMRequest.
 275    *         The request's error will be an object containing the number of
 276    *         remaining retries.
 277    *         @see IccCardLockError.
 278    */
 279   [Throws]
 280   DOMRequest setCardLock(optional IccSetCardLockOptions info);
 281
 282   /**
 283    * Retrieve the number of remaining tries for unlocking the card.
 284    *
 285    * @param lockType
 286    *        Identifies the lock type.
 287    *
 288    * @return a DOMRequest.
 289    *         The request's result will be an object containing the number of
 290    *         remaining retries.
 291    *         e.g. {retryCount: 3}.
 292    */
 293   [Throws]
 294   DOMRequest getCardLockRetryCount(IccLockType lockType);
 295
 296   // Integrated Circuit Card Phonebook Interfaces.
 297
 298   /**
 299    * Read ICC contacts.
 300    *
 301    * @param contactType
 302    *        Identifies the contact type.
 303    *
 304    * @return a DOMRequest.
 305    */
 306   [Throws]
 307   DOMRequest readContacts(IccContactType contactType);
 308
 309   /**
 310    * Update ICC Phonebook contact.
 311    *
 312    * @param contactType
 313    *        Identifies the contact type.
 314    * @param contact
 315    *        The contact will be updated in ICC.
 316    * @param pin2 [optional]
 317    *        PIN2 is only required for "fdn".
 318    *
 319    * @return a DOMRequest.
 320    */
 321   [Throws]
 322   DOMRequest updateContact(IccContactType contactType,
 323                            any contact,
 324                            optional DOMString? pin2 = null);
 325
 326   // Integrated Circuit Card Helpers.
 327
 328   /**
 329    * Verify whether the passed data (matchData) matches with some ICC's field
 330    * according to the mvno type (mvnoType).
 331    *
 332    * @param mvnoType
 333    *        Mvno type to use to compare the match data.
 334    * @param matchData
 335    *        Data to be compared with ICC's field.
 336    *
 337    * @return a DOMRequest.
 338    *         The request's result will be a boolean indicating the matching
 339    *         result.
 340    */
 341   [Throws]
 342   DOMRequest matchMvno(IccMvnoType mvnoType, DOMString matchData);
 343
 344   /**
 345    * Retrieve the the availability of an icc service.
 346    *
 347    * @param service
 348    *        Identifies the service type.
 349    *
 350    * @return a Promise
 351    *         If succeeds, the promise is resolved with boolean indicating the
 352    *         availability of the service. Otherwise, rejected with a DOMError.
 353    */
 354   [NewObject]
 355   Promise<boolean> getServiceState(IccService service);
 356 };