From d7cdaf5a64385fe4ae4a809c4f4cc3710c641219 Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Sun, 12 Jun 2022 11:54:55 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- .../reference/apis/js-apis-cardEmulation.md | 111 +++++++++++++ .../reference/apis/js-apis-nfcController.md | 148 ++++++++++++++++++ .../reference/apis/js-apis-nfcTag.md | 78 +++++++++ 3 files changed, 337 insertions(+) create mode 100644 en/application-dev/reference/apis/js-apis-cardEmulation.md create mode 100644 en/application-dev/reference/apis/js-apis-nfcController.md create mode 100644 en/application-dev/reference/apis/js-apis-nfcTag.md diff --git a/en/application-dev/reference/apis/js-apis-cardEmulation.md b/en/application-dev/reference/apis/js-apis-cardEmulation.md new file mode 100644 index 0000000000..8a02d10ed2 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-cardEmulation.md @@ -0,0 +1,111 @@ +# Standard NFC Card Emulation + +This module is used to implement Near-Field Communication (NFC) card emulation. + +> **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 cardEmulation from '@ohos.nfc.cardEmulation'; +``` + + +## cardEmulation.isSupported + +isSupported(feature: number): boolean + +Checks whether a certain type of card emulation is supported. + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + + | **Type**| **Description**| + | -------- | -------- | + | boolean | Returns **true** if the card emulation is supported; returns **false** otherwise.| + +## HceService + +Implements Host-based Card Emulation (HCE). Before calling any API in **HceService**, you must use **new cardEmulation.HceService()** to create an **HceService** instance. + +### startHCE + +startHCE(aidList: string[]): boolean + +Starts HCE. + +**Required permissions**: ohos.permission.NFC_CARD_EMULATION + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | -------- | ---- | ----------------------- | +| aidList | string[] | Yes | Aid list to be registered for card emulation.| + +### stopHCE + +stopHCE(): boolean + +Stops HCE. + +**Required permissions**: ohos.permission.NFC_CARD_EMULATION + +**System capability**: SystemCapability.Communication.NFC + +### on + +on(type: "hceCmd", callback: AsyncCallback): void; + +Subscribes to messages from the peer device after **startHCE()**. + +**Required permissions**: ohos.permission.NFC_CARD_EMULATION + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | -------------------------------------------- | +| type | string | Yes | Event type to subscribe to. The value is **hceCmd**. | +| callback | AsyncCallback | Yes | Callback invoked to return the subscribed event. The input parameter is a data array that complies with the Application Protocol Data Unit (APDU).| + +### sendResponse + +sendResponse(responseApdu: number[]): void; + +Sends data to the peer device. + +**Required permissions**: ohos.permission.NFC_CARD_EMULATION + +**System capability**: SystemCapability.Communication.NFC + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | -------- | ---- | -------------------------------------------------- | +| responseApdu | number[] | Yes | Data to send, which is an array that complies with the APDU.| + +**Example** + +```js +var hceService = new cardEmulation.HceService(); +hceService.startHCE([ + "F0010203040506", "A0000000041010" +]) +hceService.stopHCE(); +hceService.on("hceCmd", (err, res) => { + if(err.data === 0) { + console.log('callback => Operation hceCmd succeeded. Data: ' + JSON.stringify(res)); + hceService.sendResponse([0x00,0xa4,0x04,0x00, + 0x0e,0x32,0x50,0x41,0x59,0x2e,0x53,0x59,0x53,0x2e,0x44,0x44, + 0x46,0x30,0x31,0x00]); + } else { + console.log('callback => Operation hceCmd failed. Cause: ' + err.data); + } +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-nfcController.md b/en/application-dev/reference/apis/js-apis-nfcController.md new file mode 100644 index 0000000000..7b94354644 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-nfcController.md @@ -0,0 +1,148 @@ +# Standard NFC + +This module is used to implement Near-Field Communication (NFC). + +> **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 controller from '@ohos.nfc.controller'; +``` + + +## controller.isNfcAvailable + +isNfcAvailable(): boolean + +Checks whether NFC is available. + +**Return value** + +| **Type**| **Description**| +| -------- | -------- | +| boolean | Returns **true** if NFC is available; returns **false** otherwise.| + + +## controller.openNfc + +openNfc(): boolean + +Opens NFC. + +**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description**| +| -------- | -------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | + +## controller.closeNfc + +closeNfc(): boolean + +Closes NFC. + +**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| -------- | ------------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +## controller.isNfcOpen + +isNfcOpen(): boolean + +Checks whether NFC is open. + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| -------- | ----------------------------------- | +| boolean | Returns **true** if NFC is open; returns **false** otherwise.| + +## controller.getNfcState + +getNfcState(): NfcState + +Obtains the NFC state. + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| -------- | ---------------------- | +| NfcState | NFC state obtained. For details, see [NfcState](#nfc-state).| + +## controller.on('nfcStateChange') + +on(type: "nfcStateChange", callback: Callback<NfcState>): void + +Registers NFC state changes. + +**System capability**: SystemCapability.Communication.NFC + +**Parameter** + + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type to subscribe to. The value is **nfcStateChange**.| + | callback | Callback<NfcState> | Yes| Callback invoked to return the NFC state changes.| + + + +## controller.off('nfcStateChange') + +off(type: "nfcStateChange", callback?: Callback<NfcState>): void + +Unregisters the NFC state changes. + +**System capability**: SystemCapability.Communication.NFC + +**Parameter** + + | **Name**| **Type**| **Mandatory**| **Description**| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type to unsubscribe from. The value is **nfcStateChange**.| +| callback | Callback<NfcState> | No| Callback used to return the NFC state changes. If this parameter is not specified, all callbacks associated with the specified event will be unregistered.| + +**Example** + + ```js + import nfcController from '@ohos.nfcController'; + + var NFC_STATE_NOTIFY = "nfcStateChange"; + + var recvNfcStateNotifyFunc = result => { + console.info("nfc state receive state: " + result); + } + + // Register the NFC state changes. + nfcController.on(NFC_STATE_NOTIFY, recvNfcStateNotifyFunc); + + // Unregister the NFC state changes. + nfcController.off(NFC_STATE_NOTIFY, recvNfcStateNotifyFunc); + ``` + +## NfcState + +Enumerates the NFC states. + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| STATE_OFF | 1 | Off| +| STATE_TURNING_ON | 2 | Turning on| +| STATE_ON | 3 | On| +| STATE_TURNING_OFF | 4 | Turning off| diff --git a/en/application-dev/reference/apis/js-apis-nfcTag.md b/en/application-dev/reference/apis/js-apis-nfcTag.md new file mode 100644 index 0000000000..160bac7842 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-nfcTag.md @@ -0,0 +1,78 @@ +# Standard NFC Tag + +This module is used to manage Near-Field Communication (NFC) tags. + +> **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 tag from '@ohos.nfc.tag'; +``` + + +## tag.getNfcATag + +getNfcATag(tagInfo: TagInfo): NfcATag + +Obtains the **NfcATag** object, which allows access to the tags that use the NfcA technology. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description**| +| -------- | -------- | +| NfcATag | **NfcATag** object obtained.| + +## tag.getNfcBTag + +getNfcBTag(tagInfo: TagInfo): NfcBTag + +Obtains the **NfcBTag** object, which allows access to the tags that use the NfcB technology. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| -------- | ---------------- | +| NfcBTag | **NfcBTag** object obtained.| + +## tag.getNfcFTag + +getNfcFTag(tagInfo: TagInfo): NfcFTag + +Obtains the **NfcFTag** object, which allows access to the tags that use the NfcF technology. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| -------- | ---------------- | +| NfcFTag | **NfcFTag** object obtained.| + +## tag.getNfcVTag + +getNfcVTag(tagInfo: TagInfo): NfcVTag + +Obtains the **NfcVTag** object, which allows access to the tags that use the NfcV technology. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC + +**Return value** + +| **Type**| **Description** | +| -------- | ---------------- | +| NfcVTag | **NfcVTag** object obtained.| -- GitLab