1/* 2 * Copyright (c) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit ConnectivityKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22import { ElementName } from './bundleManager/ElementName'; 23import type { AbilityInfo } from './bundleManager/AbilityInfo'; 24 25/** 26 * Provides methods to operate or manage NFC card emulation. 27 * 28 * @namespace cardEmulation 29 * @syscap SystemCapability.Communication.NFC.CardEmulation 30 * @since 6 31 */ 32/** 33 * Provides methods to operate or manage NFC card emulation. 34 * 35 * @namespace cardEmulation 36 * @syscap SystemCapability.Communication.NFC.CardEmulation 37 * @atomicservice 38 * @since 12 39 */ 40declare namespace cardEmulation { 41 /** 42 * Defines the capability type. 43 * 44 * @enum { number } 45 * @syscap SystemCapability.Communication.NFC.CardEmulation 46 * @since 6 47 * @deprecated since 9 48 * @useinstead ohos.nfc.cardEmulation/cardEmulation#hasHceCapability 49 */ 50 enum FeatureType { 51 /** 52 * This constant is used to check whether HCE card emulation is supported. 53 * 54 * @syscap SystemCapability.Communication.NFC.CardEmulation 55 * @since 6 56 * @deprecated since 9 57 */ 58 HCE = 0, 59 60 /** 61 * This constant is used to check whether SIM card emulation is supported. 62 * 63 * @syscap SystemCapability.Communication.NFC.CardEmulation 64 * @since 6 65 * @deprecated since 9 66 */ 67 UICC = 1, 68 69 /** 70 * This constant is used to check whether eSE card emulation is supported. 71 * 72 * @syscap SystemCapability.Communication.NFC.CardEmulation 73 * @since 6 74 * @deprecated since 9 75 */ 76 ESE = 2 77 } 78 79 /** 80 * Define the card emulation type, payment or other. 81 * 82 * @enum { string } 83 * @syscap SystemCapability.Communication.NFC.CardEmulation 84 * @since 9 85 */ 86 /** 87 * Define the card emulation type, payment or other. 88 * 89 * @enum { string } 90 * @syscap SystemCapability.Communication.NFC.CardEmulation 91 * @atomicservice 92 * @since 12 93 */ 94 enum CardType { 95 /** 96 * Payment type of card emulation 97 * 98 * @syscap SystemCapability.Communication.NFC.CardEmulation 99 * @since 9 100 */ 101 /** 102 * Payment type of card emulation 103 * 104 * @syscap SystemCapability.Communication.NFC.CardEmulation 105 * @atomicservice 106 * @since 12 107 */ 108 PAYMENT = 'payment', 109 110 /** 111 * Other type of card emulation 112 * 113 * @syscap SystemCapability.Communication.NFC.CardEmulation 114 * @since 9 115 */ 116 /** 117 * Other type of card emulation 118 * 119 * @syscap SystemCapability.Communication.NFC.CardEmulation 120 * @atomicservice 121 * @since 12 122 */ 123 OTHER = 'other' 124 } 125 126 /** 127 * Checks whether a specified type of card emulation is supported. 128 * <p>This method is used to check Whether the host or secure element supports card emulation. 129 * 130 * @param { number } feature Indicates the card emulation type, {@code HCE}, {@code UICC}, or {@code ESE}. 131 * @returns { boolean } Returns true if the specified type of card emulation is supported; returns false otherwise. 132 * @syscap SystemCapability.Communication.NFC.CardEmulation 133 * @since 6 134 * @deprecated since 9 135 * @useinstead ohos.nfc.cardEmulation/cardEmulation#hasHceCapability 136 */ 137 function isSupported(feature: number): boolean; 138 139 /** 140 * Checks whether Host Card Emulation(HCE) capability is supported. 141 * 142 * @permission ohos.permission.NFC_CARD_EMULATION 143 * @returns { boolean } Returns true if HCE is supported, otherwise false. 144 * @throws { BusinessError } 201 - Permission denied. 145 * @throws { BusinessError } 801 - Capability not supported. 146 * @syscap SystemCapability.Communication.NFC.CardEmulation 147 * @since 9 148 */ 149 /** 150 * Checks whether Host Card Emulation(HCE) capability is supported. 151 * 152 * @permission ohos.permission.NFC_CARD_EMULATION 153 * @returns { boolean } Returns true if HCE is supported, otherwise false. 154 * @throws { BusinessError } 201 - Permission denied. 155 * @throws { BusinessError } 801 - Capability not supported. 156 * @syscap SystemCapability.Communication.NFC.CardEmulation 157 * @atomicservice 158 * @since 12 159 */ 160 function hasHceCapability(): boolean; 161 162 /** 163 * Checks whether a service is default for given type. 164 * 165 * @permission ohos.permission.NFC_CARD_EMULATION 166 * @param { ElementName } elementName - The element name of the service ability 167 * @param { CardType } type - The type to query, payment or other. 168 * @returns { boolean } Returns true if the service is default, otherwise false. 169 * @throws { BusinessError } 201 - Permission denied. 170 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 171 * <br> 1. Mandatory parameters are left unspecified. 172 * <br> 2. Incorrect parameters types. 173 * <br> 3. Parameter verification failed. 174 * @throws { BusinessError } 801 - Capability not supported. 175 * @syscap SystemCapability.Communication.NFC.CardEmulation 176 * @since 9 177 */ 178 /** 179 * Checks whether a service is default for given type. 180 * 181 * @permission ohos.permission.NFC_CARD_EMULATION 182 * @param { ElementName } elementName - The element name of the service ability 183 * @param { CardType } type - The type to query, payment or other. 184 * @returns { boolean } Returns true if the service is default, otherwise false. 185 * @throws { BusinessError } 201 - Permission denied. 186 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 187 * <br> 1. Mandatory parameters are left unspecified. 188 * <br> 2. Incorrect parameters types. 189 * <br> 3. Parameter verification failed. 190 * @throws { BusinessError } 801 - Capability not supported. 191 * @syscap SystemCapability.Communication.NFC.CardEmulation 192 * @atomicservice 193 * @since 12 194 */ 195 function isDefaultService(elementName: ElementName, type: CardType): boolean; 196 197 /** 198 * Gets all payment services. 199 * 200 * @permission ohos.permission.NFC_CARD_EMULATION 201 * @returns { AbilityInfo[] } Returns all payment services. 202 * @throws { BusinessError } 201 - Permission denied. 203 * @throws { BusinessError } 202 - Not system application. 204 * @throws { BusinessError } 801 - Capability not supported. 205 * @syscap SystemCapability.Communication.NFC.CardEmulation 206 * @systemapi Hide this for inner system use. 207 * @since 11 208 */ 209 function getPaymentServices(): AbilityInfo[]; 210 211 /** 212 * A class for NFC host application. 213 * <p>The NFC host application use this class, then Nfc service can access the application 214 * installation information and connect to services of the application. 215 * 216 * @syscap SystemCapability.Communication.NFC.CardEmulation 217 * @since 8 218 */ 219 /** 220 * A class for NFC host application. 221 * <p>The NFC host application use this class, then Nfc service can access the application 222 * installation information and connect to services of the application. 223 * 224 * @syscap SystemCapability.Communication.NFC.CardEmulation 225 * @atomicservice 226 * @since 12 227 */ 228 export class HceService { 229 /** 230 * start HCE 231 * 232 * @permission ohos.permission.NFC_CARD_EMULATION 233 * @param { string[] } aidList - The aid list to be registered by this service 234 * @returns { boolean } Returns true if HCE is enabled or has been enabled; returns false otherwise. 235 * @syscap SystemCapability.Communication.NFC.CardEmulation 236 * @since 8 237 * @deprecated since 9 238 * @useinstead ohos.nfc.cardEmulation/cardEmulation.HceService#start 239 */ 240 startHCE(aidList: string[]): boolean; 241 242 /** 243 * Starts the HCE, register more aids and allows this application to be preferred while in foreground. 244 * 245 * @permission ohos.permission.NFC_CARD_EMULATION 246 * @param { ElementName } elementName - The element name of the service ability 247 * @param { string[] } aidList - The aid list to be registered by this service, allowed to be empty. 248 * @throws { BusinessError } 201 - Permission denied. 249 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 250 * <br> 1. Mandatory parameters are left unspecified. 251 * <br> 2. Incorrect parameters types. 252 * <br> 3. Parameter verification failed. 253 * @throws { BusinessError } 801 - Capability not supported. 254 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 255 * @syscap SystemCapability.Communication.NFC.CardEmulation 256 * @since 9 257 */ 258 /** 259 * Starts the HCE, register more aids and allows this application to be preferred while in foreground. 260 * 261 * @permission ohos.permission.NFC_CARD_EMULATION 262 * @param { ElementName } elementName - The element name of the service ability 263 * @param { string[] } aidList - The aid list to be registered by this service, allowed to be empty. 264 * @throws { BusinessError } 201 - Permission denied. 265 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 266 * <br> 1. Mandatory parameters are left unspecified. 267 * <br> 2. Incorrect parameters types. 268 * <br> 3. Parameter verification failed. 269 * @throws { BusinessError } 801 - Capability not supported. 270 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 271 * @syscap SystemCapability.Communication.NFC.CardEmulation 272 * @atomicservice 273 * @since 12 274 */ 275 start(elementName: ElementName, aidList: string[]): void; 276 277 /** 278 * stop HCE 279 * 280 * @permission ohos.permission.NFC_CARD_EMULATION 281 * @returns { boolean } Returns true if HCE is disabled or has been disabled; returns false otherwise. 282 * @syscap SystemCapability.Communication.NFC.CardEmulation 283 * @since 8 284 * @deprecated since 9 285 * @useinstead ohos.nfc.cardEmulation/cardEmulation.HceService#stop 286 */ 287 stopHCE(): boolean; 288 289 /** 290 * Stops the HCE, and unset the preferred service while in foreground. 291 * 292 * @permission ohos.permission.NFC_CARD_EMULATION 293 * @param { ElementName } elementName - The element name of the service ability 294 * @throws { BusinessError } 201 - Permission denied. 295 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 296 * <br> 1. Mandatory parameters are left unspecified. 297 * <br> 2. Incorrect parameters types. 298 * <br> 3. Parameter verification failed. 299 * @throws { BusinessError } 801 - Capability not supported. 300 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 301 * @syscap SystemCapability.Communication.NFC.CardEmulation 302 * @since 9 303 */ 304 /** 305 * Stops the HCE, and unset the preferred service while in foreground. 306 * 307 * @permission ohos.permission.NFC_CARD_EMULATION 308 * @param { ElementName } elementName - The element name of the service ability 309 * @throws { BusinessError } 201 - Permission denied. 310 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 311 * <br> 1. Mandatory parameters are left unspecified. 312 * <br> 2. Incorrect parameters types. 313 * <br> 3. Parameter verification failed. 314 * @throws { BusinessError } 801 - Capability not supported. 315 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 316 * @syscap SystemCapability.Communication.NFC.CardEmulation 317 * @atomicservice 318 * @since 12 319 */ 320 stop(elementName: ElementName): void; 321 322 /** 323 * register HCE event to receive the APDU data. 324 * 325 * @permission ohos.permission.NFC_CARD_EMULATION 326 * @param { 'hceCmd' } type The type to register. 327 * @param { AsyncCallback<number[]> } callback Callback used to listen to HCE data that local device received. 328 * @syscap SystemCapability.Communication.NFC.CardEmulation 329 * @since 8 330 */ 331 /** 332 * register HCE event to receive the APDU data. 333 * 334 * @permission ohos.permission.NFC_CARD_EMULATION 335 * @param { 'hceCmd' } type The type to register. 336 * @param { AsyncCallback<number[]> } callback Callback used to listen to HCE data that local device received. 337 * @syscap SystemCapability.Communication.NFC.CardEmulation 338 * @atomicservice 339 * @since 12 340 */ 341 on(type: 'hceCmd', callback: AsyncCallback<number[]>): void; 342 343 /** 344 * Sends a response APDU to the remote device. 345 * <p>This method is used by a host application when swiping card. 346 * 347 * @permission ohos.permission.NFC_CARD_EMULATION 348 * @param { number[] } responseApdu Indicates the response, which is a byte array. 349 * @syscap SystemCapability.Communication.NFC.CardEmulation 350 * @since 8 351 * @deprecated since 9 352 * @useinstead ohos.nfc.cardEmulation/cardEmulation.HceService#transmit 353 */ 354 sendResponse(responseApdu: number[]): void; 355 356 /** 357 * Sends a response APDU to the remote device. 358 * 359 * @permission ohos.permission.NFC_CARD_EMULATION 360 * @param { number[] } response Indicates the response to send, which is a byte array. 361 * @returns { Promise<void> } The void 362 * @throws { BusinessError } 201 - Permission denied. 363 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 364 * <br> 1. Mandatory parameters are left unspecified. 365 * <br> 2. Incorrect parameters types. 366 * <br> 3. Parameter verification failed. 367 * @throws { BusinessError } 801 - Capability not supported. 368 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 369 * @syscap SystemCapability.Communication.NFC.CardEmulation 370 * @since 9 371 */ 372 /** 373 * Sends a response APDU to the remote device. 374 * 375 * @permission ohos.permission.NFC_CARD_EMULATION 376 * @param { number[] } response Indicates the response to send, which is a byte array. 377 * @returns { Promise<void> } The void 378 * @throws { BusinessError } 201 - Permission denied. 379 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 380 * <br> 1. Mandatory parameters are left unspecified. 381 * <br> 2. Incorrect parameters types. 382 * <br> 3. Parameter verification failed. 383 * @throws { BusinessError } 801 - Capability not supported. 384 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 385 * @syscap SystemCapability.Communication.NFC.CardEmulation 386 * @atomicservice 387 * @since 12 388 */ 389 transmit(response: number[]): Promise<void>; 390 391 /** 392 * Sends a response APDU to the remote device. 393 * 394 * @permission ohos.permission.NFC_CARD_EMULATION 395 * @param { number[] } response Indicates the response to send, which is a byte array. 396 * @param { AsyncCallback<void> } callback The callback 397 * @throws { BusinessError } 201 - Permission denied. 398 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 399 * <br> 1. Mandatory parameters are left unspecified. 400 * <br> 2. Incorrect parameters types. 401 * <br> 3. Parameter verification failed. 402 * @throws { BusinessError } 801 - Capability not supported. 403 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 404 * @syscap SystemCapability.Communication.NFC.CardEmulation 405 * @since 9 406 */ 407 /** 408 * Sends a response APDU to the remote device. 409 * 410 * @permission ohos.permission.NFC_CARD_EMULATION 411 * @param { number[] } response Indicates the response to send, which is a byte array. 412 * @param { AsyncCallback<void> } callback The callback 413 * @throws { BusinessError } 201 - Permission denied. 414 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 415 * <br> 1. Mandatory parameters are left unspecified. 416 * <br> 2. Incorrect parameters types. 417 * <br> 3. Parameter verification failed. 418 * @throws { BusinessError } 801 - Capability not supported. 419 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 420 * @syscap SystemCapability.Communication.NFC.CardEmulation 421 * @atomicservice 422 * @since 12 423 */ 424 transmit(response: number[], callback: AsyncCallback<void>): void; 425 } 426} 427export default cardEmulation; 428