Network Connection Management
NOTE
The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Modules to Import
import connection from '@ohos.net.connection'
connection.getDefaultNet
getDefaultNet(callback: AsyncCallback<NetHandle>): void
Obtains the default active data network. This API uses an asynchronous callback to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<NetHandle> | Yes | Callback used to return the result. |
Example
connection.getDefaultNet(function (error, netHandle) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(netHandle))
})
connection.getDefaultNet
getDefaultNet(): Promise<NetHandle>
Obtains the default active data network. This API uses a promise to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Return Value
Type | Description |
---|---|
Promise<NetHandle> | Promise used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
console.log(JSON.stringify(netHandle))
})
connection.hasDefaultNet
hasDefaultNet(callback: AsyncCallback<boolean>): void
Checks whether the default data network is activated. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value true indicates that the default data network is activated. |
Example
connection.hasDefaultNet(function (error, has) {
console.log(JSON.stringify(error))
console.log(has)
})
connection.hasDefaultNet
hasDefaultNet(): Promise<boolean>
Checks whether the default data network is activated. This API uses a promise to return the result.
System capability: SystemCapability.Communication.NetManager.Core
Return Value
Type | Description |
---|---|
Promise<boolean> | Promise used to return the result. The value true indicates that the default data network is activated. |
Example
connection.hasDefaultNet().then(function (has) {
console.log(has)
})
connection.getAllNets
getAllNets(callback: AsyncCallback<Array<NetHandle>>): void
Obtains the list of all active data networks. This API uses an asynchronous callback to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Array<NetHandle>> | Yes | Callback used to return the result. |
Example
connection.getAllNets(function (error, nets) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(nets))
});
connection.getAllNets
getAllNets(): Promise<Array<NetHandle>>
Obtains the list of all active data networks. This API uses a promise to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Return Value
Type | Description |
---|---|
Promise<Array<NetHandle>> | Promise used to return the result. |
Example
connection.getAllNets().then(function (nets) {
console.log(JSON.stringify(nets))
});
connection.getConnectionProperties
getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback<ConnectionProperties>): void
Obtains connection properties of the network corresponding to given network handle. This API uses an asynchronous callback to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Network handle. |
callback | AsyncCallback<ConnectionProperties> | Yes | Callback used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getConnectionProperties(netHandle, function (error, info) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(info))
})
})
connection.getConnectionProperties
getConnectionProperties(netHandle: NetHandle): Promise<ConnectionProperties>
Obtains connection properties of the network corresponding to netHandle. This API uses a promise to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Network handle. |
Return Value
Type | Description |
---|---|
Promise<ConnectionProperties> | Promise used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getConnectionProperties(netHandle).then(function (info) {
console.log(JSON.stringify(info))
})
})
connection.getNetCapabilities
getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback<NetCapabilities>): void
Obtains capability information of the network corresponding to netHandle. This API uses an asynchronous callback to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Network handle. |
callback | AsyncCallback<NetCapabilities> | Yes | Callback used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getNetCapabilities(netHandle, function (error, info) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(info))
})
})
connection.getNetCapabilities
getNetCapabilities(netHandle: NetHandle): Promise<NetCapabilities>
Obtains capability information of the network corresponding to netHandle. This API uses a promise to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Network handle. |
Return Value
Type | Description |
---|---|
Promise<NetCapabilities> | Promise used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getNetCapabilities(netHandle).then(function (info) {
console.log(JSON.stringify(info))
})
})
connection.reportNetConnected
reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): void
Reports connection of the data network. This API uses an asynchronous callback to return the result.
Permission required: ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Handle of the data network. For details, see NetHandle. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.reportNetConnected(netHandle, function (error) {
console.log(JSON.stringify(error))
});
});
connection.reportNetConnected
reportNetConnected(netHandle: NetHandle): Promise<void>
Reports connection of the data network. This API uses a promise to return the result.
Permission required: ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Handle of the data network. For details, see NetHandle. |
Return Value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.reportNetConnected(netHandle).then(function () {
console.log(`report success`)
});
});
connection.reportNetDisconnected
reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback<void>): void
Reports disconnection of the data network. This API uses an asynchronous callback to return the result.
Permission required: ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Handle of the data network. For details, see NetHandle. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.reportNetDisconnected(netHandle, function (error) {
console.log(JSON.stringify(error))
});
});
connection.reportNetDisconnected
reportNetDisconnected(netHandle: NetHandle): Promise<void>
Reports disconnection of the data network. This API uses a promise to return the result.
Permission required: ohos.permission.GET_NETWORK_INFO and ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Handle of the data network. For details, see NetHandle. |
Return Value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.reportNetDisconnected(netHandle).then(function () {
console.log(`report success`)
});
});
connection.getAddressesByName
getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void
Resolves the host name by using the default network to obtain all IP addresses. This API uses an asynchronous callback to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to be resolved. |
callback | AsyncCallback<Array<NetAddress>> | Yes | Callback used to return the result. |
Example
let host = "xxxx";
connection.getAddressesByName(host, function (error, addresses) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(addresses))
})
connection.getAddressesByName
getAddressesByName(host: string): Promise<Array<NetAddress>>
Resolves the host name by using the default network to obtain all IP addresses. This API uses a promise to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to be resolved. |
Return Value
Type | Description |
---|---|
Promise<Array<NetAddress>> | Promise used to return the result. |
Example
let host = "xxxx";
connection.getAddressesByName(host).then(function (addresses) {
console.log(JSON.stringify(addresses))
})
connection.createNetConnection
createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection
Obtains the handle of the network specified by netSpecifier.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netSpecifier | NetSpecifier | No | Network specifier. If this parameter is not set, the default network is used. |
timeout | number | No | Timeout interval for obtaining the network specified by netSpecifier. This parameter is valid only when netSpecifier is set. |
Return Value
Type | Description |
---|---|
NetConnection | Handle of the network specified by netSpecifier. |
Example
// Default network
let netConnection = connection.createNetConnection()
// Cellular network
let netConnectionCellular = connection.createNetConnection({
netCapabilities: {
bearerTypes: [NetBearType.BEARER_CELLULAR]
}
})
NetConnection
Represents the network connection handle.
on('netAvailable')
on(type: 'netAvailable', callback: Callback<NetHandle>): void
Registers a listener for netAvailable events.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed to netAvailable. netAvailable: event indicating that the data network is available. |
callback | Callback<NetHandle> | Yes | Callback used to return the result. |
Example
netConnection.on('netAvailable', function (data) {
console.log(JSON.stringify(data))
})
on('netCapabilitiesChange')
on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void
Registers a listener for netCapabilitiesChange events.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed to netCapabilitiesChange. netCapabilitiesChange: event indicating that he network capabilities have changed. |
callback | Callback<{ netHandle: NetHandle, netCap: NetCapabilities }> | Yes | Callback used to return the result. |
Example
netConnection.on('netCapabilitiesChange', function (data) {
console.log(JSON.stringify(data))
})
on('netConnectionPropertiesChange')
on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void
Registers a listener for netConnectionPropertiesChange events.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed to netConnectionPropertiesChange. netConnectionPropertiesChange: event indicating that network connection properties have changed. |
callback | Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }> | Yes | Callback used to return the result. |
Example
netConnection.on('netConnectionPropertiesChange', function (data) {
console.log(JSON.stringify(data))
})
on('netBlockStatusChange')
on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void
Registers a listener for netBlockStatusChange events.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed to netBlockStatusChange. netBlockStatusChange: event indicating a change in the network blocking status. |
callback | Callback<{ netHandle: NetHandle, blocked: boolean }> | Yes | Callback used to return the result. |
Example
netConnection.on('netBlockStatusChange', function (data) {
console.log(JSON.stringify(data))
})
on('netLost')
on(type: 'netLost', callback: Callback<NetHandle>): void
Registers a listener for netLost events.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed to netLost. netLost: event indicating that the network is interrupted or normally disconnected. |
callback | Callback<NetHandle> | Yes | Callback used to return the result. |
Example
let netConnection1 = connection.createNetConnection()
netConnection1.on('netLost', function (data) {
console.log(JSON.stringify(data))
})
on('netUnavailable')
on(type: 'netUnavailable', callback: Callback<void>): void
Registers a listener for netUnavailable events.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed to netUnavailable. netUnavailable: event indicating that the network is unavailable. |
callback | Callback<void> | Yes | Callback used to return the result. |
Example
netConnection.on('netUnavailable', function (data) {
console.log(JSON.stringify(data))
})
register
register(callback: AsyncCallback<void>): void
Registers a listener for network status changes.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
netConnection.register(function (error) {
console.log(JSON.stringify(error))
})
unregister
unregister(callback: AsyncCallback<void>): void
Unregisters the listener for network status changes.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
netConnection.unregister(function (error) {
console.log(JSON.stringify(error))
})
NetHandle
Defines the handle of the data network.
Before invoking NetHandle APIs, call getNetHandle to obtain a NetHandle object.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Description |
---|---|---|
netId | number | Network ID. The value must be greater than or equal to 100. |
getAddressesByName
getAddressesByName(host: string, callback: AsyncCallback<Array<NetAddress>>): void
Resolves the host name by using the corresponding network to obtain all IP addresses. This API uses an asynchronous callback to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to be resolved. |
callback | AsyncCallback<Array<NetAddress>> | Yes | Callback used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressesByName(host, function (error, addresses) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(addresses))
})
})
getAddressesByName
getAddressesByName(host: string): Promise<Array<NetAddress>>
Resolves the host name by using the corresponding network to obtain all IP addresses. This API uses a promise to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to be resolved. |
Return Value
Type | Description |
---|---|
Promise<Array<NetAddress>> | Promise used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressesByName(host).then(function (addresses) {
console.log(JSON.stringify(addresses))
})
})
getAddressByName
getAddressByName(host: string, callback: AsyncCallback<NetAddress>): void
Resolves the host name by using the corresponding network to obtain the first IP address. This API uses an asynchronous callback to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to be resolved. |
callback | AsyncCallback<NetAddress> | Yes | Callback used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressByName(host, function (error, address) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(address))
})
})
getAddressByName
getAddressByName(host: string): Promise<NetAddress>
Resolves the host name by using the corresponding network to obtain the first IP address. This API uses a promise to return the result.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to be resolved. |
Return Value
Type | Description |
---|---|
Promise<NetAddress> | Promise used to return the result. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressByName(host).then(function (address) {
console.log(JSON.stringify(address))
})
})
NetSpecifier
Provides an instance that bears data network capabilities.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Description |
---|---|---|
netCapabilities | NetCapabilities | Network transmission capabilities and bearer types of the data network. |
bearerPrivateIdentifier | string | Network identifier. The identifier of a Wi-Fi network is wifi, and that of a cellular network is slot0 (corresponding to SIM card 1). |
NetCapabilities
Defines the network capability set.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Description |
---|---|---|
linkUpBandwidthKbps | number | Uplink (from the device to the network) bandwidth. |
linkDownBandwidthKbps | number | Downlink (from the network to the device) bandwidth. |
networkCap | Array<NetCap> | Network capability. |
bearerTypes | Array<NetBearType> | Network type. |
NetCap
Defines the network capability.
System capability: SystemCapability.Communication.NetManager.Core
Name | Value | Description |
---|---|---|
NET_CAPABILITY_MMS | 0 | The network can connect to the carrier's Multimedia Messaging Service Center (MMSC) to send and receive multimedia messages. |
NET_CAPABILITY_NOT_METERED | 11 | The network traffic is not metered. |
NET_CAPABILITY_INTERNET | 12 | The network can connect to the Internet. |
NET_CAPABILITY_NOT_VPN | 15 | The network does not use a Virtual Private Network (VPN). |
NET_CAPABILITY_VALIDATED | 16 | The network is available. |
NetBearType
Defines the network type.
System capability: SystemCapability.Communication.NetManager.Core
Name | Value | Description |
---|---|---|
BEARER_CELLULAR | 0 | Cellular network |
BEARER_WIFI | 1 | Wi-Fi network |
BEARER_ETHERNET | 3 | Ethernet network |
ConnectionProperties
Defines the network connection properties.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Description |
---|---|---|
interfaceName | string | NIC card name. |
domains | string | Domain. The default value is "". |
linkAddresses | Array<LinkAddress> | Link information. |
routes | Array<RouteInfo> | Route information. |
dnses | Array<NetAddress> | Network address. For details, see NetAddress. |
mtu | number | Maximum transmission unit (MTU). |
LinkAddress
Network link information.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Description |
---|---|---|
address | NetAddress | Link address. |
prefixLength | number | Length of the link address prefix. |
RouteInfo
Network route information.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Description |
---|---|---|
interface | string | NIC card name. |
destination | LinkAddress | Destination IP address. |
gateway | NetAddress | Gateway address. |
hasGateway | boolean | Whether a gateway is present. |
isDefaultRoute | boolean | Whether the route is the default route. |
NetAddress
Defines the network address.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Description |
---|---|---|
address | string | Network address. |
family | number | Address family identifier. The value is 1 for IPv4 and 2 for IPv6. The default value is 1. |
port | number | Port number. The value ranges from 0 to 65535. |