harmony 鸿蒙@ohos.enterprise.wifiManager(Wi-Fi管理)

  • 2025-06-16
  • 浏览 (2)

@ohos.enterprise.wifiManager(Wi-Fi管理)

本模块提供企业设备Wi-Fi管理能力,包括查询Wi-Fi开启状态等。

说明:

本模块首批接口从API version 12开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

本模块接口仅对设备管理应用开放,且调用接口前需激活设备管理应用,具体请参考MDM Kit开发指南

全局通用限制类策略由restrictions统一提供,若要全局禁用Wi-Fi,请参考@ohos.enterprise.restrictions(限制类策略)

导入模块

import { wifiManager } from '@kit.MDMKit';

wifiManager.isWifiActiveSync

isWifiActiveSync(admin: Want): boolean

查询当前设备Wi-Fi开启状态。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。

返回值:

类型 说明
boolean 返回Wi-Fi开启状态,true表示Wi-Fi开启,false表示Wi-Fi关闭。

错误码

以下的错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

import { Want } from '@kit.AbilityKit';
let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};

try {
  let result: boolean = wifiManager.isWifiActiveSync(wantTemp);
  console.info(`Succeeded in query is wifi active or not, result : ${result}`);
} catch (err) {
  console.error(`Failed to query is wifi active or not. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.setWifiProfileSync

setWifiProfileSync(admin: Want, profile: WifiProfile): void

为当前设备配置Wi-Fi,使连接到指定网络。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。
profile WifiProfile Wi-Fi配置信息。

错误码

以下的错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

import { Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};
let profile: wifiManager.WifiProfile = {
  'ssid': 'name',
  'preSharedKey': 'passwd',
  'securityType': wifiManager.WifiSecurityType.WIFI_SEC_TYPE_PSK
};

try {
  wifiManager.setWifiProfileSync(wantTemp, profile);
  console.info('Succeeded in setting wifi profile.');
} catch (err) {
  console.error(`Failed to set wifi profile. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.addAllowedWifiList19+

addAllowedWifiList(admin: Want, list: Array<WifiAccessInfo>): void

添加Wi-Fi白名单。添加白名单后当前设备仅允许连接该名单下的Wi-Fi。

以下情况下,调用本接口会报策略冲突:

  1. 已经通过setDiallowedPolicy接口禁用了设备Wi-Fi能力。通过setDiallowedPolicy解除Wi-Fi禁用后,可解除冲突。
  2. 已经通过addDisallowedWifiList接口添加了Wi-Fi黑名单。通过removeDisallowedWifiList移除Wi-Fi黑名单后,可解除冲突。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。
list Array<WifiAccessInfo> Wi-Fi白名单数组。数组总长度不能超过200。例如,若当前白名单数组中已有100个Wi-Fi,则最多支持通过该接口再添加100个。

错误码

以下错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
9200010 A conflict policy has been configured.
201 Permission verification failed. The application does not have the permission required to call the API.

示例:

import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  //需根据实际情况进行替换
  bundleName: 'com.example.edmtest',
  abilityName: 'com.example.edmtest.EnterpriseAdminAbility'
};
try {
  let wifiIds: Array<wifiManager.WifiAccessInfo> = [{
    //需根据实际情况进行替换
    ssid: "wifi_name",
    bssid: "68:77:24:77:A6:D8"
  }];
  wifiManager.addAllowedWifiList(wantTemp, wifiIds);
  console.info(`Succeeded in adding allowed wifi list.`);
} catch (err) {
  console.error(`Failed to add allowed wifi list. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.removeAllowedWifiList19+

removeAllowedWifiList(admin: Want, list: Array&lt;WifiAccessInfo&gt;): void

移除Wi-Fi白名单。若移除白名单中的部分Wi-Fi,则当前设备仅允许连接剩下未移除的Wi-Fi。若移除白名单中的所有Wi-Fi,则当前设备可以连接任意Wi-Fi。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。
list Array&lt;WifiAccessInfo&gt; 待移除的Wi-Fi白名单数组。数组总长度不能超过200。

错误码

以下错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.

示例:

import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  //需根据实际情况进行替换
  bundleName: 'com.example.edmtest',
  abilityName: 'com.example.edmtest.EnterpriseAdminAbility'
};
try {
  let wifiIds: Array<wifiManager.WifiAccessInfo> = [{
    //需根据实际情况进行替换
    ssid: "wifi_name",
    bssid: "68:77:24:77:A6:D8"
  }];
  wifiManager.removeAllowedWifiList(wantTemp, wifiIds);
  console.info(`Succeeded in removing allowed wifi list.`);
} catch (err) {
  console.error(`Failed to remove allowed wifi list. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.getAllowedWifiList19+

getAllowedWifiList(admin: Want): Array&lt;WifiAccessInfo&gt;

获取Wi-Fi白名单。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。

返回值:

类型 说明
Array&lt;WifiAccessInfo&gt; Wi-Fi白名单数组。

错误码

以下错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.

示例:

import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  //需根据实际情况进行替换
  bundleName: 'com.example.edmtest',
  abilityName: 'com.example.edmtest.EnterpriseAdminAbility'
};
try {
  let result: Array<wifiManager.WifiAccessInfo> = wifiManager.getAllowedWifiList(wantTemp);
  console.info(`Succeeded in getting allowed wifi list. Result: ${JSON.stringify(result)}`);
} catch (err) {
  console.error(`Failed to get allowed wifi list. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.addDisallowedWifiList19+

addDisallowedWifiList(admin: Want, list: Array&lt;WifiAccessInfo&gt;): void

添加Wi-Fi黑名单。添加黑名单后当前设备不允许连接该名单下的Wi-Fi。

以下情况下,调用本接口会报策略冲突:

  1. 已经通过setDisallowedPolicy接口禁用了设备Wi-Fi能力。通过setDisallowedPolicy解除Wi-Fi禁用后,可解除冲突。
  2. 已经通过addAllowedWifiList接口添加了Wi-Fi白名单。通过removeAllowedWifiList移除Wi-Fi白名单后,可解除冲突。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。
list Array&lt;WifiAccessInfo&gt; Wi-Fi黑名单数组。数组总长度不能超过200。例如,若当前黑名单数组中已有100个Wi-Fi,则最多支持通过该接口再添加100个。

错误码

以下错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
9200010 A conflict policy has been configured.
201 Permission verification failed. The application does not have the permission required to call the API.

示例:

import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  //需根据实际情况进行替换
  bundleName: 'com.example.edmtest',
  abilityName: 'com.example.edmtest.EnterpriseAdminAbility'
};
try {
  let wifiIds: Array<wifiManager.WifiAccessInfo> = [{
    //需根据实际情况进行替换
    ssid: "wifi_name",
    bssid: "68:77:24:77:A6:D8"
  }];
  wifiManager.addDisallowedWifiList(wantTemp, wifiIds);
  console.info(`Succeeded in adding disallowed wifi list.`);
} catch (err) {
  console.error(`Failed to add disallowed wifi list. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.removeDisallowedWifiList19+

removeDisallowedWifiList(admin: Want, list: Array&lt;WifiAccessInfo&gt;): void

移除Wi-Fi黑名单。若移除黑名单中的部分Wi-Fi,则当前设备不允许连接黑名单内剩余的Wi-Fi。若移除黑名单中的所有Wi-Fi,则当前设备可以连接任意的Wi-Fi。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。
list Array&lt;WifiAccessInfo&gt; 待移除的Wi-Fi黑名单数组。数组总长度不能超过200。

错误码

以下错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.

示例:

import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  //需根据实际情况进行替换
  bundleName: 'com.example.edmtest',
  abilityName: 'com.example.edmtest.EnterpriseAdminAbility'
};
try {
  let wifiIds: Array<wifiManager.WifiAccessInfo> = [{
    //需根据实际情况进行替换
    ssid: "wifi_name",
    bssid: "68:77:24:77:A6:D8"
  }];
  wifiManager.removeDisallowedWifiList(wantTemp, wifiIds);
  console.info(`Succeeded in removing disallowed wifi list.`);
} catch (err) {
  console.error(`Failed to remove disallowed wifi list. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.getDisallowedWifiList19+

getDisallowedWifiList(admin: Want): Array&lt;WifiAccessInfo&gt;

获取Wi-Fi黑名单。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。

返回值:

类型 说明
Array&lt;WifiAccessInfo&gt; Wi-Fi黑名单数组。

错误码

以下错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.

示例:

import { Want } from '@kit.AbilityKit';

let wantTemp: Want = {
  //需根据实际情况进行替换
  bundleName: 'com.example.edmtest',
  abilityName: 'com.example.edmtest.EnterpriseAdminAbility'
};
try {
  let result: Array<wifiManager.WifiAccessInfo> = wifiManager.getDisallowedWifiList(wantTemp);
  console.info(`Succeeded in getting disallowed wifi list. Result: ${JSON.stringify(result)}`);
} catch (err) {
  console.error(`Failed to get disallowed wifi list. Code: ${err.code}, message: ${err.message}`);
}

WifiAccessInfo19+

Wi-Fi的SSID和BSSID信息。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 类型 必填 说明
ssid string Wi-Fi热点名称,编码格式为UTF-8,最大长度为32字节(中文字符占3位,英文字符占1位)。
bssid string Wi-Fi热点的mac地址,例如:00:11:22:33:44:55。
调用addAllowedWifiListremoveAllowedWifiList时为必填。
调用addDisallowedWifiListremoveDisallowedWifiList时为选填(默认值为空字符串)。

WifiProfile

Wi-Fi配置信息。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 类型 必填 说明
ssid string 热点的SSID,编码格式为UTF-8。
bssid string 热点的BSSID。
preSharedKey string 热点的密钥。
isHiddenSsid boolean 是否是隐藏网络。true表示是隐藏网络,false表示不是隐藏网络。
securityType WifiSecurityType 加密类型。
creatorUid number 创建用户的ID。
disableReason number 禁用原因。
netId number 分配的网络ID。
randomMacType number 随机MAC类型。
randomMacAddr string 随机MAC地址。
ipType IpType IP地址类型。
staticIp IpProfile 静态IP配置信息。
eapProfile WifiEapProfile 可扩展身份验证协议配置。

WifiSecurityType

表示加密类型的枚举。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 说明
WIFI_SEC_TYPE_INVALID 0 无效加密类型。
WIFI_SEC_TYPE_OPEN 1 开放加密类型。
WIFI_SEC_TYPE_WEP 2 Wired&nbsp;Equivalent&nbsp;Privacy&nbsp;(WEP)加密类型。
WIFI_SEC_TYPE_PSK 3 Pre-shared&nbsp;key&nbsp;(PSK)加密类型。
WIFI_SEC_TYPE_SAE 4 Simultaneous&nbsp;Authentication&nbsp;of&nbsp;Equals&nbsp;(SAE)加密类型。
WIFI_SEC_TYPE_EAP 5 EAP加密类型。
WIFI_SEC_TYPE_EAP_SUITE_B 6 Suite-B 192位加密类型。
WIFI_SEC_TYPE_OWE 7 机会性无线加密类型。
WIFI_SEC_TYPE_WAPI_CERT 8 WAPI-Cert加密类型。
WIFI_SEC_TYPE_WAPI_PSK 9 WAPI-PSK加密类型。

IpType

表示IP类型的枚举。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 说明
STATIC 0 静态IP。
DHCP 1 通过DHCP获取。
UNKNOWN 2 未指定。

IpProfile

IP配置信息。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 类型 必填 说明
ipAddress number IP地址。
gateway number 网关。
prefixLength number 掩码。
dnsServers number[] DNS服务器。
domains Array&lt;string&gt; 域信息。

WifiEapProfile

可扩展身份验证协议配置信息。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 类型 必填 说明
eapMethod EapMethod AP认证方式。
phase2Method Phase2Method 第二阶段认证方式。
identity string 身份信息。
anonymousIdentity string 匿名身份。
password string 密码。
caCertAliases string CA 证书别名。
caPath string CA 证书路径。
clientCertAliases string 客户端证书别名。
certEntry Uint8Array CA 证书内容。
certPassword string CA证书密码。
altSubjectMatch string 替代主题匹配。
domainSuffixMatch string 域后缀匹配。
realm string 通行证凭证的领域。
plmn string 公共陆地移动网的直通凭证提供商。
eapSubId number SIM卡的子ID。

EapMethod

表示EAP认证方式的枚举。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 说明
EAP_NONE 0 不指定。
EAP_PEAP 1 PEAP类型。
EAP_TLS 2 TLS类型。
EAP_TTLS 3 TTLS类型。
EAP_PWD 4 PWD类型。
EAP_SIM 5 SIM类型。
EAP_AKA 6 AKA类型。
EAP_AKA_PRIME 7 AKA Prime类型。
EAP_UNAUTH_TLS 8 UNAUTH TLS类型。

Phase2Method

表示第二阶段认证方式的枚举。

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

名称 说明
PHASE2_NONE 0 不指定。
PHASE2_PAP 1 PAP类型。
PHASE2_MSCHAP 2 MSCHAP类型。
PHASE2_MSCHAPV2 3 MSCHAPV2类型。
PHASE2_GTC 4 GTC类型。
PHASE2_SIM 5 SIM类型。
PHASE2_AKA 6 AKA类型。
PHASE2_AKA_PRIME 7 AKA Prime类型。

wifiManager.turnOnWifi20+

turnOnWifi(admin: Want, isForce: boolean): void

打开Wi-Fi开关。

以下情况下,通过本接口打开Wi-Fi开关,会打开失败并提示”系统功能被禁用”:

​ 已经通过setDisallowedPolicy接口禁用了Wi-Fi。需通过setDisallowedPolicy接口启用Wi-Fi,解决”系统功能被禁用”报错。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。
isForce boolean 是否强制打开Wi-Fi功能。
true表示强制开启Wi-Fi,强制开启后不支持用户在设备上手动关闭Wi-Fi开关,必须采用turnOffWifi接口关闭。false表示非强制开启Wi-Fi,此时用户可以在设备上手动操作关闭Wi-Fi开关。

错误码

以下的错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.
203 This function is prohibited by enterprise management policies.

示例:

import { Want } from '@kit.AbilityKit';
import { wifiManager } from '@kit.MDMKit';

let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};

try {
  wifiManager.turnOnWifi(wantTemp, true);
  console.info(`Succeeded in turning on wifi.`);
} catch (err) {
  console.error(`Failed to turn on wifi. Code: ${err.code}, message: ${err.message}`);
}

wifiManager.turnOffWifi20+

turnOffWifi(admin: Want): void

关闭Wi-Fi开关。

以下情况下,通过本接口关闭Wi-Fi开关,会提示”系统功能被禁用”:

​ 已经通过setDisallowedPolicy接口禁用了Wi-Fi。需通过setDisallowedPolicy接口启用Wi-Fi,解决”系统功能被禁用”报错。

需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI

系统能力: SystemCapability.Customization.EnterpriseDeviceManager

参数:

参数名 类型 必填 说明
admin Want 企业设备管理扩展组件。

错误码

以下的错误码的详细介绍请参见企业设备管理错误码通用错误码

错误码ID 错误信息
9200001 The application is not an administrator application of the device.
9200002 The administrator application does not have permission to manage the device.
201 Permission verification failed. The application does not have the permission required to call the API.
203 This function is prohibited by enterprise management policies.

示例:

import { Want } from '@kit.AbilityKit';
import { wifiManager } from '@kit.MDMKit';

let wantTemp: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility',
};

try {
  wifiManager.turnOffWifi(wantTemp);
  console.info(`Succeeded in turning off wifi.`);
} catch (err) {
  console.error(`Failed to turn off wifi. Code: ${err.code}, message: ${err.message}`);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Mdm Kit(企业设备管理服务)

harmony 鸿蒙企业设备管理错误码

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility(企业设备管理扩展能力)

harmony 鸿蒙@ohos.enterprise.accountManager(账户管理)(系统接口)

harmony 鸿蒙@ohos.enterprise.accountManager(账户管理)

harmony 鸿蒙@ohos.enterprise.adminManager(企业设备管理)(系统接口)

harmony 鸿蒙@ohos.enterprise.adminManager (admin权限管理)

harmony 鸿蒙@ohos.enterprise.applicationManager(应用管理)(系统接口)

harmony 鸿蒙@ohos.enterprise.applicationManager(应用管理)

harmony 鸿蒙@ohos.enterprise.bluetoothManager(蓝牙管理)(系统接口)

0  赞