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 * @throws { BusinessError } 201 - Permission denied. 338 * @throws { BusinessError } 401 - Invalid parameter. 339 * @throws { BusinessError } 801 - Capability not supported. 340 * @syscap SystemCapability.Communication.NFC.CardEmulation 341 * @atomicservice 342 * @since 12 343 */ 344 on(type: 'hceCmd', callback: AsyncCallback<number[]>): void; 345 346 /** 347 * Unsubscribe the event to receive the APDU data. 348 * 349 * @permission ohos.permission.NFC_CARD_EMULATION 350 * @param { 'hceCmd' } type - The type to unregister event. 351 * @param { AsyncCallback<number[]> } callback - The callback used to listen for the event. 352 * @throws { BusinessError } 201 - Permission denied. 353 * @throws { BusinessError } 801 - Capability not supported. 354 * @syscap SystemCapability.Communication.NFC.CardEmulation 355 * @atomicservice 356 * @since 18 357 */ 358 off(type: 'hceCmd', callback?: AsyncCallback<number[]>): void; 359 360 /** 361 * Sends a response APDU to the remote device. 362 * <p>This method is used by a host application when swiping card. 363 * 364 * @permission ohos.permission.NFC_CARD_EMULATION 365 * @param { number[] } responseApdu Indicates the response, which is a byte array. 366 * @syscap SystemCapability.Communication.NFC.CardEmulation 367 * @since 8 368 * @deprecated since 9 369 * @useinstead ohos.nfc.cardEmulation/cardEmulation.HceService#transmit 370 */ 371 sendResponse(responseApdu: number[]): void; 372 373 /** 374 * Sends a response APDU to the remote device. 375 * 376 * @permission ohos.permission.NFC_CARD_EMULATION 377 * @param { number[] } response Indicates the response to send, which is a byte array. 378 * @returns { Promise<void> } The void 379 * @throws { BusinessError } 201 - Permission denied. 380 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 381 * <br> 1. Mandatory parameters are left unspecified. 382 * <br> 2. Incorrect parameters types. 383 * <br> 3. Parameter verification failed. 384 * @throws { BusinessError } 801 - Capability not supported. 385 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 386 * @syscap SystemCapability.Communication.NFC.CardEmulation 387 * @since 9 388 */ 389 /** 390 * Sends a response APDU to the remote device. 391 * 392 * @permission ohos.permission.NFC_CARD_EMULATION 393 * @param { number[] } response Indicates the response to send, which is a byte array. 394 * @returns { Promise<void> } The void 395 * @throws { BusinessError } 201 - Permission denied. 396 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 397 * <br> 1. Mandatory parameters are left unspecified. 398 * <br> 2. Incorrect parameters types. 399 * <br> 3. Parameter verification failed. 400 * @throws { BusinessError } 801 - Capability not supported. 401 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 402 * @syscap SystemCapability.Communication.NFC.CardEmulation 403 * @atomicservice 404 * @since 12 405 */ 406 transmit(response: number[]): Promise<void>; 407 408 /** 409 * Sends a response APDU to the remote device. 410 * 411 * @permission ohos.permission.NFC_CARD_EMULATION 412 * @param { number[] } response Indicates the response to send, which is a byte array. 413 * @param { AsyncCallback<void> } callback The callback 414 * @throws { BusinessError } 201 - Permission denied. 415 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 416 * <br> 1. Mandatory parameters are left unspecified. 417 * <br> 2. Incorrect parameters types. 418 * <br> 3. Parameter verification failed. 419 * @throws { BusinessError } 801 - Capability not supported. 420 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 421 * @syscap SystemCapability.Communication.NFC.CardEmulation 422 * @since 9 423 */ 424 /** 425 * Sends a response APDU to the remote device. 426 * 427 * @permission ohos.permission.NFC_CARD_EMULATION 428 * @param { number[] } response Indicates the response to send, which is a byte array. 429 * @param { AsyncCallback<void> } callback The callback 430 * @throws { BusinessError } 201 - Permission denied. 431 * @throws { BusinessError } 401 - The parameter check failed. Possible causes: 432 * <br> 1. Mandatory parameters are left unspecified. 433 * <br> 2. Incorrect parameters types. 434 * <br> 3. Parameter verification failed. 435 * @throws { BusinessError } 801 - Capability not supported. 436 * @throws { BusinessError } 3100301 - Card emulation running state is abnormal in service. 437 * @syscap SystemCapability.Communication.NFC.CardEmulation 438 * @atomicservice 439 * @since 12 440 */ 441 transmit(response: number[], callback: AsyncCallback<void>): void; 442 } 443} 444export default cardEmulation; 445