From 17c8e6c7ded8939147b0af52f815d1a5e367df17 Mon Sep 17 00:00:00 2001 From: zhangxiuping Date: Tue, 3 Jan 2023 11:41:53 +0800 Subject: [PATCH] Add nfc new api 9 docs. Signed-off-by: zhangxiuping --- .../reference/apis/js-apis-cardEmulation.md | 48 ++- .../reference/apis/js-apis-nfcController.md | 61 +++ .../reference/apis/js-apis-nfcTag.md | 148 ++++++- .../reference/apis/js-apis-nfctech.md | 16 - .../reference/apis/js-apis-tagSession.md | 367 ++++++++++++++++++ .../reference/errorcodes/errorcode-nfc.md | 8 +- .../OpenHarmony_3.2.10.3/changelogs-nfc.md | 61 +++ 7 files changed, 677 insertions(+), 32 deletions(-) create mode 100644 zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.3/changelogs-nfc.md 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 cf66358043..e6f45e0b61 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md @@ -16,31 +16,37 @@ import cardEmulation from '@ohos.nfc.cardEmulation'; 定义不同的NFC卡模拟类型。 +> **说明：** +> 从 API version 6 开始支持，从 API version 9 开始废弃，建议使用[hasHceCapability](#hashcecapability9)替代。 + **系统能力：** SystemCapability.Communication.NFC.CardEmulation | 名称 | 值 | 说明 | | -------- | -------- | -------- | | HCE | 0 | HCE 卡模拟。 | | UICC | 1 | SIM 卡模拟。 | -| ESE | 2 | ESE卡模拟。 | +| ESE | 2 | ESE卡模拟。 | -## CardType +## CardType9+ -定义卡模拟应用是支付类型，还是非支付类型。 +定义卡模拟应用所使用的业务类型，是支付类型，还是其他类型。 **系统能力：** SystemCapability.Communication.NFC.CardEmulation | 名称 | 值 | 说明 | | -------- | -------- | -------- | -| PAYMENT | "payment" | 卡模拟应用是支付类型。 | -| OTHER | "other" | 卡模拟应用是非支付类型。 | +| PAYMENT | "payment" | 卡模拟应用所使用的业务是支付类型。 | +| OTHER | "other" | 卡模拟应用所使用的业务是其他类型。 | -## cardEmulation.isSupported +## isSupported isSupported(feature: number): boolean 是否支持某种类型的卡模拟。 +> **说明：** +> 从 API version 6 开始支持，从 API version 9 开始废弃，建议使用[hasHceCapability](#hashcecapability9)替代。 + **系统能力：** SystemCapability.Communication.NFC.CardEmulation **参数：** @@ -55,20 +61,38 @@ isSupported(feature: number): boolean | -------- | -------- | | boolean | true: 支持该类型卡模拟， false: 不支持该类型卡模拟。| -## cardEmulation.isDefaultService +## hasHceCapability9+ + +hasHceCapability(): boolean + +判断是否支持HCE功能。 + +**系统能力：** SystemCapability.Communication.NFC.CardEmulation + +**需要权限：** ohos.permission.NFC_CARD_EMULATION + +**返回值：** + +| **类型** | **说明** | +| -------- | -------- | +| boolean | true: 支持HCE， false: 不支持HCE。| + +## isDefaultService9+ isDefaultService(elementName: ElementName, type: CardType): boolean -判断指定的应用是否为默认支付应用。 +判断指定的应用是否为指定业务类型的默认应用。 **系统能力：** SystemCapability.Communication.NFC.CardEmulation +**需要权限：** ohos.permission.NFC_CARD_EMULATION + **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | -------- | ---- | ----------------------- | | elementName | [ElementName](js-apis-bundleManager-elementName.md#elementname) | 是 | 应用的描述，由Bundle名称和组件名称组成。 | -| type | [CardType](#cardtype) | 是 | 支付类型。 | +| type | [CardType](#cardtype9) | 是 | 卡模拟业务类型。 | **返回值：** @@ -87,6 +111,12 @@ if (!isHceSupported) { return; } +var hasHceCap = cardEmulation.hasHceCapability(); +if (!hasHceCap) { + console.log('this device hasHceCapability false, ignore it.'); + return; +} + var elementName = { "bundleName": "com.test.cardemulation", "abilityName": "com.test.cardemulation.MainAbility", 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 a82e48c76e..b46c3e52c4 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-nfcController.md +++ b/zh-cn/application-dev/reference/apis/js-apis-nfcController.md @@ -31,6 +31,9 @@ isNfcAvailable(): boolean 查询设备是否有NFC能力。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用canIUse("SystemCapability.Communication.NFC.Core")替代。 + **系统能力：** SystemCapability.Communication.NFC.Core **返回值：** @@ -46,6 +49,9 @@ openNfc(): boolean 打开NFC开关。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[enableNfc](#controllerenablenfc9)替代。 + **需要权限：** ohos.permission.MANAGE_SECURE_SETTINGS **系统能力：** SystemCapability.Communication.NFC.Core @@ -56,12 +62,33 @@ openNfc(): boolean | -------- | -------- | | boolean | true: 打开NFC成功， false: 打开NFC失败。 | +## controller.enableNfc9+ + +enableNfc(): boolean + +打开NFC开关。 + +**需要权限：** ohos.permission.MANAGE_SECURE_SETTINGS + +**系统能力：** SystemCapability.Communication.NFC.Core + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100101 | NFC state is abnormal in service. | + ## controller.closeNfc closeNfc(): boolean 关闭NFC开关。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[disableNfc](#controllerdisablenfc9)替代。 + **需要权限：** ohos.permission.MANAGE_SECURE_SETTINGS **系统能力：** SystemCapability.Communication.NFC.Core @@ -72,6 +99,24 @@ closeNfc(): boolean | -------- | ------------------------------------------- | | boolean | true: 关闭NFC成功， false: 关闭NFC失败。 | +## controller.disableNfc9+ + +disableNfc(): boolean + +关闭NFC开关。 + +**需要权限：** ohos.permission.MANAGE_SECURE_SETTINGS + +**系统能力：** SystemCapability.Communication.NFC.Core + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100101 | NFC state is abnormal in service. | + ## controller.isNfcOpen isNfcOpen(): boolean @@ -150,12 +195,28 @@ if (!controller.isNfcOpen()) { console.log("controller openNfc ret: " + ret); } +// from api9, use 'enableNfc' to open nfc. +try { + controller.enableNfc(); + console.log("controller enableNfc success"); +} catch (busiError) { + console.log("controller enableNfc busiError: " + busiError); +} + // close nfc, require permission: ohos.permission.MANAGE_SECURE_SETTINGS if (controller.isNfcOpen()) { var ret = controller.closeNfc(); console.log("controller closeNfc ret: " + ret); } +// from api9, use 'disableNfc' to close nfc. +try { + controller.disableNfc(); + console.log("controller disableNfc success"); +} catch (busiError) { + console.log("controller disableNfc busiError: " + busiError); +} + // unregister callback controller.off("nfcStateChange"); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-nfcTag.md b/zh-cn/application-dev/reference/apis/js-apis-nfcTag.md index 3c1f33040c..d7ebd70b23 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-nfcTag.md +++ b/zh-cn/application-dev/reference/apis/js-apis-nfcTag.md @@ -126,64 +126,204 @@ getNfcATag(tagInfo: [TagInfo](#taginfo)): [NfcATag](js-apis-nfctech.md#nfcatag) 获取NFC A类型Tag对象，通过该对象可访问NfcA技术类型的Tag。 -**需要权限：** ohos.permission.NFC_TAG +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tag.getNfcA](#taggetnfca9)替代。 + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + +**返回值：** + +| **类型** | **说明** | +| -------- | -------- | +| [NfcATag](js-apis-nfctech.md#nfcatag) | NFC A类型Tag对象。 | + +## tag.getNfcA9+ + +getNfcA(tagInfo: [TagInfo](#taginfo)): [NfcATag](js-apis-nfctech.md#nfcatag) + +获取NFC A类型Tag对象，通过该对象可访问NfcA技术类型的Tag。 **系统能力：** SystemCapability.Communication.NFC.Tag +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + **返回值：** | **类型** | **说明** | | -------- | -------- | | [NfcATag](js-apis-nfctech.md#nfcatag) | NFC A类型Tag对象。 | +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + ## tag.getNfcBTag getNfcBTag(tagInfo: [TagInfo](#taginfo)): [NfcBTag](js-apis-nfctech.md#nfcbtag) 获取NFC B类型Tag对象，通过该对象可访问NfcB技术类型的Tag。 -**需要权限：** ohos.permission.NFC_TAG +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tag.getNfcB](#taggetnfcb9)替代。 + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + +**返回值：** + +| **类型** | **说明** | +| -------- | ---------------- | +| [NfcBTag](js-apis-nfctech.md#nfcbtag) | NFC B类型Tag对象。 | + +## tag.getNfcB9+ + +getNfcB(tagInfo: [TagInfo](#taginfo)): [NfcBTag](js-apis-nfctech.md#nfcbtag) + +获取NFC B类型Tag对象，通过该对象可访问NfcB技术类型的Tag。 **系统能力：** SystemCapability.Communication.NFC.Tag +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + **返回值：** | **类型** | **说明** | | -------- | ---------------- | | [NfcBTag](js-apis-nfctech.md#nfcbtag) | NFC B类型Tag对象。 | +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + ## tag.getNfcFTag getNfcFTag(tagInfo: [TagInfo](#taginfo)): [NfcFTag](js-apis-nfctech.md#nfcftag) 获取NFC F类型Tag对象，通过该对象可访问NfcF技术类型的Tag。 -**需要权限：** ohos.permission.NFC_TAG +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tag.getNfcF](#taggetnfcf9)替代。 + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + +**返回值：** + +| **类型** | **说明** | +| -------- | ---------------- | +| [NfcFTag](js-apis-nfctech.md#nfcftag) | NFC F类型Tag对象。 | + +## tag.getNfcF9+ + +getNfcF(tagInfo: [TagInfo](#taginfo)): [NfcFTag](js-apis-nfctech.md#nfcftag) + +获取NFC F类型Tag对象，通过该对象可访问NfcF技术类型的Tag。 **系统能力：** SystemCapability.Communication.NFC.Tag +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + **返回值：** | **类型** | **说明** | | -------- | ---------------- | | [NfcFTag](js-apis-nfctech.md#nfcftag) | NFC F类型Tag对象。 | +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + ## tag.getNfcVTag getNfcVTag(tagInfo: [TagInfo](#taginfo)): [NfcVTag](js-apis-nfctech.md#nfcvtag) 获取NFC V类型Tag对象，通过该对象可访问NfcV技术类型的Tag。 -**需要权限：** ohos.permission.NFC_TAG +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tag.getNfcV](#taggetnfcv9)替代。 + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + +**返回值：** + +| **类型** | **说明** | +| -------- | ---------------- | +| [NfcVTag](js-apis-nfctech.md#nfcvtag) | NFC V类型Tag对象。 | + +## tag.getNfcV9+ + +getNfcV(tagInfo: [TagInfo](#taginfo)): [NfcVTag](js-apis-nfctech.md#nfcvtag) + +获取NFC V类型Tag对象，通过该对象可访问NfcV技术类型的Tag。 **系统能力：** SystemCapability.Communication.NFC.Tag +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------- | ---- | ---------------------------------------- | +| taginfo | [TagInfo](#taginfo) | 是 | 包含Tag技术类型和相关参数，从tag.getTagInfo(want: Want)获取。 + **返回值：** | **类型** | **说明** | | -------- | ---------------- | | [NfcVTag](js-apis-nfctech.md#nfcvtag) | NFC V类型Tag对象。 | +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + ## tag.getIsoDep9+ getIsoDep(tagInfo: [TagInfo](#taginfo)): [IsoDepTag](js-apis-nfctech.md#isoDepTag9 ) diff --git a/zh-cn/application-dev/reference/apis/js-apis-nfctech.md b/zh-cn/application-dev/reference/apis/js-apis-nfctech.md index fc5241358c..122d4992bf 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-nfctech.md +++ b/zh-cn/application-dev/reference/apis/js-apis-nfctech.md @@ -26,8 +26,6 @@ getSak(): number 获取NFC-A标签的SAK值。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** @@ -52,8 +50,6 @@ getAtqa(): number[] 获取NFC-A标签的Atqa值。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** @@ -86,8 +82,6 @@ getRespAppData(): number[] 获取标签的应用程序数据。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** @@ -112,8 +106,6 @@ getRespProtocol(): number[] 获取标签的协议信息。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** @@ -146,8 +138,6 @@ getSystemCode(): number[] 从标签实例获取系统代码。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** @@ -172,8 +162,6 @@ getPmm(): number[] 从标签实例获取PMm（由IC代码和制造商参数组成）。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** @@ -206,8 +194,6 @@ getResponseFlags(): number 从标签实例实例获取响应标志。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** @@ -232,8 +218,6 @@ getDsfId(): number 从标签实例实例获取数据存储格式标识符（DSFID）。 -**需要权限：** ohos.permission.NFC_TAG - **系统能力：** SystemCapability.Communication.NFC.Tag **返回值：** diff --git a/zh-cn/application-dev/reference/apis/js-apis-tagSession.md b/zh-cn/application-dev/reference/apis/js-apis-tagSession.md index 8677dd0286..32b66bd40e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-tagSession.md +++ b/zh-cn/application-dev/reference/apis/js-apis-tagSession.md @@ -26,6 +26,9 @@ getTagInfo(): tag.TagInfo 获取该Tag被分发时，NFC服务所提供的Tag数据对象。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tag.getTagInfo](js-apis-nfcTag.md#taggettaginfo9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -54,6 +57,9 @@ connectTag(): boolean; 和标签建立连接。在从标签读取数据或将数据写入标签之前，必须调用此方法。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.connect](#tagsessionconnect9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -76,12 +82,49 @@ let connectStatus = tag.getIsoDep(tagInfo).connectTag(); console.log("connectStatus: " + connectStatus); ``` +### tagSession.connect9+ + +connect(): void; + +和标签建立连接。在从标签读取数据或将数据写入标签之前，必须调用此方法。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + +**示例：** + +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +try { + tag.getIsoDep(tagInfo).connect(); + console.log("tag connect success"); +} catch (busiError) { + console.log("tag connect busiError: " + busiError); +} +``` + ### tagSession.reset() reset(): void 重置与标签的连接。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.resetConnection](#tagsessionresetconnection9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -97,12 +140,49 @@ import tag from '@ohos.nfc.tag'; tag.getIsoDep(tagInfo).reset(); ``` +### tagSession.resetConnection()9+ + +resetConnection(): void + +重置与标签的连接。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + +**示例：** + +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +try { + tag.getIsoDep(tagInfo).resetConnection(); + console.log("tag resetConnection success"); +} catch (busiError) { + console.log("tag resetConnection busiError: " + busiError); +} +``` + ### tagSession.isTagConnected isTagConnected(): boolean 检查是否已与标签建立连接。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.isConnected](#tagsessionisconnected9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -125,12 +205,47 @@ let isTagConnected = tag.getIsoDep(tagInfo).isTagConnected(); console.log("isTagConnected: " + isTagConnected); ``` +### tagSession.isConnected9+ + +isConnected(): boolean + +检查是否已与标签建立连接。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**返回值：** + +| **类型** | **说明** | +| ------------------ | --------------------------| +| boolean | 已建立连接返回 true，未建立连接返回false。 | + +**示例：** + +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +try { + var isConnected = tag.getIsoDep(tagInfo).isConnected(); + console.log("tag isConnected = " + isConnected); +} catch (busiError) { + console.log("tag isConnected busiError: " + busiError); +} +``` + ### tagSession.getMaxSendLength getMaxSendLength(): number 查询可以发送到标签的最大数据长度。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.getMaxTransmitSize](#tagsessiongetmaxtransmitsize9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -152,12 +267,54 @@ let maxSendLen = tag.getIsoDep(tagInfo).getMaxSendLength(); console.log("tag maxSendLen: " + maxSendLen); ``` +### tagSession.getMaxTransmitSize9+ + +getMaxTransmitSize(): number + +查询可以发送到标签的最大数据长度。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**返回值：** + +| **类型** | **说明** | +| ------------------ | --------------------------| +| number | 可以发送到标签的最大数据长度，非负数。 | + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + +**示例：** +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +try { + var maxTransmitSize = tag.getIsoDep(tagInfo).getMaxTransmitSize(); + console.log("tag maxTransmitSize = " + maxTransmitSize); +} catch (busiError) { + console.log("tag getMaxTransmitSize busiError: " + busiError); +} +``` + ### tagSession.getSendDataTimeout getSendDataTimeout(): number 查询发送数据到Tag的等待超时时间，单位是毫秒。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.getTimeout](#tagsessiongettimeout9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -180,12 +337,55 @@ let sendDataTimeout = tag.getIsoDep(tagInfo).getSendDataTimeout(); console.log("tag sendDataTimeout: " + sendDataTimeout); ``` +### tagSession.getTimeout9+ + +getTimeout(): number + +查询发送数据到Tag的等待超时时间，单位是毫秒。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**返回值：** + +| **类型** | **说明** | +| ------------------ | --------------------------| +| number | 发送数据到Tag的等待超时时间，单位是毫秒，非负数。 | + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + +**示例：** + +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +try { + var timeout = tag.getIsoDep(tagInfo).getTimeout(); + console.log("tag timeout = " + timeout); +} catch (busiError) { + console.log("tag getTimeout busiError: " + busiError); +} +``` + ### tagSession.setSendDataTimeout setSendDataTimeout(timeout: number): boolean 查询发送数据到Tag的等待超时时间，单位是毫秒。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.setTimeout](#tagsessionsettimeout9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -215,12 +415,56 @@ let setStatus = tag.getIsoDep(tagInfo).setSendDataTimeout(timeoutMs); console.log("tag setSendDataTimeout setStatus: " + setStatus); ``` +### tagSession.setTimeout9+ + +setTimeout(timeout: number): void + +查询发送数据到Tag的等待超时时间，单位是毫秒。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | -------------------------------------- | +| timeout | number | 是 | 超时时间，单位毫秒，非负值。 | + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + +**示例：** + +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +let timeoutMs = 700; // change it to be correct. +try { + tag.getIsoDep(tagInfo).setTimeout(timeoutMs); + console.log("tag setTimeout success"); +} catch (busiError) { + console.log("tag setTimeout busiError: " + busiError); +} +``` + ### tagSession.sendData sendData(data: number[]): Promise 发送指令到Tag上，使用Promise方式作为异步方法。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.transmit](#tagsessiontransmit9)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -267,6 +511,9 @@ sendData(data: number[], callback: AsyncCallback): void 发送指令到Tag上，使用AsyncCallback方式作为异步方法。 +> **说明：** +> 从 API version 7 开始支持，从 API version 9 开始废弃，建议使用[tagSession.transmit](#tagsessiontransmit9-1)替代。 + **需要权限：** ohos.permission.NFC_TAG **系统能力：** SystemCapability.Communication.NFC.Tag @@ -303,3 +550,123 @@ tag.getIsoDep(tagInfo).sendData(cmdData, (err, response)=> { } }); ``` + +### tagSession.transmit9+ + +transmit(data: number[]): Promise + +发送指令到Tag上，使用Promise方式作为异步方法。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | -------------------------------------- | +| data | number[] | 是 | 要发送的指令。每个number十六进制表示，范围是0x00~0xFF。 | + +**返回值：** + +| **类型** | **说明** | +| ------------------ | --------------------------| +| Promise | 对端Tag对指令的响应数据。每个number十六进制表示，范围是0x00~0xFF。| + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + +**示例：** + +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +// connect the tag at first if not connected. +try { + if (!tag.getIsoDep(tagInfo).isConnected()) { + tag.getIsoDep(tagInfo).connect(); + } +} catch (busiError) { + console.log("tag connect busiError: " + busiError); + return; +} + +let cmdData = [0x01, 0x02, 0x03, 0x04]; // change the raw data to be correct. +try { + tag.getIsoDep(tagInfo).transmit(cmdData).then((response) => { + console.log("tagSession transmit Promise response: " + response); + }).catch((err)=> { + console.log("tagSession transmit Promise err: " + err); + }); +} catch (busiError) { + console.log("tag transmit busiError: " + busiError); + return; +} +``` + +### tagSession.transmit9+ + +transmit(data: number[], callback: AsyncCallback): void + +发送指令到Tag上，使用AsyncCallback方式作为异步方法。 + +**需要权限：** ohos.permission.NFC_TAG + +**系统能力：** SystemCapability.Communication.NFC.Tag + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | -------------------------------------- | +| data | number[] | 是 | 要发送的指令。每个number十六进制表示，范围是0x00~0xFF。 | +| callback | AsyncCallback | 是 | 回调函数，返回响应数据。每个number十六进制表示，范围是0x00~0xFF。 | + +**错误码：** + +以下错误码的详细介绍请参见[NFC错误码](../errorcodes/errorcode-nfc.md)。 + +| 错误码ID | 错误信息| +| ------- | -------| +| 3100201 | Tag running state is abnormal in service. | + +**示例：** + +```js +import tag from '@ohos.nfc.tag'; + +// see 'tag.TagInfo' at 'js-apis-nfcTag.md', tagInfo is an Object given by nfc service when tag is dispatched. +// the folowing getXXX, can be one of getIsoDep, getNdef, getMifareClassic, ... + +// connect the tag at first if not connected. +try { + if (!tag.getIsoDep(tagInfo).isConnected()) { + tag.getIsoDep(tagInfo).connect(); + } +} catch (busiError) { + console.log("tag connect busiError: " + busiError); + return; +} + +let cmdData = [0x01, 0x02, 0x03, 0x04]; // change the raw data to be correct. +try { + tag.getIsoDep(tagInfo).transmit(cmdData, (err, response)=> { + if (err) { + console.log("tagSession transmit AsyncCallback err: " + err); + } else { + console.log("tagSession transmit AsyncCallback response: " + response); + } + }); +} catch (busiError) { + console.log("tag transmit busiError: " + busiError); + return; +} + +``` diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-nfc.md b/zh-cn/application-dev/reference/errorcodes/errorcode-nfc.md index d6763eebdd..9c73fdd1a5 100644 --- a/zh-cn/application-dev/reference/errorcodes/errorcode-nfc.md +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-nfc.md @@ -4,7 +4,7 @@ **错误信息** -NFC opening or closing state is abnormal in service. +NFC state is abnormal in service. **错误描述** @@ -12,11 +12,13 @@ NFC服务内部执行NFC打开或关闭异常。 **可能原因** -和NFC服务建立通信异常。 +1. 和NFC服务建立通信异常。 +2. NFC芯片通信异常。 **处理步骤** -重新执行打开或关闭NFC。 +1. 重新执行打开或关闭NFC。 +2. 重新执行打开或关闭NFC，或重启设备尝试。 ## 3100201 diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.3/changelogs-nfc.md b/zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.3/changelogs-nfc.md new file mode 100644 index 0000000000..506de8014a --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.3/changelogs-nfc.md @@ -0,0 +1,61 @@ +# 公共通信子系统NFC JS API变更Changelog + +OpenHarmony 3.2.10.2(Mr)版本相较于OpenHarmony 3.2.beta4版本，分布式数据管理子系统的API变更如下 + +## cl.nfc.1 接口变更 +NFC部分API6到API8部分JS接口不支持抛出错误码，需要删除废弃，然后使用新的API9替换。 + +开发者需要根据以下说明对应用进行适配。 + + **变更影响** + +影响部分API6到API8部分JS接口，应用需要进行适配才可以在新版本SDK环境正常实现功能。 + +**关键的接口/组件变更** + +| 模块名 | 类名 | 方法/属性/枚举/常量 | 变更类型 | +| ------------------------- | ------------------- | ------------------------------------------------------------ | -------- | +| api/@ohos.nfc.cardEmulation.d.ts | cardEmulation | FeatureType | 废弃 | +| api/@ohos.nfc.cardEmulation.d.ts | cardEmulation | isSupported | 废弃 | +| api/@ohos.nfc.cardEmulation.d.ts | cardEmulation | hasHceCapability | 新增 | +| api/@ohos.nfc.controller.d.ts | nfcController | isNfcAvailable | 废弃 | +| api/@ohos.nfc.controller.d.ts | nfcController | openNfc | 废弃 | +| api/@ohos.nfc.controller.d.ts | nfcController | closeNfc | 废弃 | +| api/@ohos.nfc.controller.d.ts | nfcController | enableNfc | 新增 | +| api/@ohos.nfc.controller.d.ts | nfcController | disableNfc | 新增 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcATag | 废弃 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcBTag | 废弃 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcFTag | 废弃 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcVTag | 废弃 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcA | 新增 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcB | 新增 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcF | 新增 | +| api/@ohos.nfc.tag.d.ts | tag | getNfcV | 新增 | +| api/tag/tagSession.d.ts | TagSession | getTagInfo | 废弃 | +| api/tag/tagSession.d.ts | TagSession | connectTag | 废弃 | +| api/tag/tagSession.d.ts | TagSession | reset | 废弃 | +| api/tag/tagSession.d.ts | TagSession | isTagConnected | 废弃 | +| api/tag/tagSession.d.ts | TagSession | setSendDataTimeout | 废弃 | +| api/tag/tagSession.d.ts | TagSession | getSendDataTimeout | 废弃 | +| api/tag/tagSession.d.ts | TagSession | sendData | 废弃 | +| api/tag/tagSession.d.ts | TagSession | getMaxSendLength | 废弃 | +| api/tag/tagSession.d.ts | TagSession | connect | 新增 | +| api/tag/tagSession.d.ts | TagSession | resetConnection | 新增 | +| api/tag/tagSession.d.ts | TagSession | isConnected | 新增 | +| api/tag/tagSession.d.ts | TagSession | setTimeout | 新增 | +| api/tag/tagSession.d.ts | TagSession | getTimeout | 新增 | +| api/tag/tagSession.d.ts | TagSession | transmit | 新增 | +| api/tag/tagSession.d.ts | TagSession | getMaxTransmitSize | 新增 | + +**适配指导** + +查看API开发指南： +[cardEmulation-API参考](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-cardEmulation.md) + +[nfcController-API参考](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-nfcController.md) + +[tag-API参考](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-nfcTag.md) + +[TagSession-API参考](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-tagSession.md) +``` + -- GitLab