From 3a649f4109409630b9bf9bf0cfb7358046c24694 Mon Sep 17 00:00:00 2001 From: zhangxiuping Date: Tue, 27 Sep 2022 11:00:44 +0800 Subject: [PATCH] Update nfc controller api reference. Signed-off-by: zhangxiuping --- .../reference/apis/js-apis-cardEmulation.md | 70 +++++++++----- .../reference/apis/js-apis-nfcController.md | 94 +++++++++++-------- 2 files changed, 99 insertions(+), 65 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md b/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md index 5ad5188e32..52dca7d462 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md @@ -1,6 +1,6 @@ # 标准NFC-cardEmulation -本模块主要用于操作及管理NFC卡模拟。 +本模块主要提供NFC卡模拟业务，包括判断支持哪种卡模拟类型，HCE卡模拟的业务实现等。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -12,30 +12,49 @@ import cardEmulation from '@ohos.nfc.cardEmulation'; ``` +## FeatureType + +定义不同的NFC卡模拟类型。 + +**系统能力**：SystemCapability.Communication.NFC.Core + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| HCE | 0 | HCE 卡模拟。 | +| UICC | 1 | SIM 卡模拟。 | +| ESE | 2 | ESE卡模拟。 | ## cardEmulation.isSupported isSupported(feature: number): boolean -是否支持某种类型的卡模拟 +是否支持某种类型的卡模拟。 + +**需要权限**：ohos.permission.NFC_CARD_EMULATION **系统能力**：SystemCapability.Communication.NFC.Core +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | -------- | ---- | ----------------------- | +| feature | number | 是 | 卡模拟类型值，详细请见[FeatureType](#featuretype)枚举值。 | + **返回值：** | **类型** | **说明** | | -------- | -------- | - | boolean | true:支持该类型卡模拟， false:不支持该类型卡模拟。 | + | boolean | true: 支持该类型卡模拟， false: 不支持该类型卡模拟。 | ## HceService8+ -管理HCE卡模拟。在调用HceService的接口前，需要先通过new cardEmulation.HceService()创建实例。 +提供HCE卡模拟的实现，主要包括接收对端读卡设备的APDU数据，并响应APDU数据到对端读卡设备。使用HCE相关接口前，必须先判断设备是否支持HCE卡模拟能力。 ### startHCE8+ startHCE(aidList: string[]): boolean -开始使用HCE能力。 +启动HCE业务功能。包括设置当前应用为前台优先，动态注册AID列表。 **需要权限**：ohos.permission.NFC_CARD_EMULATION @@ -45,13 +64,13 @@ startHCE(aidList: string[]): boolean | 参数名 | 类型 | 必填 | 说明 | | ------- | -------- | ---- | ----------------------- | -| aidList | string[] | 是 | 注册进行卡模拟的aid列表 | +| aidList | string[] | 是 | 动态注册卡模拟的AID列表。 | ### stopHCE8+ stopHCE(): boolean -停止使用HCE能力。 +停止HCE业务功能。包括退出当前应用前台优先，释放动态注册的AID列表。 **需要权限**：ohos.permission.NFC_CARD_EMULATION @@ -61,7 +80,7 @@ stopHCE(): boolean on(type: "hceCmd", callback: AsyncCallback): void; -在startHCE后，订阅对端设备消息。 +订阅回调，用于接收对端读卡设备发送的APDU数据。 **需要权限**：ohos.permission.NFC_CARD_EMULATION @@ -71,14 +90,14 @@ on(type: "hceCmd", callback: AsyncCallback): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------- | ---- | -------------------------------------------- | -| type | string | 是 | 固定填"hceCmd"字符串 | -| callback | AsyncCallback | 是 | 订阅的事件回调，入参是符合APDU协议的数据数组 | +| type | string | 是 | 固定填"hceCmd"字符串。 | +| callback | AsyncCallback | 是 | 订阅的事件回调，入参是符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | ### sendResponse8+ sendResponse(responseApdu: number[]): void; -发送数据到对端设备。 +发送APDU数据到对端读卡设备。 **需要权限**：ohos.permission.NFC_CARD_EMULATION @@ -88,16 +107,25 @@ sendResponse(responseApdu: number[]): void; | 参数名 | 类型 | 必填 | 说明 | | ------------ | -------- | ---- | -------------------------------------------------- | -| responseApdu | number[] | 是 | 准备发送到对端的数据，入参是符合APDU协议的数据数组 | +| responseApdu | number[] | 是 | 发送到对端读卡设备的符合APDU协议的数据，每个number十六进制表示，范围是0x00~0xFF。 | **示例：** ```js +import cardEmulation from '@ohos.nfc.cardEmulation'; + +var isHceSupported = cardEmulation.isSupported(cardEmulation.FeatureType.HCE); +if (!isHceSupported) { + console.log('this device is not supported for HCE, ignore it.'); + return; +} + +// device supports HCE, transimit APDU with remote nfc reader. 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)); @@ -108,16 +136,8 @@ hceService.on("hceCmd", (err, res) => { console.log('callback => Operation hceCmd failed. Cause: ' + err.data); } }) -``` -## FeatureType -表示NFC支持的卡模拟类型枚举。 - -**系统能力**：SystemCapability.Communication.NFC.Core - -| 名称 | 默认值 | 说明 | -| -------- | -------- | -------- | -| HCE | 0 | 该常量用于检查是否支持 HCE 卡模拟。 | -| UICC | 1 | 该常量用于检查是否支持 SIM 卡模拟。 | -| ESE | 2 | 该常量用于检查是否支持ESE卡模拟。 | +// stop HCE when the application exit the nfc card emulation. +hceService.stopHCE(); +``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-nfcController.md b/zh-cn/application-dev/reference/apis/js-apis-nfcController.md index 2e77f939b7..0217b81862 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-nfcController.md +++ b/zh-cn/application-dev/reference/apis/js-apis-nfcController.md @@ -1,6 +1,6 @@ # 标准NFC -本模块主要用于操作及管理NFC。 +本模块主要用于管理NFC状态，包括打开和关闭NFC，读取NFC的状态等。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -12,12 +12,24 @@ import controller from '@ohos.nfc.controller'; ``` +## NfcState + +定义不同的NFC状态值。 + +**系统能力**：SystemCapability.Communication.NFC.Core + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| STATE_OFF | 1 | NFC已关闭状态。 | +| STATE_TURNING_ON | 2 | NFC正在打开状态。 | +| STATE_ON | 3 | NFC已打开状态。 | +| STATE_TURNING_OFF | 4 | NFC正在关闭状态。 | ## controller.isNfcAvailable isNfcAvailable(): boolean -查询是否有NFC功能 +查询设备是否有NFC能力。 **系统能力**：SystemCapability.Communication.NFC.Core @@ -25,7 +37,7 @@ isNfcAvailable(): boolean | **类型** | **说明** | | -------- | -------- | -| boolean | true:有NFC功能， false:无NFC功能。 | +| boolean | true: 设备具备NFC能力， false: 设备不具备NFC能力。 | ## controller.openNfc @@ -42,7 +54,7 @@ openNfc(): boolean | **类型** | **说明** | | -------- | -------- | -| boolean | true:打开NFC成功， false:打开NFC失败。 | +| boolean | true: 打开NFC成功， false: 打开NFC失败。 | ## controller.closeNfc @@ -58,7 +70,7 @@ closeNfc(): boolean | **类型** | **说明** | | -------- | ------------------------------------------- | -| boolean | true:关闭NFC成功， false:关闭NFC失败。 | +| boolean | true: 关闭NFC成功， false: 关闭NFC失败。 | ## controller.isNfcOpen @@ -72,11 +84,11 @@ isNfcOpen(): boolean | **类型** | **说明** | | -------- | ----------------------------------- | -| boolean | true:NFC打开， false:NFC关闭。 | +| boolean | true: NFC是打开的， false: NFC是关闭的。 | ## controller.getNfcState -getNfcState(): NfcState +getNfcState(): [NfcState](#nfcstate) 查询NFC状态。 @@ -86,13 +98,13 @@ getNfcState(): NfcState | **类型** | **说明** | | -------- | ---------------------- | -| NfcState | 详细请见NfcState枚举值 | +| [NfcState](#nfcstate) | NFC状态值，详细请见[NfcState](#nfcstate)枚举值。 | ## controller.on('nfcStateChange') -on(type: "nfcStateChange", callback: Callback<NfcState>): void +on(type: "nfcStateChange", callback: Callback<[NfcState](#nfcstate)>): void -注册NFC开关状态事件。 +注册NFC开关状态事件，通过Callback方式获取NFC状态的变化通知。 **系统能力**：SystemCapability.Communication.NFC.Core @@ -100,16 +112,16 @@ on(type: "nfcStateChange", callback: Callback<NfcState>): void | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"nfcStateChange"字符串 | - | callback | Callback<NfcState> | 是 | 状态改变回调函数。 | + | type | string | 是 | 固定填"nfcStateChange"字符串。 | + | callback | Callback<[NfcState](#nfcstate)> | 是 | NFC状态改变通知的回调函数。 | ## controller.off('nfcStateChange') -off(type: "nfcStateChange", callback?: Callback<NfcState>): void +off(type: "nfcStateChange", callback?: Callback<[NfcState](#nfcstate)>): void -取消NFC开关状态事件的注册。 +取消NFC开关状态事件的注册，取消后NFC状态变化时，就不会再收到Callback的通知。 **系统能力**：SystemCapability.Communication.NFC.Core @@ -117,36 +129,38 @@ off(type: "nfcStateChange", callback?: Callback<NfcState>): void | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"nfcStateChange"字符串 | -| callback | Callback<NfcState> | 否 | 状态改变回调函数。如果callback不填，将“去注册”该事件关联的所有回调函数。 | + | type | string | 是 | 固定填"nfcStateChange"字符串。 | +| callback | Callback<[NfcState](#nfcstate)> | 否 | NFC状态改变回调函数，可以空缺不填。 | **示例** ```js - import nfcController from '@ohos.nfcController'; - - var NFC_STATE_NOTIFY = "nfcStateChange"; - - var recvNfcStateNotifyFunc = result => { - console.info("nfc state receive state: " + result); + import controller from '@ohos.nfc.controller'; + + // callback key definition + var NFC_STATE_CALLBACK_KEY = "nfcStateChange"; + + // register callback to receive the nfc state changed notification + controller.on(NFC_STATE_CALLBACK_KEY, (err, nfcState)=> { + if (err) { + console.log("controller on callback err: " + err); + } else { + console.log("controller on callback nfcState: " + nfcState); + } + }); + + // open nfc, require permission: ohos.permission.MANAGE_SECURE_SETTINGS + if (!controller.isNfcOpen()) { + var ret = controller.openNfc(); + console.log("controller openNfc ret: " + ret); } - - // 注册事件 - nfcController.on(NFC_STATE_NOTIFY, recvNfcStateNotifyFunc); - - // 解注册事件 - nfcController.off(NFC_STATE_NOTIFY, recvNfcStateNotifyFunc); - ``` - -## NfcState - -表示NFC状态的枚举。 -**系统能力**：SystemCapability.Communication.NFC.Core + // close nfc, require permission: ohos.permission.MANAGE_SECURE_SETTINGS + if (controller.isNfcOpen()) { + var ret = controller.closeNfc(); + console.log("controller closeNfc ret: " + ret); + } -| 名称 | 默认值 | 说明 | -| -------- | -------- | -------- | -| STATE_OFF | 1 | NFC关闭状态 | -| STATE_TURNING_ON | 2 | NFC正在打开状态 | -| STATE_ON | 3 | NFC打开状态 | -| STATE_TURNING_OFF | 4 | NFC正在关闭状态 | + // unregister callback + controller.off(NFC_STATE_CALLBACK_KEY); + ``` -- GitLab