diff --git a/en/application-dev/reference/apis/js-apis-connectedTag.md b/en/application-dev/reference/apis/js-apis-connectedTag.md new file mode 100644 index 0000000000000000000000000000000000000000..5e76a594771be99634ac1cfd7e3b7089b8a58ba3 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-connectedTag.md @@ -0,0 +1,223 @@ +# Active Tag + +> ![icon-note.gif](public_sys-resources/icon-note.gif)**NOTE**
+> 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. + + +## Modules to Import + +``` +import connectedTag from '@ohos.connectedTag'; +``` + + +## connectedTag.init + +init(): boolean + +Initializes the active tag chip. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Return value + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the initialization is successful; returns **false** otherwise.| + + +## connectedTag.uninit + +uninit(): boolean + +Uninitializes the active tag resources. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Return value + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + + +## connectedTag.readNdefTag + +readNdefTag(): Promise<string> + +Reads the content of this active tag. This method uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Return value + | **Type**| **Description**| + | -------- | -------- | + | Promise<string> | Promise used to return the content of the active tag.| + +- Example + ``` + import connectedTag from '@ohos.connectedTag'; + + connectedTag.readNdefTag().then(result => { + console.log("promise recv ndef response: " + result); + }); + ``` + +## connectedTag.readNdefTag + +readNdefTag(callback: AsyncCallback<string>): void + +Reads the content of this active tag. This method uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Parameters + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | Yes| Callback invoked to return the active tag content obtained.| + +- Example + ``` + import connectedTag from '@ohos.connectedTag'; + + connectedTag.readNdefTag(result => { + console.log("callback recv ndef response: " + result); + }); + ``` + +## connectedTag.writeNdefTag + +writeNdefTag(data: string): Promise<void> + +Writes data to this active tag. This method uses a promise to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Parameters + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | data | string | Yes| Data to write. The maximum length is 1024 bytes.| + +- Return value + | **Type**| **Description**| + | -------- | -------- | + | Promise<void> | Promise used to return the result. This method returns no value.| + +- Example + ``` + import connectedTag from '@ohos.connectedTag'; + + writeNdefTag.write("010203") + .then((value) => { + // Data is written to the tag. + console.log(`success to write event: ${value}`); + }).catch((err) => { + // Failed to write data to the tag. + console.error(`failed to write event because ${err.code}`); + }); + ``` + +## connectedTag.writeNdefTag + +writeNdefTag(data: string, callback: AsyncCallback<string>): void + +Writes data to this active tag. This method uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Parameters + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | data | string | Yes| Data to write. The maximum length is 1024 bytes.| + | callback | AsyncCallback<string> | Yes| Callback invoked to return the operation result.| + +- Example + ``` + import connectedTag from '@ohos.connectedTag'; + + connectedTag.writeNdefTag("010203", (err, value) => { + if (err) { + // Failed to write data to the tag. + console.error(`failed to write event because ${err.code}`); + return; + } + + // Data is written to the tag. + console.log(`success to write event: ${value}`); + }); + ``` + +## connectedTag.on('notify') + +on(type: "notify", callback: Callback<number>): void + +Registers the NFC field strength state events. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Parameters + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **notify**.| + | callback | Callback<number> | Yes| Callback invoked to return the field strength state.| + +- Enumerates the field strength states. + | **Value**| **Description**| + | -------- | -------- | + | 0 | Field off. | + | 1 | Field on. | + + +## connectedTag.off('notify') + +off(type: "notify", callback?: Callback<number>): void + +Unregisters the NFC field strength state events. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.ConnectedTag + +- Parameters + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is **notify**.| + | callback | Callback<number> | 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.| + +- Example + ``` + import connectedTag from '@ohos.connectedTag'; + + var NFC_RF_NOTIFY = "notify"; + + var recvNfcRfNotifyFunc = result => { + console.info("nfc rf receive state: " + result); + } + + // Register event + connectedTag.on(NFC_RF_NOTIFY, recvNfcRfNotifyFunc); + + // Unregister event + connectedTag.off(NFC_RF_NOTIFY, recvNfcRfNotifyFunc); + ``` + +## NfcRfType + +Enumerates the NFC states. + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| NFC_RF_LEAVE | 0 | Field off. | +| NFC_RF_ENTER | 1 | Field on. |