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

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.