1# @ohos.connectedTag (Active Tags)
2
3The **connectedTag** module provides APIs for using active tags. You can use the APIs to initialize the active tag chip and read and write active tags.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```js
12import { connectedTag } from '@kit.ConnectivityKit';
13```
14
15## connectedTag.init
16
17init(): boolean
18
19Initializes the active tag chip.
20
21> **NOTE**<br>
22> This API is supported since API version 8 and deprecated since API version 9. Use [initialize](#connectedtaginitialize9) instead.
23
24**Required permissions**: ohos.permission.NFC_TAG
25
26**System capability**: SystemCapability.Communication.ConnectedTag
27
28**Return value**
29
30| **Type** | **Description** |
31| -------- | -------- |
32| boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
33
34## connectedTag.initialize<sup>9+</sup>
35
36initialize(): void
37
38Initializes the active tag chip.
39
40**Required permissions**: ohos.permission.NFC_TAG
41
42**System capability**: SystemCapability.Communication.ConnectedTag
43
44**Error codes**
45For details about the error codes, see [NFC Error Codes](errorcode-nfc.md).
46
47| ID | Error Message|
48| -------- | -------- |
49|201 | Permission denied.                 |
50|801 | Capability not supported.          |
51| 3200101 | Connected NFC tag running state is abnormal in service. |
52
53## connectedTag.uninit
54
55uninit(): boolean
56
57Uninitializes the active tag resources.
58
59**Required permissions**: ohos.permission.NFC_TAG
60
61**System capability**: SystemCapability.Communication.ConnectedTag
62
63**Return value**
64
65| **Type** | **Description** |
66| -------- | -------- |
67| boolean | Returns **true** if the operation is successful; returns **false** otherwise. |
68
69## connectedTag.uninitialize<sup>9+</sup>
70
71uninitialize(): void
72
73Uninitializes the active tag resources.
74
75**Required permissions**: ohos.permission.NFC_TAG
76
77**System capability**: SystemCapability.Communication.ConnectedTag
78
79**Error codes**
80For details about the error codes, see [NFC Error Codes](errorcode-nfc.md).
81
82| ID | Error Message|
83| -------- | -------- |
84|201 | Permission denied.                 |
85|801 | Capability not supported.          |
86| 3200101 | Connected NFC tag running state is abnormal in service. |
87
88## connectedTag.readNdefTag
89
90readNdefTag(): Promise&lt;string&gt;
91
92Reads the content of this active tag. This API uses a promise to return the result.
93
94**Required permissions**: ohos.permission.NFC_TAG
95
96**System capability**: SystemCapability.Communication.ConnectedTag
97
98**Return value**
99
100| **Type** | **Description** |
101| -------- | -------- |
102| Promise&lt;string&gt; | Promise used to return the content of the active tag. |
103
104**Example**
105
106```js
107import { connectedTag } from '@kit.ConnectivityKit';
108import { BusinessError } from '@kit.BasicServicesKit';
109
110connectedTag.readNdefTag().then((data) => {
111    console.log("connectedTag readNdefTag Promise data = " + data);
112}).catch((err: BusinessError)=> {
113    console.log("connectedTag readNdefTag Promise err: " + err);
114});
115```
116
117## connectedTag.read<sup>9+</sup>
118
119read(): Promise&lt;number[]&gt;
120
121Reads the content of this active tag. This API uses a promise to return the result.
122
123**Required permissions**: ohos.permission.NFC_TAG
124
125**System capability**: SystemCapability.Communication.ConnectedTag
126
127**Return value**
128
129| **Type** | **Description** |
130| -------- | -------- |
131| Promise&lt;number[]&gt; | Promise used to return the content of the active tag. |
132
133**Error codes**
134For details about the error codes, see [NFC Error Codes](errorcode-nfc.md).
135
136| ID | Error Message|
137| -------- | -------- |
138|201 | Permission denied.                 |
139|801 | Capability not supported.          |
140| 3200101 | Connected NFC tag running state is abnormal in service. |
141
142**Example**
143
144```js
145import { connectedTag } from '@kit.ConnectivityKit';
146import { BusinessError } from '@kit.BasicServicesKit';
147
148connectedTag.read().then((data) => {
149    console.log("connectedTag read Promise data = " + data);
150}).catch((err: BusinessError)=> {
151    console.log("connectedTag read Promise err: " + err);
152});
153```
154
155## connectedTag.readNdefTag
156
157readNdefTag(callback: AsyncCallback&lt;string&gt;): void
158
159Reads the content of this active tag. This API uses an asynchronous callback to return the result.
160
161**Required permissions**: ohos.permission.NFC_TAG
162
163**System capability**: SystemCapability.Communication.ConnectedTag
164
165**Parameters**
166
167| **Name** | **Type** | **Mandatory** | **Description** |
168| -------- | -------- | -------- | -------- |
169| callback | AsyncCallback&lt;string&gt; | Yes | Callback used to return the active tag content obtained. |
170
171**Example**
172
173```js
174import { connectedTag } from '@kit.ConnectivityKit';
175
176connectedTag.readNdefTag((err, data)=> {
177    if (err) {
178        console.log("connectedTag readNdefTag AsyncCallback err: " + err);
179    } else {
180        console.log("connectedTag readNdefTag AsyncCallback data: " + data);
181    }
182});
183```
184
185## connectedTag.read<sup>9+</sup>
186
187read(callback: AsyncCallback&lt;number[]&gt;): void
188
189Reads the content of this active tag. This API uses an asynchronous callback to return the result.
190
191**Required permissions**: ohos.permission.NFC_TAG
192
193**System capability**: SystemCapability.Communication.ConnectedTag
194
195**Parameters**
196
197| **Name** | **Type** | **Mandatory** | **Description** |
198| -------- | -------- | -------- | -------- |
199| callback | AsyncCallback&lt;number[]&gt; | Yes | Callback used to return the active tag content obtained. |
200
201**Error codes**
202For details about the error codes, see [NFC Error Codes](errorcode-nfc.md).
203
204| ID | Error Message|
205| -------- | -------- |
206|201 | Permission denied.                 |
207|801 | Capability not supported.          |
208| 3200101 | Connected NFC tag running state is abnormal in service. |
209
210**Example**
211
212```js
213import { connectedTag } from '@kit.ConnectivityKit';
214
215connectedTag.read((err, data)=> {
216    if (err) {
217        console.log("connectedTag read AsyncCallback err: " + err);
218    } else {
219        console.log("connectedTag read AsyncCallback data: " + data);
220    }
221});
222```
223
224## connectedTag.writeNdefTag
225
226writeNdefTag(data: string): Promise&lt;void&gt;
227
228Writes data to this active tag. This API uses a promise to return the result.
229
230**Required permissions**: ohos.permission.NFC_TAG
231
232**System capability**: SystemCapability.Communication.ConnectedTag
233
234**Parameters**
235
236| **Name** | **Type** | **Mandatory** | **Description** |
237| -------- | -------- | -------- | -------- |
238| data | string | Yes | Data to write. The maximum length is 1024 bytes. |
239
240**Return value**
241
242| **Type** | **Description** |
243| -------- | -------- |
244| Promise&lt;void&gt; | Promise that returns no value. |
245
246**Example**
247
248```js
249import { connectedTag } from '@kit.ConnectivityKit';
250import { BusinessError } from '@kit.BasicServicesKit';
251
252let rawData = "010203"; // change it to be correct.
253connectedTag.writeNdefTag(rawData).then(() => {
254    console.log("connectedTag writeNdefTag Promise success.");
255}).catch((err: BusinessError)=> {
256    console.log("connectedTag writeNdefTag Promise err: " + err);
257});
258```
259
260## connectedTag.write<sup>9+</sup>
261
262write(data: number[]): Promise&lt;void&gt;
263
264Writes data to this active tag. This API uses a promise to return the result.
265
266**Required permissions**: ohos.permission.NFC_TAG
267
268**System capability**: SystemCapability.Communication.ConnectedTag
269
270**Parameters**
271
272| **Name** | **Type** | **Mandatory** | **Description** |
273| -------- | -------- | -------- | -------- |
274| data | number[] | Yes | Data to be written to the active tag. The value is a hexadecimal number ranging from 0x00 to 0xFF. |
275
276**Return value**
277
278| **Type** | **Description** |
279| -------- | -------- |
280| Promise&lt;void&gt; | Promise that returns no value. |
281
282**Error codes**
283For details about the error codes, see [NFC Error Codes](errorcode-nfc.md).
284
285| ID | Error Message|
286| -------- | -------- |
287|201 | Permission denied.                 |
288|401 | The parameter check failed. Possible causes: <br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameters types.<br>3. Parameter verification failed. |
289|801 | Capability not supported.          |
290| 3200101 | Connected NFC tag running state is abnormal in service. |
291
292**Example**
293
294```js
295import { connectedTag } from '@kit.ConnectivityKit';
296import { BusinessError } from '@kit.BasicServicesKit';
297
298let rawData = [0x01, 0x02, 0x03]; // change it to be correct.
299connectedTag.write(rawData).then(() => {
300    console.log("connectedTag write NdefTag Promise success.");
301}).catch((err: BusinessError)=> {
302    console.log("connectedTag write NdefTag Promise err: " + err);
303});
304```
305
306## connectedTag.writeNdefTag
307
308writeNdefTag(data: string, callback: AsyncCallback&lt;void&gt;): void
309
310Writes data to this active tag. This API uses an asynchronous callback to return the result.
311
312**Required permissions**: ohos.permission.NFC_TAG
313
314**System capability**: SystemCapability.Communication.ConnectedTag
315
316**Parameters**
317
318| **Name** | **Type** | **Mandatory** | **Description** |
319| -------- | -------- | -------- | -------- |
320| data | string | Yes | Data to write. The maximum length is 1024 bytes. |
321| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the active tag content obtained. |
322
323**Example**
324
325```js
326import { connectedTag } from '@kit.ConnectivityKit';
327
328let rawData = "010203"; // change it to be correct.
329connectedTag.writeNdefTag(rawData, (err)=> {
330    if (err) {
331        console.log("connectedTag writeNdefTag AsyncCallback err: " + err);
332    } else {
333        console.log("connectedTag writeNdefTag AsyncCallback success.");
334    }
335});
336```
337
338## connectedTag.write<sup>9+</sup>
339
340write(data: number[], callback: AsyncCallback&lt;void&gt;): void
341
342Writes data to this active tag. This API uses an asynchronous callback to return the result.
343
344**Required permissions**: ohos.permission.NFC_TAG
345
346**System capability**: SystemCapability.Communication.ConnectedTag
347
348**Parameters**
349
350| **Name** | **Type** | **Mandatory** | **Description** |
351| -------- | -------- | -------- | -------- |
352| data | number[] | Yes | Data to be written to the active tag. The value is a hexadecimal number ranging from 0x00 to 0xFF. |
353| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the active tag content obtained. |
354
355**Error codes**
356For details about the error codes, see [NFC Error Codes](errorcode-nfc.md).
357
358| ID | Error Message|
359| -------- | -------- |
360|201 | Permission denied.                 |
361|401 | The parameter check failed. Possible causes: <br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameters types.<br>3. Parameter verification failed. |
362|801 | Capability not supported.          |
363| 3200101 | Connected NFC tag running state is abnormal in service. |
364
365**Example**
366
367```js
368import { connectedTag } from '@kit.ConnectivityKit';
369
370let rawData = [0x01, 0x02, 0x03]; // change it to be correct.
371connectedTag.write(rawData, (err)=> {
372    if (err) {
373        console.log("connectedTag write NdefTag AsyncCallback err: " + err);
374    } else {
375        console.log("connectedTag write NdefTag AsyncCallback success.");
376    }
377});
378```
379
380## connectedTag.on('notify')
381
382on(type: "notify", callback: Callback&lt;number&gt;): void
383
384Registers the NFC field strength state events.
385
386**Required permissions**: ohos.permission.NFC_TAG
387
388**System capability**: SystemCapability.Communication.ConnectedTag
389
390**Parameters**
391
392| **Name** | **Type** | **Mandatory** | **Description** |
393| -------- | -------- | -------- | -------- |
394| type | string | Yes | Event type. The value is **notify**. |
395| callback | Callback&lt;number&gt; | Yes | Callback used to return the [NfcRfType](#nfcrftype). |
396
397## connectedTag.off('notify')
398
399off(type: "notify", callback?: Callback&lt;number&gt;): void
400
401Unregisters the NFC field strength state events.
402
403**Required permissions**: ohos.permission.NFC_TAG
404
405**System capability**: SystemCapability.Communication.ConnectedTag
406
407**Parameters**
408
409| **Name** | **Type** | **Mandatory** | **Description** |
410| -------- | -------- | -------- | -------- |
411| type | string | Yes | Event type. The value is **notify**. |
412| callback | Callback&lt;number&gt; | No | Callback used to return the field strength state. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.|
413
414**Example**
415
416```js
417import { connectedTag } from '@kit.ConnectivityKit';
418
419// Register the event.
420connectedTag.on("notify", (rfState : number)=> {
421  console.log("connectedTag on Callback rfState: " + rfState);
422});
423
424let initStatus = connectedTag.init();
425console.log("connectedTag init status: " + initStatus);
426
427// Add NFC connected tag business operations here.
428// connectedTag.writeNdefTag(rawData)
429// connectedTag.readNdefTag()
430
431let uninitStatus = connectedTag.uninit();
432console.log("connectedTag uninit status: " + uninitStatus);
433
434// Unregister the event.
435connectedTag.off("notify", (rfState : number)=> {
436  console.log("connectedTag off Callback rfState: " + rfState);
437});
438```
439
440## NfcRfType
441
442Enumerates the NFC field strength states.
443
444**System capability**: SystemCapability.Communication.ConnectedTag
445
446| Name | Value | Description |
447| -------- | -------- | -------- |
448| NFC_RF_LEAVE | 0 | Field off. |
449| NFC_RF_ENTER | 1 | Field on. |
450