• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.nfc.cardEmulation (Standard NFC Card Emulation)
2
3The **cardEmulation** module implements Near-Field Communication (NFC) card emulation. You can use the APIs provided by this module to determine the card emulation type supported and implement Host-based Card Emulation (HCE).
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```
12import cardEmulation from '@ohos.nfc.cardEmulation';
13```
14
15## FeatureType
16
17Enumerates the NFC card emulation types.
18
19> **NOTE**
20> This parameter is supported since API version 6 and deprecated since API version 9. You are advised to use [hasHceCapability](#hashcecapability9).
21
22**System capability**: SystemCapability.Communication.NFC.CardEmulation
23
24| Name  | Value   | Description      |
25| ---- | ---- | -------- |
26| HCE  | 0    | HCE.|
27| UICC | 1    | Subscriber identity module (SIM) card emulation.|
28| ESE  | 2    | embedded Secure Element (eSE) emulation. |
29
30## CardType<sup>9+</sup>
31
32Enumerates the types of services used by the card emulation application.
33
34**System capability**: SystemCapability.Communication.NFC.CardEmulation
35
36| Name     | Value        | Description               |
37| ------- | --------- | ----------------- |
38| PAYMENT | "payment" | Payment type.|
39| OTHER   | "other"   | Other types.|
40
41## isSupported
42
43isSupported(feature: number): boolean
44
45Checks whether a certain type of card emulation is supported.
46
47> **NOTE**
48> This parameter is supported since API version 6 and deprecated since API version 9. You are advised to use [hasHceCapability](#hashcecapability9).
49
50**System capability**: SystemCapability.Communication.NFC.CardEmulation
51
52**Parameters**
53
54| Name    | Type    | Mandatory  | Description                                      |
55| ------- | ------ | ---- | ---------------------------------------- |
56| feature | number | Yes   | Card emulation type. For details, see [FeatureType](#featuretype).|
57
58**Return value**
59
60| **Type** | **Description**                                |
61| ------- | -------------------------------------- |
62| boolean | Returns **true** if the card emulation type is supported; returns **false** otherwise.|
63
64## hasHceCapability<sup>9+</sup>
65
66hasHceCapability(): boolean
67
68Checks whether HCE is supported.
69
70**System capability**: SystemCapability.Communication.NFC.CardEmulation
71
72**Required permissions**: ohos.permission.NFC_CARD_EMULATION
73
74**Return value**
75
76| **Type** | **Description**                          |
77| ------- | -------------------------------- |
78| boolean | Returns **true** if HCE is supported; returns **false** otherwise.|
79
80## isDefaultService<sup>9+</sup>
81
82isDefaultService(elementName: ElementName, type: CardType): boolean
83
84Checks whether an application is the default application of the specified service type.
85
86**System capability**: SystemCapability.Communication.NFC.CardEmulation
87
88**Required permissions**: ohos.permission.NFC_CARD_EMULATION
89
90**Parameters**
91
92| Name        | Type                                      | Mandatory  | Description                     |
93| ----------- | ---------------------------------------- | ---- | ----------------------- |
94| elementName | [ElementName](js-apis-bundleManager-elementName.md#elementname) | Yes   | Application description, which consists of the bundle name and component name.|
95| type        | [CardType](#cardtype9)                   | Yes   | Card emulation service type.               |
96
97**Return value**
98
99| **Type** | **Description**                              |
100| ------- | ------------------------------------ |
101| boolean | Returns **true** if the application is the default payment application; returns **false** otherwise.|
102
103## HceService<sup>8+</sup>
104
105Implements HCE, including receiving Application Protocol Data Units (APDUs) from the peer card reader and sending a response. Before using HCE-related APIs, check whether the device supports HCE. This API is used only for declaration and cannot be used currently.
106
107### startHCE<sup>8+</sup>
108
109startHCE(aidList: string[]): boolean
110
111Starts HCE, including setting the application to be foreground preferred and dynamically registering the application identifier (AID) list. This API is used only for declaration and cannot be used currently.
112
113> **NOTE**
114> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [start](#start9).
115
116**Required permissions**: ohos.permission.NFC_CARD_EMULATION
117
118**System capability**: SystemCapability.Communication.NFC.CardEmulation
119
120**Parameters**
121
122| Name | Type    | Mandatory| Description                   |
123| ------- | -------- | ---- | ----------------------- |
124| aidList | string[] | Yes  | AID list to register.|
125
126### start<sup>9+</sup>
127
128start(elementName: ElementName, aidList: string[]): void
129
130Starts HCE, including setting the application to be foreground preferred and dynamically registering the application identifier (AID) list. This API is used only for declaration and cannot be used currently.
131
132**Required permissions**: ohos.permission.NFC_CARD_EMULATION
133
134**System capability**: SystemCapability.Communication.NFC.CardEmulation
135
136**Parameters**
137
138| Name | Type    | Mandatory| Description                   |
139| ------- | -------- | ---- | ----------------------- |
140| elementName | ElementName | Yes  | Element name of a service capability.|
141| aidList | string[] | Yes  | AID list to register.|
142
143**Error codes**
144
145For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
146
147| ID| Error Message |
148| ------- | -------|
149| 3100301 | Card emulation running state is abnormal in service. |
150
151### stopHCE<sup>8+</sup>
152
153stopHCE(): boolean
154
155Stops HCE, including removing the foreground preferred attribute and releasing the dynamically registered AID list. This API is used only for declaration and cannot be used currently.
156
157> **NOTE**
158> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [stop](#stop).
159
160**Required permissions**: ohos.permission.NFC_CARD_EMULATION
161
162**System capability**: SystemCapability.Communication.NFC.CardEmulation
163
164### stop<sup>9+</sup>
165
166stop(elementName: ElementName): void;
167
168Stops HCE, including removing the foreground preferred attribute and releasing the dynamically registered AID list. This API is used only for declaration and cannot be used currently.
169
170**Required permissions**: ohos.permission.NFC_CARD_EMULATION
171
172**System capability**: SystemCapability.Communication.NFC.CardEmulation
173
174**Parameters**
175
176| Name | Type    | Mandatory| Description                   |
177| ------- | -------- | ---- | ----------------------- |
178| elementName | ElementName | Yes  | Element name of a service capability.|
179
180**Error codes**
181
182For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
183
184| ID| Error Message |
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
192Registers a callback to receive APDUs from the peer card reader. This API is used only for declaration and cannot be used currently.
193
194**Required permissions**: ohos.permission.NFC_CARD_EMULATION
195
196**System capability**: SystemCapability.Communication.NFC.CardEmulation
197
198**Parameters**
199
200| Name  | Type                   | Mandatory| Description                                        |
201| -------- | ----------------------- | ---- | -------------------------------------------- |
202| type     | string                  | Yes  | Event type to subscribe to. The value is **hceCmd**.                        |
203| callback | AsyncCallback<number[]> | Yes  | Callback invoked to return the APDU, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**.|
204
205### sendResponse<sup>8+</sup>
206
207sendResponse(responseApdu: number[]): void;
208
209Sends a response to the peer card reader. This API is used only for declaration and cannot be used currently.
210
211> **NOTE**
212> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [transmit](#transmit9).
213
214**Required permissions**: ohos.permission.NFC_CARD_EMULATION
215
216**System capability**: SystemCapability.Communication.NFC.CardEmulation
217
218**Parameters**
219
220| Name      | Type    | Mandatory| Description                                              |
221| ------------ | -------- | ---- | -------------------------------------------------- |
222| responseApdu | number[] | Yes  | Response APDU sent to the peer card reader. The value consists of hexadecimal numbers ranging from **0x00** to **0xFF**.|
223
224### transmit<sup>9+</sup>
225
226transmit(response: number[]): Promise\<void>;
227
228Sends a response to the peer card reader. This API is used only for declaration and cannot be used currently.
229
230**Required permissions**: ohos.permission.NFC_CARD_EMULATION
231
232**System capability**: SystemCapability.Communication.NFC.CardEmulation
233
234**Parameters**
235
236| Name      | Type    | Mandatory| Description                                              |
237| ------------ | -------- | ---- | -------------------------------------------------- |
238| responseApdu | number[] | Yes  | Response APDU sent to the peer card reader. The value consists of hexadecimal numbers ranging from **0x00** to **0xFF**.|
239
240**Return value**
241
242| **Type** | **Description**                                |
243| ------- | -------------------------------------- |
244| Promise\<void> | Promise that returns no value.|
245
246**Error codes**
247
248For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
249
250| ID| Error Message |
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
258Sends a response to the peer card reader. This API is used only for declaration and cannot be used currently.
259
260**Required permissions**: ohos.permission.NFC_CARD_EMULATION
261
262**System capability**: SystemCapability.Communication.NFC.CardEmulation
263
264**Parameters**
265
266| Name | Type    | Mandatory| Description                   |
267| ------- | -------- | ---- | ----------------------- |
268| responseApdu | number[] | Yes  | Response APDU sent to the peer card reader. The value consists of hexadecimal numbers ranging from **0x00** to **0xFF**.|
269| callback | AsyncCallback\<void> | Yes  | Callback that returns no value.|
270
271**Error codes**
272
273For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
274
275| ID| Error Message |
276| ------- | -------|
277| 3100301 | Card emulation running state is abnormal in service. |
278
279**Example**
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