harmony 鸿蒙@ohos.enterprise.wifiManager(Wi-Fi管理)
@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。
以下情况下,调用本接口会报策略冲突:
- 已经通过setDiallowedPolicy接口禁用了设备Wi-Fi能力。通过setDiallowedPolicy解除Wi-Fi禁用后,可解除冲突。
- 已经通过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<WifiAccessInfo>): void
移除Wi-Fi白名单。若移除白名单中的部分Wi-Fi,则当前设备仅允许连接剩下未移除的Wi-Fi。若移除白名单中的所有Wi-Fi,则当前设备可以连接任意Wi-Fi。
需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI
系统能力: SystemCapability.Customization.EnterpriseDeviceManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
admin | Want | 是 | 企业设备管理扩展组件。 |
list | Array<WifiAccessInfo> | 是 | 待移除的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<WifiAccessInfo>
获取Wi-Fi白名单。
需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI
系统能力: SystemCapability.Customization.EnterpriseDeviceManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
admin | Want | 是 | 企业设备管理扩展组件。 |
返回值:
类型 | 说明 |
---|---|
Array<WifiAccessInfo> | 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<WifiAccessInfo>): void
添加Wi-Fi黑名单。添加黑名单后当前设备不允许连接该名单下的Wi-Fi。
以下情况下,调用本接口会报策略冲突:
- 已经通过setDisallowedPolicy接口禁用了设备Wi-Fi能力。通过setDisallowedPolicy解除Wi-Fi禁用后,可解除冲突。
- 已经通过addAllowedWifiList接口添加了Wi-Fi白名单。通过removeAllowedWifiList移除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.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<WifiAccessInfo>): void
移除Wi-Fi黑名单。若移除黑名单中的部分Wi-Fi,则当前设备不允许连接黑名单内剩余的Wi-Fi。若移除黑名单中的所有Wi-Fi,则当前设备可以连接任意的Wi-Fi。
需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI
系统能力: SystemCapability.Customization.EnterpriseDeviceManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
admin | Want | 是 | 企业设备管理扩展组件。 |
list | Array<WifiAccessInfo> | 是 | 待移除的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<WifiAccessInfo>
获取Wi-Fi黑名单。
需要权限: ohos.permission.ENTERPRISE_MANAGE_WIFI
系统能力: SystemCapability.Customization.EnterpriseDeviceManager
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
admin | Want | 是 | 企业设备管理扩展组件。 |
返回值:
类型 | 说明 |
---|---|
Array<WifiAccessInfo> | 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。 调用addAllowedWifiList和removeAllowedWifiList时为必填。 调用addDisallowedWifiList和removeDisallowedWifiList时为选填(默认值为空字符串)。 |
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 Equivalent Privacy (WEP)加密类型。 |
WIFI_SEC_TYPE_PSK | 3 | Pre-shared key (PSK)加密类型。 |
WIFI_SEC_TYPE_SAE | 4 | Simultaneous Authentication of Equals (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<string> | 是 | 域信息。 |
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 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility(企业设备管理扩展能力)
harmony 鸿蒙@ohos.enterprise.accountManager(账户管理)(系统接口)
harmony 鸿蒙@ohos.enterprise.accountManager(账户管理)
harmony 鸿蒙@ohos.enterprise.adminManager(企业设备管理)(系统接口)
harmony 鸿蒙@ohos.enterprise.adminManager (admin权限管理)
harmony 鸿蒙@ohos.enterprise.applicationManager(应用管理)(系统接口)
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦