@ohos.net.connection (Network Connection Management)
The network connection management module provides basic network management capabilities. You can obtain the default active data network or the list of all active data networks, enable or disable the airplane mode, and obtain network capability information.
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.createNetConnection
createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection
Creates a NetConnection object. netSpecifier specifies the network, and timeout specifies the timeout interval in ms. timeout is configurable only when netSpecifier is specified. If neither of them is present, the default network is used.
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
// For the default network, you do not need to pass in parameters.
let netConnection = connection.createNetConnection()
// For the cellular network, you need to pass in related network parameters. If the timeout parameter is not specified, the timeout value is 0 by default.
let netConnectionCellular = connection.createNetConnection({
netCapabilities: {
bearerTypes: [connection.NetBearType.BEARER_CELLULAR]
}
})
connection.getDefaultNet
getDefaultNet(callback: AsyncCallback<NetHandle>): void
Obtains the default active data network. This API uses an asynchronous callback to return the result. You can use getNetCapabilities to obtain information such as the network type and capabilities.
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. If the default activated data network is obtained successfully, err is undefined and data is the default activated data network. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet(function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
})
connection.getDefaultNet
getDefaultNet(): Promise<NetHandle>
Obtains the default active data network. This API uses a promise to return the result. You can use getNetCapabilities to obtain information such as the network type and capabilities.
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. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (data) {
console.log(JSON.stringify(data))
})
connection.getDefaultNetSync9+
getDefaultNetSync(): NetHandle
Obtains the default active data network in synchronous mode. You can use getNetCapabilities to obtain information such as the network type and capabilities.
Required permission: ohos.permission.GET_NETWORK_INFO
System capability: SystemCapability.Communication.NetManager.Core
Return value
Type | Description |
---|---|
NetHandle | Handle of the default active data network. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
let netHandle = connection.getDefaultNetSync();
connection.getAppNet9+
getAppNet(callback: AsyncCallback<NetHandle>): void
Obtains information about the network bound to an application. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<NetHandle> | Yes | Callback used to return the result. If information about the network bound to the application is successfully obtained, err is undefined and data is the obtained network information. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getAppNet(function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
})
connection.getAppNet9+
getAppNet(): Promise<NetHandle>;
Obtains information about the network bound to an application. This API uses a promise to return the result.
System capability: SystemCapability.Communication.NetManager.Core
Return value
Type | Description |
---|---|
Promise<NetHandle> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getAppNet().then((data) => {
console.info(JSON.stringify(data));
}).catch(error => {
console.info(JSON.stringify(error));
})
connection.SetAppNet9+
setAppNet(netHandle: NetHandle, callback: AsyncCallback<void>): void
Binds an application to the specified network, so that the application can access the external network only through this network. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Handle of the data network. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the application is successfully bound to the specified network, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet(function (error, netHandle) {
connection.setAppNet(netHandle, (error, data) => {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
});
})
connection.SetAppNet9+
setAppNet(netHandle: NetHandle): Promise<void>;
Binds an application to the specified network, so that the application can access the external network only through this network. This API uses a promise to return the result.
Required permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
netHandle | NetHandle | Yes | Handle of the data network. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.setAppNet(netHandle).then(() => {
console.log("success")
}).catch(error => {
console.log(JSON.stringify(error))
})
})
connection.getAllNets
getAllNets(callback: AsyncCallback<Array<NetHandle>>): void
Obtains the list of all connected 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. If the list of all connected networks is obtained successfully, err is undefined and data is the list of activated data networks. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getAllNets(function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
});
connection.getAllNets
getAllNets(): Promise<Array<NetHandle>>
Obtains the list of all connected 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. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getAllNets().then(function (data) {
console.log(JSON.stringify(data))
});
connection.getConnectionProperties
getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback<ConnectionProperties>): void
Obtains connection properties of the network corresponding to the 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 | Handle of the data network. |
callback | AsyncCallback<ConnectionProperties> | Yes | Callback used to return the result. If the connection properties of the network corresponding to the netHandle is obtained successfully, err is undefined and data is the obtained network connection information. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getConnectionProperties(netHandle, function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
})
})
connection.getConnectionProperties
getConnectionProperties(netHandle: NetHandle): Promise<ConnectionProperties>
Obtains connection properties of the network corresponding to the 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 | Handle of the data network. |
Return value
Type | Description |
---|---|
Promise<ConnectionProperties> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getConnectionProperties(netHandle).then(function (data) {
console.log(JSON.stringify(data))
})
})
connection.getNetCapabilities
getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback<NetCapabilities>): void
Obtains capability information of the network corresponding to the 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 | Handle of the data network. |
callback | AsyncCallback<NetCapabilities> | Yes | Callback used to return the result. If the capability information of the network corresponding to the netHandle is obtained successfully, err is undefined and data is the obtained network capability information. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getNetCapabilities(netHandle, function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
})
})
connection.getNetCapabilities
getNetCapabilities(netHandle: NetHandle): Promise<NetCapabilities>
Obtains capability information of the network corresponding to the 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 | Handle of the data network. |
Return value
Type | Description |
---|---|
Promise<NetCapabilities> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
connection.getNetCapabilities(netHandle).then(function (data) {
console.log(JSON.stringify(data))
})
})
connection.isDefaultNetMetered9+
isDefaultNetMetered(callback: AsyncCallback<boolean>): void
Checks whether the data traffic usage on the current network is metered. 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<boolean> | Yes | Callback used to return the result. The value true indicates the data traffic usage is metered. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.isDefaultNetMetered(function (error, data) {
console.log(JSON.stringify(error))
console.log('data: ' + data)
})
connection.isDefaultNetMetered9+
isDefaultNetMetered(): Promise<boolean>
Checks whether the data traffic usage on the current network is metered. 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<boolean> | Promise used to return the result. The value true indicates the data traffic usage is metered. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.isDefaultNetMetered().then(function (data) {
console.log('data: ' + data)
})
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. You can use getDefaultNet to obtain the default data network, if any.
Required permission: ohos.permission.GET_NETWORK_INFO
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 the default data network is activated. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.hasDefaultNet(function (error, data) {
console.log(JSON.stringify(error))
console.log('data: ' + data)
})
connection.hasDefaultNet
hasDefaultNet(): Promise<boolean>
Checks whether the default data network is activated. This API uses a promise to return the result. You can use getDefaultNet to obtain the default data network, if any.
Required permission: ohos.permission.GET_NETWORK_INFO
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. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.hasDefaultNet().then(function (data) {
console.log('data: ' + data)
})
connection.enableAirplaneMode
enableAirplaneMode(callback: AsyncCallback<void>): void
Enables the airplane mode. This API uses an asynchronous callback to return the result.
System API: This is a system API.
Required permissions: ohos.permission.CONNECTIVITY_INTERNAL
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.enableAirplaneMode(function (error) {
console.log(JSON.stringify(error))
})
connection.enableAirplaneMode
enableAirplaneMode(): Promise<void>
Enables the airplane mode. This API uses a promise to return the result.
System API: This is a system API.
Required permissions: ohos.permission.CONNECTIVITY_INTERNAL
System capability: SystemCapability.Communication.NetManager.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
ID | Error Message |
---|---|
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.enableAirplaneMode().then(function (error) {
console.log(JSON.stringify(error))
})
connection.disableAirplaneMode
disableAirplaneMode(callback: AsyncCallback<void>): void
Disables the airplane mode. This API uses an asynchronous callback to return the result.
System API: This is a system API.
Required permissions: ohos.permission.CONNECTIVITY_INTERNAL
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the airplane mode is disabled successfully, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.disableAirplaneMode(function (error) {
console.log(JSON.stringify(error))
})
connection.disableAirplaneMode
disableAirplaneMode(): Promise<void>
Disables the airplane mode. This API uses a promise to return the result.
System API: This is a system API.
Required permissions: ohos.permission.CONNECTIVITY_INTERNAL
System capability: SystemCapability.Communication.NetManager.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
ID | Error Message |
---|---|
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.disableAirplaneMode().then(function (error) {
console.log(JSON.stringify(error))
})
connection.reportNetConnected
reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): void
Reports connection of the data network to the network management module. 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. If the network status is reported successfully, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
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 to the network management module. 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 that returns no value. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
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 to the network management module. 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. If the network status is reported successfully, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
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 to the network management module. 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 that returns no value. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
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 permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to resolve. |
callback | AsyncCallback<Array<NetAddress>> | Yes | Callback used to return the result. If all IP addresses are successfully obtained, err is undefined, and data is the list of all obtained IP addresses. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
let host = "xxxx";
connection.getAddressesByName(host, function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
})
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 permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to resolve. |
Return value
Type | Description |
---|---|
Promise<Array<NetAddress>> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
let host = "xxxx";
connection.getAddressesByName(host).then(function (data) {
console.log(JSON.stringify(data))
})
NetConnection
Represents the network connection handle.
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. If a listener for network status changes is registered successfully, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
2101008 | The callback is not exists. |
2101022 | The number of requests exceeded the maximum. |
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. If a listener for network status changes is unregistered successfully, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
2101007 | The same callback exists. |
Example
netConnection.unregister(function (error) {
console.log(JSON.stringify(error))
})
on('netAvailable')
on(type: 'netAvailable', callback: Callback<NetHandle>): void
Registers a listener for netAvailable events.
Model restriction: Before you call this API, make sure that you have called register to add a listener and called unregister API to unsubscribe from status changes of the default network.
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 network handle. |
Example
// Create a NetConnection object.
let netCon = connection.createNetConnection()
// Call register to register a listener.
netCon.register(function (error) {
console.log(JSON.stringify(error))
})
// Subscribe to netAvailable events. Event notifications can be received only after register is called.
netCon.on('netAvailable', function (data) {
console.log(JSON.stringify(data))
})
// Call unregister to unregister the listener.
netCon.unregister(function (error) {
console.log(JSON.stringify(error))
})
on('netBlockStatusChange')
on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void
Registers a listener for netBlockStatusChange events.
Model restriction: Before you call this API, make sure tat you have called register to add a listener and called unregister API to unsubscribe from status changes of the default network.
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 network handle (netHandle) and network status (blocked). |
Example
// Create a NetConnection object.
let netCon = connection.createNetConnection()
// Call register to register a listener.
netCon.register(function (error) {
console.log(JSON.stringify(error))
})
// Subscribe to netBlockStatusChange events. Event notifications can be received only after register is called.
netCon.on('netBlockStatusChange', function (data) {
console.log(JSON.stringify(data))
})
// Call unregister to unregister the listener.
netCon.unregister(function (error) {
console.log(JSON.stringify(error))
})
on('netCapabilitiesChange')
on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void
Registers a listener for netCapabilitiesChange events.
Model restriction: Before you call this API, make sure tat you have called register to add a listener and called unregister API to unsubscribe from status changes of the default network.
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 the network capabilities have changed. |
callback | Callback<{ netHandle: NetHandle, netCap: NetCapabilities }> | Yes | Callback used to return the network handle (netHandle) and capability information (netCap). |
Example
// Create a NetConnection object.
let netCon = connection.createNetConnection()
// Call register to register a listener.
netCon.register(function (error) {
console.log(JSON.stringify(error))
})
// Subscribe to netCapabilitiesChange events. Event notifications can be received only after register is called.
netCon.on('netCapabilitiesChange', function (data) {
console.log(JSON.stringify(data))
})
// Call unregister to unregister the listener.
netCon.unregister(function (error) {
console.log(JSON.stringify(error))
})
on('netConnectionPropertiesChange')
on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void
Registers a listener for netConnectionPropertiesChange events.
Model restriction: Before you call this API, make sure tat you have called register to add a listener and called unregister API to unsubscribe from status changes of the default network.
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 network handle (netHandle) and conection information (connectionProperties). |
Example
// Create a NetConnection object.
let netCon = connection.createNetConnection()
// Call register to register a listener.
netCon.register(function (error) {
console.log(JSON.stringify(error))
})
// Subscribe to netConnectionPropertiesChange events. Event notifications can be received only after register is called.
netCon.on('netConnectionPropertiesChange', function (data) {
console.log(JSON.stringify(data))
})
// Call unregister to unregister the listener.
netCon.unregister(function (error) {
console.log(JSON.stringify(error))
})
on('netLost')
on(type: 'netLost', callback: Callback<NetHandle>): void
Registers a listener for netLost events.
Model restriction: Before you call this API, make sure tat you have called register to add a listener and called unregister API to unsubscribe from status changes of the default network.
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 network handle (netHandle). |
Example
// Create a NetConnection object.
let netCon = connection.createNetConnection()
// Call register to register a listener.
netCon.register(function (error) {
console.log(JSON.stringify(error))
})
// Subscribe to netLost events. Event notifications can be received only after register is called.
netCon.on('netLost', function (data) {
console.log(JSON.stringify(data))
})
// Call unregister to unregister the listener.
netCon.unregister(function (error) {
console.log(JSON.stringify(error))
})
on('netUnavailable')
on(type: 'netUnavailable', callback: Callback<void>): void
Registers a listener for netUnavailable events.
Model restriction: Before you call this API, make sure tat you have called register to add a listener and called unregister API to unsubscribe from status changes of the default network.
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, which is empty. |
Example
// Create a NetConnection object.
let netCon = connection.createNetConnection()
// Call register to register a listener.
netCon.register(function (error) {
console.log(JSON.stringify(error))
})
// Subscribe to netUnavailable events. Event notifications can be received only after register is called.
netCon.on('netUnavailable', function (data) {
console.log(JSON.stringify(data))
})
// Call unregister to unregister the listener.
netCon.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
Attributes
Name | Type | Mandatory | Description |
---|---|---|---|
netId | number | Yes | Network ID. The value 0 indicates no default network. Any other value must be greater than or equal to 100. |
bindSocket9+
bindSocket(socketParam: TCPSocket | UDPSocket, callback: AsyncCallback<void>): void
Binds a TCPSocket or UDPSocket object to the data network. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
socketParam | TCPSocket | UDPSocket | Yes | TCPSocket or UDPSocket object. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the TCPSocket or UDPSocket object is successfully bound to the current network, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
import socket from "@ohos.net.socket";
connection.getDefaultNet().then((netHandle) => {
var tcp = socket.constructTCPSocketInstance();
var udp = socket.constructUDPSocketInstance();
let socketType = "TCPSocket";
if (socketType == "TCPSocket") {
tcp.bind({
address: '192.168.xx.xxx', port: 8080, family: 1
}, error => {
if (error) {
console.log('bind fail');
return;
}
netHandle.bindSocket(tcp, (error, data) => {
if (error) {
console.log(JSON.stringify(error));
} else {
console.log(JSON.stringify(data));
}
})
})
} else {
let callback = value => {
console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo);
}
udp.on('message', callback);
udp.bind({
address: '192.168.xx.xxx', port: 8080, family: 1
}, error => {
if (error) {
console.log('bind fail');
return;
}
udp.on('message', (data) => {
console.log(JSON.stringify(data))
});
netHandle.bindSocket(udp, (error, data) => {
if (error) {
console.log(JSON.stringify(error));
} else {
console.log(JSON.stringify(data));
}
})
})
}
})
bindSocket9+
bindSocket(socketParam: TCPSocket | UDPSocket): Promise<void>;
Binds a TCPSocket or UDPSocket object to the data network. This API uses a promise to return the result.
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
socketParam | TCPSocket | UDPSocket | Yes | TCPSocket or UDPSocket object. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
ID | Error Message |
---|---|
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
import socket from "@ohos.net.socket";
connection.getDefaultNet().then((netHandle) => {
var tcp = socket.constructTCPSocketInstance();
var udp = socket.constructUDPSocketInstance();
let socketType = "TCPSocket";
if (socketType == "TCPSocket") {
tcp.bind({
address: '192.168.xx.xxx', port: 8080, family: 1
}, error => {
if (error) {
console.log('bind fail');
return;
}
netHandle.bindSocket(tcp).then((data) => {
console.log(JSON.stringify(data));
}).catch(error => {
console.log(JSON.stringify(error));
})
})
} else {
let callback = value => {
console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo);
}
udp.on('message', callback);
udp.bind({
address: '192.168.xx.xxx', port: 8080, family: 1
}, error => {
if (error) {
console.log('bind fail');
return;
}
udp.on('message', (data) => {
console.log(JSON.stringify(data));
})
netHandle.bindSocket(udp).then((data) => {
console.log(JSON.stringify(data));
}).catch(error => {
console.log(JSON.stringify(error));
})
})
}
})
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 permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to resolve. |
callback | AsyncCallback<Array<NetAddress>> | Yes | Callback used to return the result. If all IP addresses are successfully obtained, err is undefined, and data is the list of all obtained IP addresses. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressesByName(host, function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
})
})
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 permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to resolve. |
Return value
Type | Description |
---|---|
Promise<Array<NetAddress>> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressesByName(host).then(function (data) {
console.log(JSON.stringify(data))
})
})
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 permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to resolve. |
callback | AsyncCallback<NetAddress> | Yes | Callback used to return the result. If the first IP address is obtained successfully, err is undefined, and data is the first obtained IP address. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressByName(host, function (error, data) {
console.log(JSON.stringify(error))
console.log(JSON.stringify(data))
})
})
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 permissions: ohos.permission.INTERNET
System capability: SystemCapability.Communication.NetManager.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
host | string | Yes | Host name to resolve. |
Return value
Type | Description |
---|---|
Promise<NetAddress> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
201 | Permission denied. |
401 | Parameter error. |
2100001 | Invalid parameter value. |
2100002 | Operation failed. Cannot connect to service. |
2100003 | System internal error. |
Example
connection.getDefaultNet().then(function (netHandle) {
let host = "xxxx";
netHandle.getAddressByName(host).then(function (data) {
console.log(JSON.stringify(data))
})
})
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 has the Internet access capability, which is set by the network provider. |
NET_CAPABILITY_NOT_VPN | 15 | The network does not use a virtual private network (VPN). |
NET_CAPABILITY_VALIDATED | 16 | The Internet access capability of the network is successfully verified by the connection management module. |
NetBearType
Enumerates network types.
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. |
NetSpecifier
Provides an instance that bears data network capabilities.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Mandatory | Description |
---|---|---|---|
netCapabilities | NetCapabilities | Yes | Network transmission capabilities and bearer types of the data network. |
bearerPrivateIdentifier | string | No | 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 | Mandatory | Description |
---|---|---|---|
linkUpBandwidthKbps | number | No | Uplink (from the device to the network) bandwidth. |
linkDownBandwidthKbps | number | No | Downlink (from the network to the device) bandwidth. |
networkCap | Array<NetCap> | No | Network capability. |
bearerTypes | Array<NetBearType> | Yes | Network type. |
ConnectionProperties
Defines the network connection properties.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Mandatory | Description |
---|---|---|---|
interfaceName | string | Yes | Network interface card (NIC) name. |
domains | string | Yes | Domain. The default value is "". |
linkAddresses | Array<LinkAddress> | Yes | Link information. |
routes | Array<RouteInfo> | Yes | Route information. |
dnses | Array<NetAddress> | Yes | Network address. For details, see NetAddress. |
mtu | number | Yes | Maximum transmission unit (MTU). |
RouteInfo
Defines network route information.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Mandatory | Description |
---|---|---|---|
interface | string | Yes | NIC name. |
destination | LinkAddress | Yes | Destination address. |
gateway | NetAddress | Yes | Gateway address. |
hasGateway | boolean | Yes | Whether a gateway is present. |
isDefaultRoute | boolean | Yes | Whether the route is the default route. |
LinkAddress
Defines network link information.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Mandatory | Description |
---|---|---|---|
address | NetAddress | Yes | Link address. |
prefixLength | number | Yes | Length of the link address prefix. |
NetAddress
Defines a network address.
System capability: SystemCapability.Communication.NetManager.Core
Name | Type | Mandatory | Description |
---|---|---|---|
address | string | Yes | Network address. |
family | number | No | Address family identifier. The value is 1 for IPv4 and 2 for IPv6. The default value is 1. |
port | number | No | Port number. The value ranges from 0 to 65535. |