1# @ohos.nfc.cardEmulation (标准NFC-cardEmulation) 2 3本模块主要提供NFC卡模拟业务，包括判断支持哪种卡模拟类型，HCE卡模拟的业务实现等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11``` 12import cardEmulation from '@ohos.nfc.cardEmulation'; 13``` 14 15## FeatureType 16 17定义不同的NFC卡模拟类型。 18 19> **说明：** 20> 从 API version 6 开始支持，从 API version 9 开始废弃，建议使用[hasHceCapability](#hashcecapability9)替代。 21 22**系统能力：** SystemCapability.Communication.NFC.CardEmulation 23 24| 名称 | 值 | 说明 | 25| ---- | ---- | -------- | 26| HCE | 0 | HCE 卡模拟。 | 27| UICC | 1 | SIM 卡模拟。 | 28| ESE | 2 | ESE卡模拟。 | 29 30## CardType<sup>9+</sup> 31 32定义卡模拟应用所使用的业务类型，是支付类型，还是其他类型。 33 34**系统能力：** SystemCapability.Communication.NFC.CardEmulation 35 36| 名称 | 值 | 说明 | 37| ------- | --------- | ----------------- | 38| PAYMENT | "payment" | 卡模拟应用所使用的业务是支付类型。 | 39| OTHER | "other" | 卡模拟应用所使用的业务是其他类型。 | 40 41## isSupported 42 43isSupported(feature: number): boolean 44 45是否支持某种类型的卡模拟。 46 47> **说明：** 48> 从 API version 6 开始支持，从 API version 9 开始废弃，建议使用[hasHceCapability](#hashcecapability9)替代。 49 50**系统能力：** SystemCapability.Communication.NFC.CardEmulation 51 52**参数：** 53 54| 参数名 | 类型 | 必填 | 说明 | 55| ------- | ------ | ---- | ---------------------------------------- | 56| feature | number | 是 | 卡模拟类型值，详细请见[FeatureType](#featuretype)枚举值。 | 57 58**返回值：** 59 60| **类型** | **说明** | 61| ------- | -------------------------------------- | 62| boolean | true: 支持该类型卡模拟， false: 不支持该类型卡模拟。 | 63 64## hasHceCapability<sup>9+</sup> 65 66hasHceCapability(): boolean 67 68判断是否支持HCE功能。 69 70**系统能力：** SystemCapability.Communication.NFC.CardEmulation 71 72**需要权限：** ohos.permission.NFC_CARD_EMULATION 73 74**返回值：** 75 76| **类型** | **说明** | 77| ------- | -------------------------------- | 78| boolean | true: 支持HCE， false: 不支持HCE。 | 79 80## isDefaultService<sup>9+</sup> 81 82isDefaultService(elementName: ElementName, type: CardType): boolean 83 84判断指定的应用是否为指定业务类型的默认应用。 85 86**系统能力：** SystemCapability.Communication.NFC.CardEmulation 87 88**需要权限：** ohos.permission.NFC_CARD_EMULATION 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ----------- | ---------------------------------------- | ---- | ----------------------- | 94| elementName | [ElementName](js-apis-bundleManager-elementName.md#elementname) | 是 | 应用的描述，由Bundle名称和组件名称组成。 | 95| type | [CardType](#cardtype9) | 是 | 卡模拟业务类型。 | 96 97**返回值：** 98 99| **类型** | **说明** | 100| ------- | ------------------------------------ | 101| boolean | true: 是默认支付应用， false: 不是默认支付应用。 | 102 103## HceService<sup>8+</sup> 104 105提供HCE卡模拟的实现，主要包括接收对端读卡设备的APDU数据，并响应APDU数据到对端读卡设备。使用HCE相关接口前，必须先判断设备是否支持HCE卡模拟能力。暂不支持使用，仅做接口声明。 106 107### startHCE<sup>8+</sup> 108 109startHCE(aidList: string[]): boolean 110 111启动HCE业务功能。包括设置当前应用为前台优先，动态注册AID列表。暂不支持使用，仅做接口声明。 112 113> **说明：** 114> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#start9)替代。 115 116**需要权限：** ohos.permission.NFC_CARD_EMULATION 117 118**系统能力：** SystemCapability.Communication.NFC.CardEmulation 119 120**参数：** 121 122| 参数名 | 类型 | 必填 | 说明 | 123| ------- | -------- | ---- | ----------------------- | 124| aidList | string[] | 是 | 动态注册卡模拟的AID列表。 | 125 126### start<sup>9+</sup> 127 128start(elementName: ElementName, aidList: string[]): void 129 130启动HCE业务功能。包括设置当前应用为前台优先，动态注册AID列表。暂不支持使用，仅做接口声明。 131 132**需要权限：** ohos.permission.NFC_CARD_EMULATION 133 134**系统能力：** SystemCapability.Communication.NFC.CardEmulation 135 136**参数：** 137 138| 参数名 | 类型 | 必填 | 说明 | 139| ------- | -------- | ---- | ----------------------- | 140| elementName | ElementName | 是 | 服务能力的元素名称。 | 141| aidList | string[] | 是 | 动态注册卡模拟的AID列表。 | 142 143**错误码：** 144 145以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 146 147| 错误码ID | 错误信息| 148| ------- | -------| 149| 3100301 | Card emulation running state is abnormal in service. | 150 151### stopHCE<sup>8+</sup> 152 153stopHCE(): boolean 154 155停止HCE业务功能。包括退出当前应用前台优先，释放动态注册的AID列表。暂不支持使用，仅做接口声明。 156 157> **说明：** 158> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[stop](#stop)替代。 159 160**需要权限：** ohos.permission.NFC_CARD_EMULATION 161 162**系统能力：** SystemCapability.Communication.NFC.CardEmulation 163 164### stop<sup>9+</sup> 165 166stop(elementName: ElementName): void; 167 168停止HCE业务功能。包括退出当前应用前台优先，释放动态注册的AID列表。暂不支持使用，仅做接口声明。 169 170**需要权限：** ohos.permission.NFC_CARD_EMULATION 171 172**系统能力：** SystemCapability.Communication.NFC.CardEmulation 173 174**参数：** 175 176| 参数名 | 类型 | 必填 | 说明 | 177| ------- | -------- | ---- | ----------------------- | 178| elementName | ElementName | 是 | 服务能力的元素名称。 | 179 180**错误码：** 181 182以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 183 184| 错误码ID | 错误信息| 185| ------- | -------| 186| 3100301 | Card emulation running state is abnormal in service. | 187 188### on<sup>8+</sup> 189 190on(type: "hceCmd", callback: AsyncCallback<number[]>): void; 191 192订阅回调，用于接收对端读卡设备发送的APDU数据。暂不支持使用，仅做接口声明。 193 194**需要权限：** ohos.permission.NFC_CARD_EMULATION 195 196**系统能力：** SystemCapability.Communication.NFC.CardEmulation 197 198**参数：** 199 200| 参数名 | 类型 | 必填 | 说明 | 201| -------- | ----------------------- | ---- | -------------------------------------------- | 202| type | string | 是 | 固定填"hceCmd"字符串。 | 203| callback | AsyncCallback<number[]> | 是 | 订阅的事件回调，入参是符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 204 205### sendResponse<sup>8+</sup> 206 207sendResponse(responseApdu: number[]): void; 208 209发送APDU数据到对端读卡设备。暂不支持使用，仅做接口声明。 210 211> **说明：** 212> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[transmit](#transmit9)替代。 213 214**需要权限：** ohos.permission.NFC_CARD_EMULATION 215 216**系统能力：** SystemCapability.Communication.NFC.CardEmulation 217 218**参数：** 219 220| 参数名 | 类型 | 必填 | 说明 | 221| ------------ | -------- | ---- | -------------------------------------------------- | 222| responseApdu | number[] | 是 | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 223 224### transmit<sup>9+</sup> 225 226transmit(response: number[]): Promise\<void>; 227 228发送APDU数据到对端读卡设备。暂不支持使用，仅做接口声明。 229 230**需要权限：** ohos.permission.NFC_CARD_EMULATION 231 232**系统能力：** SystemCapability.Communication.NFC.CardEmulation 233 234**参数：** 235 236| 参数名 | 类型 | 必填 | 说明 | 237| ------------ | -------- | ---- | -------------------------------------------------- | 238| responseApdu | number[] | 是 | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 239 240**返回值：** 241 242| **类型** | **说明** | 243| ------- | -------------------------------------- | 244| Promise\<void> | 表示异步回调完成。 | 245 246**错误码：** 247 248以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 249 250| 错误码ID | 错误信息| 251| ------- | -------| 252| 3100301 | Card emulation running state is abnormal in service. | 253 254### transmit<sup>9+</sup> 255 256transmit(response: number[], callback: AsyncCallback\<void>): void; 257 258发送APDU数据到对端读卡设备。暂不支持使用，仅做接口声明。 259 260**需要权限：** ohos.permission.NFC_CARD_EMULATION 261 262**系统能力：** SystemCapability.Communication.NFC.CardEmulation 263 264**参数：** 265 266| 参数名 | 类型 | 必填 | 说明 | 267| ------- | -------- | ---- | ----------------------- | 268| responseApdu | number[] | 是 | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | 269| callback | AsyncCallback\<void> | 是 | 回调函数void | 270 271**错误码：** 272 273以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 274 275| 错误码ID | 错误信息| 276| ------- | -------| 277| 3100301 | Card emulation running state is abnormal in service. | 278 279**示例：** 280 281```js 282import cardEmulation from '@ohos.nfc.cardEmulation'; 283import bundleManager from '@ohos.bundle.bundleManager'; 284 285let isHceSupported = cardEmulation.isSupported(cardEmulation.FeatureType.HCE); 286if (!isHceSupported) { 287 console.log('this device is not supported for HCE, ignore it.'); 288} 289 290let hasHceCap = cardEmulation.hasHceCapability(); 291if (!hasHceCap) { 292 console.log('this device hasHceCapability false, ignore it.'); 293} 294 295let elementName: bundleManager.ElementName = { 296 bundleName : "com.example.myapplication", 297 abilityName : "EntryAbility", 298}; 299let isDefaultService = cardEmulation.isDefaultService(elementName, cardEmulation.CardType.PAYMENT); 300console.log('is the app is default service for this card type: ' + isDefaultService); 301``` 302 303