1# @ohos.nfc.cardEmulation (标准NFC-cardEmulation) 2 3本模块主要提供NFC卡模拟业务，包括判断支持哪种卡模拟类型，HCE卡模拟的业务实现等。 4HCE(Host Card Emulation)，称为基于主机的卡模拟，表示不依赖安全单元芯片，应用程序模拟NFC卡片，可以通过NFC服务和NFC读卡器通信。 5 6> **说明：** 7> 8> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 9 10## HCE卡模拟和AID列表的声明定义 11 12开发HCE卡模拟相关应用时，需要在应用的属性配置文件中，声明与NFC相关的属性值，比如，在module.json5文件中，声明下面属性值： 13```json 14{ 15 "module": { 16 // other declared attributes. 17 "abilities": [ 18 { 19 // other declared attributes. 20 "skills": [ 21 { 22 "actions": [ 23 "ohos.nfc.cardemulation.action.HOST_APDU_SERVICE" 24 ] 25 } 26 ], 27 "metadata": [ 28 { 29 "name": "payment-aid", 30 "value": "your payment aid" 31 }, 32 { 33 "name": "other-aid", 34 "value": "your other aid" 35 } 36 ] 37 } 38 ], 39 "requestPermissions": [ 40 { 41 "name": "ohos.permission.NFC_CARD_EMULATION", 42 // should add variable card_emulation_reason in string.json 43 "reason": "$string:card_emulation_reason", 44 } 45 ] 46 } 47} 48``` 49> **注意：** 50>1. 声明"actions"字段的内容填写，必须包含"ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"，不能更改。 51>2. 声明aid时，name必须为payment-aid，或者other-aid。填写错误会造成解析失败。 52>3. 声明权限时"requestPermissions"中的"name"字段的内容填写，必须是"ohos.permission.NFC_CARD_EMULATION"，不能更改。 53 54## 导入模块 55 56``` 57import cardEmulation from '@ohos.nfc.cardEmulation'; 58``` 59 60## FeatureType<sup>(deprecated)</sup> 61 62定义不同的NFC卡模拟类型。 63 64> **说明：** 65> 从 API version 6 开始支持，从 API version 9 开始废弃，建议使用[hasHceCapability](#hashcecapability9)替代。 66 67**系统能力：** SystemCapability.Communication.NFC.CardEmulation 68 69| 名称 | 值 | 说明 | 70| ---- | ---- | -------- | 71| HCE | 0 | HCE 卡模拟。 | 72| UICC | 1 | SIM 卡模拟。 | 73| ESE | 2 | ESE 卡模拟。 | 74 75## CardType<sup>9+</sup> 76 77定义卡模拟应用所使用的业务类型，是支付类型，还是其他类型。 78 79**系统能力：** SystemCapability.Communication.NFC.CardEmulation 80 81| 名称 | 值 | 说明 | 82| ------- | --------- | ----------------- | 83| PAYMENT | "payment" | 卡模拟应用所使用的业务是支付类型。 | 84| OTHER | "other" | 卡模拟应用所使用的业务是其他类型。 | 85 86## isSupported<sup>(deprecated)</sup> 87 88isSupported(feature: number): boolean 89 90是否支持某种类型的卡模拟。 91 92> **说明：** 93> 从 API version 6 开始支持，从 API version 9 开始废弃，建议使用[hasHceCapability](#hashcecapability9)替代。 94 95**系统能力：** SystemCapability.Communication.NFC.CardEmulation 96 97**参数：** 98 99| 参数名 | 类型 | 必填 | 说明 | 100| ------- | ------ | ---- | ---------------------------------------- | 101| feature | number | 是 | 卡模拟类型值，详细请见[FeatureType](#featuretypedeprecated)枚举值。 | 102 103**返回值：** 104 105| **类型** | **说明** | 106| ------- | -------------------------------------- | 107| boolean | true: 支持该类型卡模拟， false: 不支持该类型卡模拟。 | 108 109## hasHceCapability<sup>9+</sup> 110 111hasHceCapability(): boolean 112 113判断设备是否支持HCE卡模拟功能。 114 115**系统能力：** SystemCapability.Communication.NFC.CardEmulation 116 117**需要权限：** ohos.permission.NFC_CARD_EMULATION 118 119**返回值：** 120 121| **类型** | **说明** | 122| ------- | -------------------------------- | 123| boolean | true: 支持HCE， false: 不支持HCE。 | 124 125**示例：** 126 127```js 128import cardEmulation from '@ohos.nfc.cardEmulation'; 129 130let isHceSupported = cardEmulation.isSupported(cardEmulation.FeatureType.HCE); 131if (!isHceSupported) { 132 console.log('this device is not supported for HCE, ignore it.'); 133} 134 135let hasHceCap = cardEmulation.hasHceCapability(); 136if (!hasHceCap) { 137 console.log('this device hasHceCapability false, ignore it.'); 138} 139``` 140 141## isDefaultService<sup>9+</sup> 142 143isDefaultService(elementName: ElementName, type: CardType): boolean 144 145判断指定的应用是否为指定业务类型的默认应用。 146 147**系统能力：** SystemCapability.Communication.NFC.CardEmulation 148 149**需要权限：** ohos.permission.NFC_CARD_EMULATION 150 151**参数：** 152 153| 参数名 | 类型 | 必填 | 说明 | 154| ----------- | ---------------------------------------- | ---- |-------------------------| 155| elementName | [ElementName](../apis-ability-kit/js-apis-bundle-ElementName.md#elementname) | 是 | 所属应用声明NFC卡模拟能力的页面信息（至少包含bundleName、abilityName这两项的赋值），不可以为空。 | 156| type | [CardType](#cardtype9) | 是 | 卡模拟业务类型。目前只支持默认支付应用查询。 | 157 158**返回值：** 159 160| **类型** | **说明** | 161| ------- | ------------------------------------ | 162| boolean | true: 是默认支付应用， false: 不是默认支付应用。 | 163 164**示例：** 165```js 166import cardEmulation from '@ohos.nfc.cardEmulation'; 167import bundleManager from '@ohos.bundle.bundleManager'; 168 169let elementName : bundleManager.ElementName; 170 171// init elementName here, bundleName and abilityName are required. 172 173let isDefaultService = cardEmulation.isDefaultService(elementName, cardEmulation.CardType.PAYMENT); 174// do something according to the isDefaultService value 175``` 176 177 178## HceService<sup>8+</sup> 179 180提供HCE卡模拟的实现，主要包括接收对端读卡设备的APDU数据，并响应APDU数据到对端读卡设备。使用HCE相关接口前，必须先判断设备是否支持HCE卡模拟能力。 181 182### startHCE<sup>(deprecated)</sup> 183 184startHCE(aidList: string[]): boolean 185 186启动HCE业务功能。包括设置当前应用为前台优先，动态注册AID列表。暂不支持使用，仅做接口声明。 187 188> **说明：** 189> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#start9)替代。 190 191**需要权限：** ohos.permission.NFC_CARD_EMULATION 192 193**系统能力：** SystemCapability.Communication.NFC.CardEmulation 194 195**参数：** 196 197| 参数名 | 类型 | 必填 | 说明 | 198| ------- | -------- | ---- | ----------------------- | 199| aidList | string[] | 是 | 动态注册卡模拟的AID列表。 | 200 201**返回值：** 202 203| **类型** | **说明** | 204| ------- | -------------------------------------- | 205| boolean | true: 启动HCE功能或HCE已启动， false: 启动失败。 | 206 207### start<sup>9+</sup> 208 209start(elementName: [ElementName](../apis-ability-kit/js-apis-bundle-ElementName.md#elementname), aidList: string[]): void 210 211启动HCE业务功能。包括设置当前应用为前台优先，动态注册AID列表。暂不支持使用，仅做接口声明。 212 213**需要权限：** ohos.permission.NFC_CARD_EMULATION 214 215**系统能力：** SystemCapability.Communication.NFC.CardEmulation 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| ------- | -------- | ---- | ----------------------- | 221| elementName | [ElementName](../apis-ability-kit/js-apis-bundle-ElementName.md#elementname) | 是 | 所属应用声明NFC卡模拟能力的页面信息（至少包含bundleName、abilityName这两项的赋值），不可以为空。 | 222| aidList | string[] | 是 | 动态注册卡模拟的AID列表，允许为空。 | 223 224**错误码：** 225 226以下错误码的详细介绍请参见[NFC错误码](errorcode-nfc.md)。 227 228| 错误码ID | 错误信息| 229| ------- | -------| 230| 3100301 | Card emulation running state is abnormal in service. | 231 232### stopHCE<sup>(deprecated)</sup> 233 234stopHCE(): boolean 235 236停止HCE业务功能。包括退出当前应用前台优先，释放动态注册的AID列表，释放hceCmd的订阅。 237 238> **说明：** 239> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[stop](#stop9)替代。 240 241**需要权限：** ohos.permission.NFC_CARD_EMULATION 242 243**系统能力：** SystemCapability.Communication.NFC.CardEmulation 244 245**返回值：** 246 247| **类型** | **说明** | 248| ------- | -------------------------------------- | 249| boolean | true: 禁用HCE功能或HCE已禁用， false: 禁用失败。 | 250 251**示例：** 252 253示例请参见[on](#on8)接口的示例。 254 255### stop<sup>9+</sup> 256 257stop(elementName: [ElementName](../apis-ability-kit/js-apis-bundleManager-elementName.md#elementname)): void 258 259停止HCE业务功能。包括取消APDU数据接收的订阅，退出当前应用前台优先，释放动态注册的AID列表。应用程序需要在HCE卡模拟页面的onDestroy函数里调用该接口。 260 261**需要权限：** ohos.permission.NFC_CARD_EMULATION 262 263**系统能力：** SystemCapability.Communication.NFC.CardEmulation 264 265**参数：** 266 267| 参数名 | 类型 | 必填 | 说明 | 268| ------- | -------- | ---- | ----------------------- | 269| elementName | [ElementName](../apis-ability-kit/js-apis-bundle-ElementName.md#elementname) | 是 | 所属应用声明NFC卡模拟能力的页面信息（至少包含bundleName、abilityName这两项的赋值），不可以为空。 | 270 271**错误码：** 272 273以下错误码的详细介绍请参见[NFC错误码](errorcode-nfc.md)。 274 275| 错误码ID | 错误信息| 276| ------- | -------| 277| 3100301 | Card emulation running state is abnormal in service. | 278 279### on<sup>8+</sup> 280 281on(type: "hceCmd", callback: AsyncCallback\<number[]>): void 282 283订阅回调，用于接收对端读卡设备发送的APDU数据。应用程序需要在HCE卡模拟页面的onCreate函数里面调用该订阅函数。 284 285**需要权限：** ohos.permission.NFC_CARD_EMULATION 286 287**系统能力：** SystemCapability.Communication.NFC.CardEmulation 288 289**参数：** 290 291| 参数名 | 类型 | 必填 | 说明 | 292| -------- | ----------------------- | ---- | -------------------------------------------- | 293| type | string | 是 | 要订阅的回调类型，固定填"hceCmd"字符串。 | 294| callback | AsyncCallback\<number[]> | 是 | 订阅的事件回调，入参是符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 295 296**示例：** 297```js 298import UIAbility from '@ohos.app.ability.UIAbility'; 299import hilog from '@ohos.hilog'; 300import cardEmulation from '@ohos.nfc.cardEmulation'; 301import { AsyncCallback } from '@ohos.base'; 302import { ElementName } from './bundleManager/ElementName' 303 304let hceService: cardEmulation.HceService = new cardEmulation.HceService(); 305let element: ElementName; 306 307export default class EntryAbility extends UIAbility { 308 onCreate(want, launchParam) { 309 hilog.info(0x0000, 'testHce', '%{public}s', 'Ability onCreate'); 310 element = { 311 bundleName: want.bundleName, 312 abilityName: want.abilityName, 313 moduleName: want.moduleName 314 } 315 const apduCallback: AsyncCallback<number[]> = (err, data) => { 316 //handle the data and err 317 console.log("got apdu data"); 318 }; 319 hceService.on('hceCmd', apduCallback); 320 } 321 onDestroy() { 322 hilog.info(0x0000, 'testHce', '%{public}s', 'Ability onDestroy'); 323 hceService.stop(element) 324 } 325 // other life cycle method... 326} 327``` 328 329 330### sendResponse<sup>(deprecated)</sup> 331 332sendResponse(responseApdu: number[]): void 333 334发送APDU数据到对端读卡设备。暂不支持使用，仅做接口声明。 335 336> **说明：** 337> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[transmit](#transmit9)替代。 338 339**需要权限：** ohos.permission.NFC_CARD_EMULATION 340 341**系统能力：** SystemCapability.Communication.NFC.CardEmulation 342 343**参数：** 344 345| 参数名 | 类型 | 必填 | 说明 | 346| ------------ | -------- | ---- | -------------------------------------------------- | 347| responseApdu | number[] | 是 | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 348 349### transmit<sup>9+</sup> 350 351transmit(response: number[]): Promise\<void> 352 353发送APDU数据到对端读卡设备，使用Promise异步回调。应用程序必须在[on](#on8)收到读卡设备发送的APDU数据后，才调用该接口响应数据。 354 355**需要权限：** ohos.permission.NFC_CARD_EMULATION 356 357**系统能力：** SystemCapability.Communication.NFC.CardEmulation 358 359**参数：** 360 361| 参数名 | 类型 | 必填 | 说明 | 362| ------------ | -------- | ---- | -------------------------------------------------- | 363| response | number[] | 是 | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 364 365**返回值：** 366 367| **类型** | **说明** | 368| ------- | -------------------------------------- | 369| Promise\<void> | 以Promise形式异步返回发送APDU数据的结果。 | 370 371**错误码：** 372 373以下错误码的详细介绍请参见[NFC错误码](errorcode-nfc.md)。 374 375| 错误码ID | 错误信息| 376| ------- | -------| 377| 3100301 | Card emulation running state is abnormal in service. | 378 379**示例：** 380```js 381import cardEmulation from '@ohos.nfc.cardEmulation'; 382import { BusinessError } from '@ohos.base'; 383 384let hceService: cardEmulation.HceService = new cardEmulation.HceService(); 385 386// the data app wanna send, just a example data 387const responseData = [0x1, 0x2]; 388hceService.transmit(responseData).then(() => { 389 // handle the transmit promise 390 console.log("transmit Promise success."); 391}).catch((err: BusinessError) => { 392 console.log("transmit Promise error:", err); 393}); 394``` 395 396### transmit<sup>9+</sup> 397 398transmit(response: number[], callback: AsyncCallback\<void>): void 399 400发送APDU数据到对端读卡设备，使用Callback异步回调。应用程序必须在[on](#on8)收到读卡设备发送的APDU数据后，才调用该接口响应数据。 401 402**需要权限：** ohos.permission.NFC_CARD_EMULATION 403 404**系统能力：** SystemCapability.Communication.NFC.CardEmulation 405 406**参数：** 407 408| 参数名 | 类型 | 必填 | 说明 | 409| ------- | -------- | ---- | ----------------------- | 410| response | number[] | 是 | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 411| callback | AsyncCallback\<void> | 是 | 以callback形式异步返回发送APDU数据的结果。 | 412 413**错误码：** 414 415以下错误码的详细介绍请参见[NFC错误码](errorcode-nfc.md)。 416 417| 错误码ID | 错误信息| 418| ------- | -------| 419| 3100301 | Card emulation running state is abnormal in service. | 420 421**示例：** 422```js 423import cardEmulation from '@ohos.nfc.cardEmulation'; 424import { BusinessError } from '@ohos.base'; 425 426let hceService: cardEmulation.HceService = new cardEmulation.HceService(); 427 428// the data app wanna send, just a example data 429try { 430 const responseData = [0x1, 0x2]; 431 432 hceService.transmit(responseData, (err : BusinessError)=> { 433 if (err) { 434 console.error("transmit AsyncCallback err Code: ${err.code}, message: ${err.message}"); 435 } else { 436 console.log("transmit AsyncCallback success."); 437 } 438 }); 439} catch (busiError) { 440 console.error("transmit AsyncCallback catch Code: ${(busiError as Businsess).code}, " + 441 "message: ${(busiError as Businsess).message}"); 442} 443``` 444 445