• 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<sup>(deprecated)</sup>
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<sup>(deprecated)</sup>
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## getPaymentServices<sup>11+</sup>
104
105getPaymentServices(): [AbilityInfo](js-apis-bundleManager-abilityInfo.md)[]
106
107Obtains all payment services.
108
109**System API**: This is a system API.
110
111**System capability**: SystemCapability.Communication.NFC.CardEmulation
112
113**Required permissions**: ohos.permission.NFC_CARD_EMULATION
114
115**Return value**
116
117| **Type** | **Description**                              |
118| ------- | ------------------------------------ |
119| [AbilityInfo](js-apis-bundleManager-abilityInfo.md)[] | Payment services obtained.|
120
121## HceService<sup>8+</sup>
122
123Implements 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.
124
125### startHCE<sup>(deprecated)</sup>
126
127startHCE(aidList: string[]): boolean
128
129Starts 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.
130
131> **NOTE**
132> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [start](#start9).
133
134**Required permissions**: ohos.permission.NFC_CARD_EMULATION
135
136**System capability**: SystemCapability.Communication.NFC.CardEmulation
137
138**Parameters**
139
140| Name | Type    | Mandatory| Description                   |
141| ------- | -------- | ---- | ----------------------- |
142| aidList | string[] | Yes  | AID list to register.|
143
144**Return value**
145
146| **Type** | **Description**                                |
147| ------- | -------------------------------------- |
148| boolean | Returns **true** if HCE is started or has been started; returns **false** otherwise.|
149
150### start<sup>9+</sup>
151
152start(elementName: [ElementName](js-apis-bundleManager-elementName.md#elementname), aidList: string[]): void
153
154Starts 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.
155
156**Required permissions**: ohos.permission.NFC_CARD_EMULATION
157
158**System capability**: SystemCapability.Communication.NFC.CardEmulation
159
160**Parameters**
161
162| Name | Type    | Mandatory| Description                   |
163| ------- | -------- | ---- | ----------------------- |
164| elementName | [ElementName](js-apis-bundleManager-elementName.md#elementname) | Yes  | Element name of the service capability.|
165| aidList | string[] | Yes  | List of AIDs. This parameter can be left empty.|
166
167**Error codes**
168
169For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
170
171| ID| Error Message |
172| ------- | -------|
173| 3100301 | Card emulation running state is abnormal in service. |
174
175### stopHCE<sup>(deprecated)</sup>
176
177stopHCE(): boolean
178
179Stops 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.
180
181> **NOTE**
182> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [stop](#stop).
183
184**Required permissions**: ohos.permission.NFC_CARD_EMULATION
185
186**System capability**: SystemCapability.Communication.NFC.CardEmulation
187
188**Return value**
189
190| **Type** | **Description**                                |
191| ------- | -------------------------------------- |
192| boolean | Returns **true** is HCE is stopped; returns **false** otherwise.|
193
194
195### stop<sup>9+</sup>
196
197stop(elementName: [ElementName](js-apis-bundleManager-elementName.md#elementname)): void
198
199Stops 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.
200
201**Required permissions**: ohos.permission.NFC_CARD_EMULATION
202
203**System capability**: SystemCapability.Communication.NFC.CardEmulation
204
205**Parameters**
206
207| Name | Type    | Mandatory| Description                   |
208| ------- | -------- | ---- | ----------------------- |
209| elementName | [ElementName](js-apis-bundleManager-elementName.md#elementname) | Yes  | Element name of the service capability.|
210
211**Error codes**
212
213For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
214
215| ID| Error Message |
216| ------- | -------|
217| 3100301 | Card emulation running state is abnormal in service. |
218
219### on<sup>8+</sup>
220
221on(type: "hceCmd", callback: AsyncCallback<number[]>): void
222
223Registers a callback to receive APDUs from the peer card reader.
224
225**Required permissions**: ohos.permission.NFC_CARD_EMULATION
226
227**System capability**: SystemCapability.Communication.NFC.CardEmulation
228
229**Parameters**
230
231| Name  | Type                   | Mandatory| Description                                        |
232| -------- | ----------------------- | ---- | -------------------------------------------- |
233| type     | string                  | Yes  | Event type to subscribe to. The value is **hceCmd**.                        |
234| callback | AsyncCallback<number[]> | Yes  | Callback invoked to return the APDU, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**.|
235
236**Example**
237```js
238import cardEmulation from '@ohos.nfc.cardEmulation';
239import { AsyncCallback } from '@ohos.base';
240
241let hceService: cardEmulation.HceService = new cardEmulation.HceService();
242
243const apduCallback: AsyncCallback<number[]> = (err, data) => {
244  //handle the data and err
245  console.log("got apdu data");
246};
247hceService.on('hceCmd', apduCallback);
248```
249
250
251### sendResponse<sup>(deprecated)</sup>
252
253sendResponse(responseApdu: number[]): void
254
255Sends a response to the peer card reader. This API is used only for declaration and cannot be used currently.
256
257> **NOTE**
258> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [transmit](#transmit9).
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
270### transmit<sup>9+</sup>
271
272transmit(response: number[]): Promise\<void>
273
274Sends a response to the peer card reader. This API uses a promise to return the result.
275
276**Required permissions**: ohos.permission.NFC_CARD_EMULATION
277
278**System capability**: SystemCapability.Communication.NFC.CardEmulation
279
280**Parameters**
281
282| Name      | Type    | Mandatory| Description                                              |
283| ------------ | -------- | ---- | -------------------------------------------------- |
284| response | number[] | Yes  | Response APDU sent to the peer card reader. The value consists of hexadecimal numbers ranging from **0x00** to **0xFF**.|
285
286**Return value**
287
288| **Type** | **Description**                                |
289| ------- | -------------------------------------- |
290| Promise\<void> | Promise that returns no value.|
291
292**Error codes**
293
294For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
295
296| ID| Error Message |
297| ------- | -------|
298| 3100301 | Card emulation running state is abnormal in service. |
299
300**Example**
301```js
302import cardEmulation from '@ohos.nfc.cardEmulation';
303import { AsyncCallback } from '@ohos.base';
304
305let hceService: cardEmulation.HceService = new cardEmulation.HceService();
306
307// the data app wanna send, just a example data
308const responseData = [0x1, 0x2];
309hceService.transmit(responseData).then(() => {
310  // handle the transmit promise
311  console.log("send data.");
312}).catch((err: BusinessError) => {
313  console.log("send data error:", err);
314});
315```
316
317### transmit<sup>9+</sup>
318
319transmit(response: number[], callback: AsyncCallback\<void>): void
320
321Sends a response to the peer card reader. This API is used only for declaration and cannot be used currently.
322
323**Required permissions**: ohos.permission.NFC_CARD_EMULATION
324
325**System capability**: SystemCapability.Communication.NFC.CardEmulation
326
327**Parameters**
328
329| Name | Type    | Mandatory| Description                   |
330| ------- | -------- | ---- | ----------------------- |
331| response | number[] | Yes  | Response APDU sent to the peer card reader. The value consists of hexadecimal numbers ranging from **0x00** to **0xFF**.|
332| callback | AsyncCallback\<void> | Yes  | Callback that returns no value.|
333
334**Error codes**
335
336For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md).
337
338| ID| Error Message |
339| ------- | -------|
340| 3100301 | Card emulation running state is abnormal in service. |
341
342**Example**
343
344```js
345import cardEmulation from '@ohos.nfc.cardEmulation';
346import bundleManager from '@ohos.bundle.bundleManager';
347
348let isHceSupported = cardEmulation.isSupported(cardEmulation.FeatureType.HCE);
349if (!isHceSupported) {
350    console.log('this device is not supported for HCE, ignore it.');
351}
352
353let hasHceCap = cardEmulation.hasHceCapability();
354if (!hasHceCap) {
355    console.log('this device hasHceCapability false, ignore it.');
356}
357
358let elementName: bundleManager.ElementName = {
359    bundleName : "com.example.myapplication",
360    abilityName : "EntryAbility",
361};
362let isDefaultService = cardEmulation.isDefaultService(elementName, cardEmulation.CardType.PAYMENT);
363console.log('is the app is default service for this card type: ' + isDefaultService);
364```
365