From a236bb52d4b2fd662711fee02211e336a4b3a91a Mon Sep 17 00:00:00 2001 From: zhangfeng Date: Mon, 7 Feb 2022 04:28:50 +0000 Subject: [PATCH] WiFi doc update Signed-off-by: zhangfeng --- .../reference/apis/js-apis-wifi.md | 482 ++++++++++++++++-- 1 file changed, 448 insertions(+), 34 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-wifi.md b/zh-cn/application-dev/reference/apis/js-apis-wifi.md index a790cd76c58..c87dff605eb 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-wifi.md +++ b/zh-cn/application-dev/reference/apis/js-apis-wifi.md @@ -6,7 +6,7 @@ ## 导入模块 -``` +```js import wifi from '@ohos.wifi'; ``` @@ -32,7 +32,7 @@ scan(): boolean - 返回值： | **类型** | **说明** | | -------- | -------- | - | boolean | true:扫描操作成功， false:扫描操作执行失败。 | + | boolean | true:扫描操作执行成功， false:扫描操作执行失败。 | ## wifi.getScanInfos @@ -59,12 +59,17 @@ getScanInfos(callback: AsyncCallback<Array<WifiScanInfo>>): void | callback | AsyncCallback< Array<[WifiScanInfo](#wifiscaninfo)>> | 是 | 扫描到的热点列表结果回调函数。 | - 示例 - ``` + ```js import wifi from '@ohos.wifi'; - - wifi.getScanInfos(result => { + + wifi.getScanInfos((err, result) => { + if (err) { + console.error("get scan info error"); + return; + } + var len = Object.keys(result).length; - console.log("wifi received scan info call back: " + len); + console.log("wifi received scan info: " + len); for (var i = 0; i < len; ++i) { console.info("ssid: " + result[i].ssid); console.info("bssid: " + result[i].bssid); @@ -78,7 +83,7 @@ getScanInfos(callback: AsyncCallback<Array<WifiScanInfo>>): void wifi.getScanInfos().then(result => { var len = Object.keys(result).length; - console.log("wifi received scan info promise: " + len); + console.log("wifi received scan info: " + len); for (var i = 0; i < len; ++i) { console.info("ssid: " + result[i].ssid); console.info("bssid: " + result[i].bssid); @@ -91,7 +96,6 @@ getScanInfos(callback: AsyncCallback<Array<WifiScanInfo>>): void }); ``` - ## WifiScanInfo WLAN热点信息。 @@ -201,17 +205,21 @@ getLinkedInfo(callback: AsyncCallback<WifiLinkedInfo>): void | callback | AsyncCallback<[WifiLinkedInfo](#wifilinkedinfo)> | 是 | 获取WLAN连接信息结果回调函数。 | - 示例 - ``` + ```js import wifi from '@ohos.wifi'; - wifi.getLinkedInfo(data => { - console.info("get wifi linked info [callback]: " + JSON.stringify(data)); + wifi.getLinkedInfo((err, data) => { + if (err) { + console.error("get linked info error"); + return; + } + console.info("get wifi linked info: " + JSON.stringify(data)); }); - + wifi.getLinkedInfo().then(data => { - console.info("get wifi linked info [promise]: " + JSON.stringify(data)); + console.info("get wifi linked info: " + JSON.stringify(data)); }).catch(error => { - console.info("linked info promise then error"); + console.info("get linked info error"); }); ``` @@ -294,6 +302,243 @@ isFeatureSupported(featureId: number): boolean | 0x20000000 | 增强开放特性。 | +## wifi.getP2pLinkedInfo8+ + +getP2pLinkedInfo(): Promise<WifiP2pLinkedInfo> + +获取P2P连接信息，使用promise方式作为异步方法。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | 返回P2P连接的相关信息。 | + + +## wifi.getP2pLinkedInfo8+ + +getP2pLinkedInfo(callback: AsyncCallback<WifiP2pLinkedInfo>): void + +获取P2P连接信息，使用callback方式作为异步方法。 + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[WifiP2pLinkedInfo](#WifiP2pLinkedInfo)> | 是 | 获取P2P连接信息结果回调函数。 | + + +## WifiP2pLinkedInfo + +提供WLAN连接的相关信息。 + +| 参数名 | 类型 | 读写属性 | 说明 | +| -------- | -------- | -------- | -------- | +| connectState | P2pConnectState | 只读 | P2P连接状态。 | +| isGroupOwner | boolean | 只读 | 是否是群组。 | +| groupOwnerAddr | string | 只读 | 群组MAC地址。 | + + +## P2pConnectState + +表示P2P连接状态的枚举。 + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| DISCONNECTED | 0 | 断开状态。 | +| CONNECTED | 1 | 连接状态。 | + + +## wifi.getCurrentGroup8+ + +getCurrentGroup(): Promise<WifiP2pGroupInfo> + +获取P2P当前组信息，使用promise方式作为异步方法。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | Promise<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> | 返回P2P当前组相关信息。 | + + +## wifi.getCurrentGroup8+ + +getCurrentGroup(callback: AsyncCallback<WifiP2pGroupInfo>): void + +获取P2P当前组信息，使用callback方式作为异步方法。 + +- 参数 + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[WifiP2pGroupInfo](#WifiP2pGroupInfo)> | 是 | 获取P2P当前组结果回调函数。 | + + +## WifiP2pGroupInfo + +表示P2P群组相关信息。 + +| 参数名 | 类型 | 读写属性 | 说明 | +| -------- | -------- | -------- | -------- | +| isP2pGo | boolean | 只读 | 是否是群组。 | +| ownerInfo | WifiP2pDevice | 只读 | 群组的设备信息。 | +| passphrase | string | 只读 | 群组密钥。 | +| interface | string | 只读 | 接口名称。 | +| groupName | string | 只读 | 群组名称。 | +| networkId | number | 只读 | 网络ID。 | +| frequency | number | 只读 | 群组的频率。 | +| clientDevices | WifiP2pDevice[] | 只读 | 接入的设备列表信息。 | +| goIpAddress | string | 只读 | 群组IP地址。 | + +## WifiP2pDevice + +表示P2P设备信息。 + +| 参数名 | 类型 | 读写属性 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceName | string | 只读 | 设备名称。 | +| deviceAddress | string | 只读 | 设备MAC地址。 | +| primaryDeviceType | string | 只读 | 主设备类型。 | +| deviceStatus | P2pDeviceStatus | 只读 | 设备状态。 | +| groupCapabilitys | number | 只读 | 群组能力。 | + +## P2pDeviceStatus + +表示设备状态的枚举。 + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| CONNECTED | 0 | 连接状态。 | +| INVITED | 1 | 邀请状态。 | +| FAILED | 2 | 失败状态。 | +| AVAILABLE | 3 | 可用状态。 | +| UNAVAILABLE | 4 | 不可用状态。 | + +## wifi.createGroup8+ + +createGroup(config: WifiP2PConfig): boolean; + +创建群组。 + +- 参数： + | **参数名** | **类型** | 必填 | **说明** | + | -------- | -------- | -------- | -------- | + | config | WifiP2PConfig | 是 | 群组配置信息。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:创建群组操作执行成功， false:创建群组操作执行失败。 | + +## WifiP2PConfig + +表示P2P配置信息。 + +| 参数名 | 类型 | 读写属性 | 说明 | +| -------- | -------- | -------- | -------- | +| deviceAddress | string | 只读 | 设备名称。 | +| netId | number | 只读 | 网络ID。创建群组时-1表示创建临时组，-2表示创建永久组。 | +| passphrase | string | 只读 | 群组密钥。 | +| groupName | string | 只读 | 群组名称。 | +| goBand | GroupOwnerBand | 只读 | 群组带宽。 | + + +## wifi.removeGroup8+ + +removeGroup(): boolean; + +移除群组。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:移除群组操作执行成功， false:移除群组操作执行失败。 | + + +## wifi.p2pConnect8+ + +p2pConnect(config: WifiP2PConfig): boolean; + +执行P2P连接。 + +- 参数： + | **参数名** | **类型** | 必填 | **说明** | + | -------- | -------- | -------- | -------- | + | config | WifiP2PConfig | 是 | 连接配置信息。 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:连接操作执行成功， false:连接操作执行失败。 | + + +## wifi.p2pCancelConnect8+ + +p2pCancelConnect(): boolean; + +取消P2P连接。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:取消连接操作执行成功， false:取消连接操作执行失败。 | + + +## wifi.startDiscoverDevices8+ + +startDiscoverDevices(): boolean; + +开始发现设备。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:发现设备操作执行成功， false:发现设备操作执行失败。 | + + +## wifi.stopDiscoverDevices8+ + +stopDiscoverDevices(): boolean; + +停止发现设备。 + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:停止发现设备操作执行成功， false:停止发现设备操作执行失败。 | + + +## wifi.deletePersistentGroup8+ + +deletePersistentGroup(netId: number): boolean; + +删除永久组。 + +- 参数： + | **参数名** | **类型** | 必填 | **说明** | + | -------- | -------- | -------- | -------- | + | netId | number | 是 | 群组网络ID | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:删除操作执行成功， false:删除操作执行失败。 | + + +## wifi.setDeviceName8+ + +setDeviceName(devName: string): boolean; + +设置设备名称。 + +- 参数： + | **参数名** | **类型** | 必填 | **说明** | + | -------- | -------- | -------- | -------- | + | devName | string | 是 | 设备名称 | + +- 返回值： + | 类型 | 说明 | + | -------- | -------- | + | boolean | true:操作执行成功， false:操作执行失败。 | + + ## wifi.on('wifiStateChange')7+ on(type: "wifiStateChange", callback: Callback<number>): void @@ -303,7 +548,7 @@ on(type: "wifiStateChange", callback: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"wifiStateChange"字符串 | + | type | string | 是 | 固定填"wifiStateChange"字符串。 | | callback | Callback<number> | 是 | 状态改变回调函数。 | - 状态改变事件的枚举。 @@ -324,26 +569,23 @@ off(type: "wifiStateChange", callback?: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"wifiStateChange"字符串 | + | type | string | 是 | 固定填"wifiStateChange"字符串。 | | callback | Callback<number> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | - 示例 - ``` + ```js import wifi from '@ohos.wifi'; - import { EventListener } from '@ohos.wifi'; - + var WIFI_POWER_STATE = "wifiStateChange"; - var listener = new EventListener(); - var recvPowerNotifyFunc = result => { - console.info("power state receive event: " + result); + console.info("Receive power state change event: " + result); } - + // Register event - listener.on(WIFI_POWER_STATE, recvPowerNotifyFunc); - + wifi.on(WIFI_POWER_STATE, recvPowerNotifyFunc); + // Unregister event - listener.off(WIFI_POWER_STATE, recvPowerNotifyFunc); + wifi.off(WIFI_POWER_STATE, recvPowerNotifyFunc); ``` @@ -356,7 +598,7 @@ on(type: "wifiConnectionChange", callback: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"wifiConnectionChange"字符串 | + | type | string | 是 | 固定填"wifiConnectionChange"字符串。 | | callback | Callback<number> | 是 | 状态改变回调函数。 | - 连接状态改变事件的枚举。 @@ -375,7 +617,7 @@ off(type: "wifiConnectionChange", callback?: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"wifiConnectionChange"字符串 | + | type | string | 是 | 固定填"wifiConnectionChange"字符串。 | | callback | Callback<number> | 否 | 连接状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | @@ -388,7 +630,7 @@ on(type: "wifiScanStateChange", callback: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"wifiScanStateChange"字符串 | + | type | string | 是 | 固定填"wifiScanStateChange"字符串。 | | callback | Callback<number> | 是 | 状态改变回调函数。 | - 扫描状态改变事件的枚举。 @@ -408,7 +650,7 @@ off(type: "wifiScanStateChange", callback?: Callback<number>): void | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | -| type | string | 是 | 固定填"wifiScanStateChange"字符串 | +| type | string | 是 | 固定填"wifiScanStateChange"字符串。 | | callback | Callback<number> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | @@ -421,7 +663,7 @@ on(type: "wifiRssiChange", callback: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"wifiRssiChange"字符串 | + | type | string | 是 | 固定填"wifiRssiChange"字符串。 | | callback | Callback<number> | 是 | 状态改变回调函数，返回以dBm为单位的RSSI值。 | @@ -434,7 +676,7 @@ off(type: "wifiRssiChange", callback?: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"wifiRssiChange"字符串 | + | type | string | 是 | 固定填"wifiRssiChange"字符串。 | | callback | Callback<number> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | @@ -447,7 +689,7 @@ on(type: "hotspotStateChange", callback: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"hotspotStateChange"字符串 | + | type | string | 是 | 固定填"hotspotStateChange"字符串。 | | callback | Callback<number> | 是 | 状态改变回调函数。 | - 热点状态改变事件的枚举。 @@ -468,5 +710,177 @@ off(type: "hotspotStateChange", callback?: Callback<number>): void - 参数 | **参数名** | **类型** | **必填** | **说明** | | -------- | -------- | -------- | -------- | - | type | string | 是 | 固定填"hotspotStateChange"字符串 | + | type | string | 是 | 固定填"hotspotStateChange"字符串。 | + | callback | Callback<number> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | + + +## wifi.on('p2pStateChange')8+ + +on(type: "p2pStateChange", callback: Callback<number>): void + +注册P2P开关状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pStateChange"字符串。 | + | callback | Callback<number> | 是 | 状态改变回调函数。 | + +- P2P状态改变事件的枚举。 + | **枚举值** | **说明** | + | -------- | -------- | + | 1 | 空闲。 | + | 2 | 打开中。 | + | 3 | 已打开。 | + | 4 | 关闭中。 | + | 5 | 已关闭。 | + +## wifi.off('p2pStateChange')8+ + +off(type: "p2pStateChange", callback?: Callback<number>): void + +取消注册P2P开关状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pStateChange"字符串。 | | callback | Callback<number> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | + + + ## wifi.on('p2pConnectionChange')8+ + +on(type: "p2pConnectionChange", callback: Callback<WifiP2pLinkedInfo>): void + +注册P2P连接状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pConnectionChange"字符串。 | + | callback | Callback<WifiP2pLinkedInfo> | 是 | 状态改变回调函数。 | + + +## wifi.off('p2pConnectionChange')8+ + +off(type: "p2pConnectionChange", callback?: Callback<WifiP2pLinkedInfo>): void + +取消注册P2P连接状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pConnectionChange"字符串。 | + | callback | Callback<WifiP2pLinkedInfo> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | + + +## wifi.on('p2pDeviceChange')8+ + +on(type: "p2pDeviceChange", callback: Callback<WifiP2pDevice>): void + +注册P2P设备状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pDeviceChange"字符串。 | + | callback | Callback<WifiP2pDevice> | 是 | 状态改变回调函数。 | + + +## wifi.off('p2pDeviceChange')8+ + +off(type: "p2pDeviceChange", callback?: Callback<WifiP2pDevice>): void + +取消注册P2P设备状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pDeviceChange"字符串。 | + | callback | Callback<WifiP2pDevice> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | + + +## wifi.on('p2pPeerDeviceChange')8+ + +on(type: "p2pPeerDeviceChange", callback: Callback<WifiP2pDevice[]>): void + +注册P2P对端设备状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pPeerDeviceChange"字符串。 | + | callback | Callback<WifiP2pDevice[]> | 是 | 状态改变回调函数。 | + + +## wifi.off('p2pPeerDeviceChange')8+ + +off(type: "p2pPeerDeviceChange", callback?: Callback<WifiP2pDevice[]>): void + +取消注册P2P对端设备状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pPeerDeviceChange"字符串。 | + | callback | Callback<WifiP2pDevice[]> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | + + +## wifi.on('p2pPersistentGroupChange')8+ + +on(type: "p2pPersistentGroupChange", callback: Callback<void>): void + +注册P2P永久组状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pPersistentGroupChange"字符串。 | + | callback | Callback<void> | 是 | 状态改变回调函数。 | + + +## wifi.off('p2pPersistentGroupChange')8+ + +off(type: "p2pPersistentGroupChange", callback?: Callback<void>): void + +取消注册P2P永久组状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pPersistentGroupChange"字符串。 | + | callback | Callback<void> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | + + +## wifi.on('p2pDiscoveryChange')8+ + +on(type: "p2pDiscoveryChange", callback: Callback<number>): void + +注册发现设备状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pDiscoveryChange"字符串。 | + | callback | Callback<number> | 是 | 状态改变回调函数。 | + +- 发现设备状态改变事件的枚举。 + | **枚举值** | **说明** | + | -------- | -------- | + | 0 | 初始状态。 | + | 1 | 发现成功。 | + + +## wifi.off('p2pDiscoveryChange')8+ + +off(type: "p2pDiscoveryChange", callback?: Callback<number>): void + +取消注册发现设备状态改变事件。 + +- 参数 + | **参数名** | **类型** | **必填** | **说明** | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 固定填"p2pDiscoveryChange"字符串。 | + | callback | Callback<number> | 否 | 状态改变回调函数。如果callback不填，将去注册该事件关联的所有回调函数。 | + + -- Gitee