@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, where netSpecifier specifies the network, and timeout specifies the timeout duration 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

Return value

Example

import connection from '@ohos.net.connection';

// 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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultNet((error: BusinessError, data: connection.NetHandle) => {
  if (error) {
    console.error(`Failed to get default net. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.info("Succeeded to get data " + 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

Error codes

Example

import connection from '@ohos.net.connection';
connection.getDefaultNet().then((data: connection.NetHandle) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

connection.getDefaultNetSync⁹⁺

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

Error codes

Example

import connection from '@ohos.net.connection';

let netHandle = connection.getDefaultNetSync();

connection.setAppHttpProxy¹¹⁺

setAppHttpProxy(httpProxy: HttpProxy): void;

Sets the application-level HTTP proxy configuration of the network.

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

let exclusionStr = "192.168,baidu.com";
let exclusionArray = exclusionStr.split(',');
connection.setAppHttpProxy({
  host: "192.168.xx.xxx",
  port: 8080,
  exclusionList: exclusionArray
} as connection.HttpProxy);

Preset certificate PIN:

A certificate PIN is the hash value calculated using the SHA256 algorithm for a certificate file. For the server.pem certificate, you can use the following openssl command to calculate its PIN:

cat server.pem \
| sed -n '/-----BEGIN/,/-----END/p' \
| openssl x509 -noout -pubkey \
| openssl pkey -pubin -outform der \
| openssl dgst -sha256 -binary \
| openssl enc -base64

Preset application-level certificate:

The original certificate file is preset in the application. Currently, certificate files in the .crt and .pem formats are supported.

Preset JSON configuration file:

The mapping between preset certificates and network servers is configured in a JSON configuration file. The configuration file is stored in the src/main/resources/base/profile/network_config.json directory of the application.

JSON configuration file:

The following is an example configuration of the certificate pin:

{
  "network-security-config": {	
	  "domain-config": {
		  "domains": [
        {
          "include-subdomains": true,
          "name": "server.com"
        }
      ],
      "pin-set": {
        "expiration": "2024-11-08",
        "pin": [
          {
            "digest-algorithm": "sha256",
            "digest": "FEDCBA987654321"
          }
        ]
      }
    }
  }
}

The following is an example configuration of the application-level certificate:

{
  "network-security-config": {
    "base-config": {  
      "trust-anchors": [                         
        {"certificates": "/etc/security/certificates"}
      ]
    },
    "domain-config": {
      "domains": [
        {
          "include-subdomains": true,
          "name": "example.com"
        }
      ],
      "trust-anchors": [
        {"certificates": "/data/storage/el1/bundle/entry/resources/resfile"}
      ]
    }
  }
}

Description of fields

network-security-config (object: network security configuration)

This field can contain zero or one base-config.

This field must contain one domain-config.

base-config (object: application-wide security configuration)

This field must contain one trust-anchors.

domain-config (array: security configuration of each domain)

This field can contain any number of items.

An item must contain one domain.

An item can contain zero or one trust-anchors.

An item can contain zero or one pin-set.

trust-anchors (array: trusted CA)

This field can contain any number of items.

An item must contain one certificates (string: CA certificate path).

domain (array: domain)

This field can contain any number of items.

An item must contain one name (string: domain name).

An item can contain zero or one include-subdomains (boolean: whether a rule is applicable to subdomains).

pin-set (object: certificate PIN setting)

This field must contain one pin.

This field can contain zero or one expiration (string: expiration time of the certificate PIN).

pin (array: certificate PIN)

This field can contain any number of items.

An item must contain one digest-algorithm (string: digest algorithm used to generate the PIN).

An item must contain one digest (string: public key PIN).

connection.getDefaultHttpProxy¹⁰⁺

getDefaultHttpProxy(callback: AsyncCallback<HttpProxy>): void

Obtains the default HTTP proxy configuration of the network. If the global proxy is set, the global HTTP proxy configuration is returned. If setAppNet is used to bind the application to the network specified by NetHandle, the HTTP proxy configuration of this network is returned. In other cases, the HTTP proxy configuration of the default network is returned. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultHttpProxy((error: BusinessError, data: connection.HttpProxy) => {
  if (error) {
    console.error(`Failed to get default http proxy. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.log("Succeeded to get data" + JSON.stringify(data));
});

connection.getDefaultHttpProxy¹⁰⁺

getDefaultHttpProxy(): Promise<HttpProxy>;

Obtains the default HTTP proxy configuration of the network. If the global proxy is set, the global HTTP proxy configuration is returned. If setAppNet is used to bind the application to the network specified by NetHandle, the HTTP proxy configuration of this network is returned. In other cases, the HTTP proxy configuration of the default network is returned. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetManager.Core

Return value

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultHttpProxy().then((data: connection.HttpProxy) => {
  console.info(JSON.stringify(data));
}).catch((error: BusinessError) => {
  console.info(JSON.stringify(error));
});

connection.getAppNet⁹⁺

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getAppNet((error: BusinessError, data: connection.NetHandle) => {
  if (error) {
    console.error(`Failed to get app net. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.info("Succeeded to get data: " + JSON.stringify(data));
})

connection.getAppNet⁹⁺

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getAppNet().then((data: connection.NetHandle) => {
  console.info(JSON.stringify(data));
}).catch((error: BusinessError) => {
  console.info(JSON.stringify(error));
});

connection.getAppNetSync¹⁰⁺

getAppNetSync(): NetHandle

Obtains information about the network bound to an application. This API returns the result synchronously.

System capability: SystemCapability.Communication.NetManager.Core

Return value

Error codes

Example

import connection from '@ohos.net.connection';

let netHandle = connection.getAppNetSync();

connection.setAppNet⁹⁺

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultNet((error: BusinessError, netHandle: connection.NetHandle) => {
  connection.setAppNet(netHandle, (error: BusinessError, data: void) => {
    if (error) {
      console.error(`Failed to get default net. Code:${error.code}, message:${error.message}`);
      return;
    }
    console.info("Succeeded to get data: " + JSON.stringify(data));
  });
});

connection.setAppNet⁹⁺

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

Return value

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.setAppNet(netHandle).then(() => {
    console.log("success");
  }).catch((error: BusinessError) => {
    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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getAllNets((error: BusinessError, data: connection.NetHandle[]) => {
  if (error) {
    console.error(`Failed to get all nets. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.info("Succeeded to get data: " + 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

Error codes

Example

import connection from '@ohos.net.connection';

connection.getAllNets().then((data: connection.NetHandle[]) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

connection.getAllNetsSync¹⁰⁺

getAllNetsSync(): Array<NetHandle>

Obtains the list of all connected networks. This API returns the result synchronously.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Communication.NetManager.Core

Return value

Error codes

Example

import connection from '@ohos.net.connection';

let netHandle = connection.getAllNetsSync();

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.getConnectionProperties(netHandle, (error: BusinessError, data: connection.ConnectionProperties) => {
    if (error) {
      console.error(`Failed to get connection properties. Code:${error.code}, message:${error.message}`);
      return;
    }
    console.info("Succeeded to get data: " + 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

Return value

Error codes

Example

import connection from '@ohos.net.connection';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.getConnectionProperties(netHandle).then((data: connection.ConnectionProperties) => {
    console.info("Succeeded to get data: " + JSON.stringify(data));
  })
});

connection.getConnectionPropertiesSync¹⁰⁺

getConnectionPropertiesSync(netHandle: NetHandle): ConnectionProperties

Obtains network connection information based on the specified netHandle.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Return value

Error codes

Example

import connection from '@ohos.net.connection';

let netHandle = connection.getDefaultNetSync();
let connectionproperties = connection.getConnectionPropertiesSync(netHandle);

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.getNetCapabilities(netHandle, (error: BusinessError, data: connection.NetCapabilities) => {
    if (error) {
      console.error(`Failed to get net capabilities. Code:${error.code}, message:${error.message}`);
      return;
    }
    console.info("Succeeded to get data: " + 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

Return value

Error codes

Example

import connection from '@ohos.net.connection';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.getNetCapabilities(netHandle).then((data: connection.NetCapabilities) => {
    console.info("Succeeded to get data: " + JSON.stringify(data));
  })
});

connection.getNetCapabilitiesSync¹⁰⁺

getNetCapabilitiesSync(netHandle: NetHandle): NetCapabilities

Obtains capability information of the network corresponding to the netHandle. This API returns the result synchronously.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Return value

Error codes

Example

import connection from '@ohos.net.connection';

let netHandle = connection.getDefaultNetSync();
let getNetCapabilitiesSync = connection.getNetCapabilitiesSync(netHandle);

connection.isDefaultNetMetered⁹⁺

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.isDefaultNetMetered((error: BusinessError, data: boolean) => {
  console.log(JSON.stringify(error));
  console.log('data: ' + data);
});

connection.isDefaultNetMetered⁹⁺

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

Error codes

Example

import connection from '@ohos.net.connection';

connection.isDefaultNetMetered().then((data: boolean) => {
  console.log('data: ' + data);
});

connection.isDefaultNetMeteredSync¹⁰⁺

isDefaultNetMeteredSync(): boolean

Checks whether the data traffic usage on the current network is metered. This API returns the result synchronously.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Communication.NetManager.Core

Return value

Error codes

Example

import connection from '@ohos.net.connection';

let isMetered = connection.isDefaultNetMeteredSync();

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.hasDefaultNet((error: BusinessError, data: boolean) => {
  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

Error codes

Example

import connection from '@ohos.net.connection';
connection.hasDefaultNet().then((data: boolean) => {
  console.log('data: ' + data);
});

connection.hasDefaultNetSync¹⁰⁺

hasDefaultNetSync(): boolean

Checks whether the default data network is activated. This API returns the result synchronously.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Communication.NetManager.Core

Return value

Error codes

Example

import connection from '@ohos.net.connection';

let isDefaultNet = connection.hasDefaultNetSync();

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.reportNetConnected(netHandle, (error: BusinessError) => {
    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

Return value

Error codes

Example

import connection from '@ohos.net.connection';
connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.reportNetConnected(netHandle).then(() => {
    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

Error codes

Example

import connection from '@ohos.net.connection';
connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.reportNetDisconnected(netHandle).then( () => {
    console.log(`report success`);
  });
});

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

Return value

Error codes

Example

import connection from '@ohos.net.connection';
connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  connection.reportNetDisconnected(netHandle).then( () => {
    console.log(`report success`);
  });
});

connection.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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";
connection.getAddressesByName("xxxx", (error: BusinessError, data: connection.NetAddress[]) => {
  if (error) {
    console.error(`Failed to get addresses. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

connection.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

Return value

Error codes

Example

import connection from '@ohos.net.connection';
connection.getAddressesByName("xxxx").then((data: connection.NetAddress[]) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

connection.addCustomDnsRule¹¹⁺

addCustomDnsRule(host: string, ip: Array<string>, callback: AsyncCallback<void>): void

Adds the mapping between a custom host and the corresponding IP address for the current application. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';
connection.addCustomDnsRule("xxxx", ["xx.xx.xx.xx","xx.xx.xx.xx"], (error: BusinessError, data: void) => {
  if (error) {
    console.error(`Failed to get add custom dns rule. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.info("Succeeded to get data: " + JSON.stringify(data));
})

connection.addCustomDnsRule¹¹⁺

addCustomDnsRule(host: string, ip: Array<string>): Promise<void>

Adds the mapping between a custom host and the corresponding IP address for the current application. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Return value

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';
connection.addCustomDnsRule("xxxx", ["xx.xx.xx.xx","xx.xx.xx.xx"]).then(() => {
    console.info("success");
}).catch((error: BusinessError) => {
    console.error(JSON.stringify(error));
})

connection.removeCustomDnsRule¹¹⁺

removeCustomDnsRule(host: string, callback: AsyncCallback<void>): void

Removes the custom DNS rules of the specified host from the current application. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';
connection.removeCustomDnsRule("xxxx", (error: BusinessError, data: void) => {
  if (error) {
    console.error(`Failed to remove custom dns rule. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.info("Succeeded to get data: " + JSON.stringify(data));
})

connection.removeCustomDnsRule¹¹⁺

removeCustomDnsRule(host: string): Promise<void>

Removes the custom DNS rules of the specified host from the current application. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Return value

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';
connection.removeCustomDnsRule("xxxx").then(() => {
    console.log("success");
}).catch((error: BusinessError) => {
    console.log(JSON.stringify(error));
})

connection.clearCustomDnsRules¹¹⁺

clearCustomDnsRules(callback: AsyncCallback<void>): void

Removes all custom DNS rules from the current application. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetManager.Core

Parameters

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';
connection.clearCustomDnsRules((error: BusinessError, data: void) => {
  if (error) {
    console.error(`Failed to clear custom dns rules. Code:${error.code}, message:${error.message}`);
    return;
  }
  console.info("Succeeded to get data: " + JSON.stringify(data));
})

connection.clearCustomDnsRules¹¹⁺

clearCustomDnsRules(): Promise<void>

Removes all custom DNS rules from the current application. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetManager.Core

Return value

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';
connection.clearCustomDnsRules().then(() => {
    console.log("success");
}).catch((error: BusinessError) => {
    console.log(JSON.stringify(error));
})

NetConnection

Represents the network connection handle.

NOTE When a device changes to the network connected state, the netAvailable, netCapabilitiesChange, and netConnectionPropertiesChange events will be triggered. When a device changes to the network disconnected state, the netLost event will be triggered. When a device switches from a Wi-Fi network to a cellular network, the netLost event will be first triggered to indicate that the Wi-Fi network is lost and then the netAvaliable event will be triggered to indicate that the cellular network is available.

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";
let netCon: connection.NetConnection = connection.createNetConnection();
netCon.register((error: BusinessError) => {
  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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";
let netCon: connection.NetConnection = connection.createNetConnection();
netCon.unregister((error: BusinessError) => {
  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

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

// Create a NetConnection object.
let netCon: connection.NetConnection = connection.createNetConnection();

// Call register to register a listener.
netCon.register((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

// Subscribe to netAvailable events. Event notifications can be received only after register is called.
netCon.on('netAvailable', (data: connection.NetHandle) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

// Call unregister to unregister the listener.
netCon.unregister((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

on('netBlockStatusChange')

on(type: 'netBlockStatusChange', callback: Callback<NetBlockStatusInfo>): void

Registers a listener for netBlockStatusChange events. This API uses an asynchronous callback to return the result.

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

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

// Create a NetConnection object.
let netCon: connection.NetConnection = connection.createNetConnection();

// Call register to register a listener.
netCon.register((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

// Subscribe to netBlockStatusChange events. Event notifications can be received only after register is called.
netCon.on('netBlockStatusChange', (data: connection.NetBlockStatusInfo) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

// Call unregister to unregister the listener.
netCon.unregister((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

on('netCapabilitiesChange')

on(type: 'netCapabilitiesChange', callback: Callback<NetCapabilityInfo>): void

Registers a listener for netCapabilitiesChange 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

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

// Create a NetConnection object.
let netCon: connection.NetConnection = connection.createNetConnection();

// Call register to register a listener.
netCon.register((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

// Subscribe to netCapabilitiesChange events. Event notifications can be received only after register is called.
netCon.on('netCapabilitiesChange', (data: connection.NetCapabilityInfo) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

// Call unregister to unregister the listener.
netCon.unregister((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

on('netConnectionPropertiesChange')

on(type: 'netConnectionPropertiesChange', callback: Callback<NetConnectionPropertyInfo>): void

Registers a listener for netConnectionPropertiesChange 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

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

// Create a NetConnection object.
let netCon: connection.NetConnection = connection.createNetConnection();

// Call register to register a listener.
netCon.register((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

// Subscribe to netConnectionPropertiesChange events. Event notifications can be received only after register is called.
netCon.on('netConnectionPropertiesChange', (data: connection.NetConnectionPropertyInfo) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

// Call unregister to unregister the listener.
netCon.unregister((error: BusinessError) => {
  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 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

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

// Create a NetConnection object.
let netCon: connection.NetConnection = connection.createNetConnection();

// Call register to register a listener.
netCon.register((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

// Subscribe to netLost events. Event notifications can be received only after register is called.
netCon.on('netLost', (data: connection.NetHandle) => {
  console.info("Succeeded to get data: " + JSON.stringify(data));
});

// Call unregister to unregister the listener.
netCon.unregister((error: BusinessError) => {
  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 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

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

// Create a NetConnection object.
let netCon: connection.NetConnection = connection.createNetConnection();

// Call register to register a listener.
netCon.register((error: BusinessError) => {
  console.log(JSON.stringify(error));
});

// Subscribe to netUnavailable events. Event notifications can be received only after register is called.
netCon.on('netUnavailable', () => {
  console.info("Succeeded to get unavailable net event");
});

// Call unregister to unregister the listener.
netCon.unregister((error: BusinessError) => {
  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

bindSocket⁹⁺

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

Error codes

Example

import socket from "@ohos.net.socket";
import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

interface Data {
  message: ArrayBuffer,
  remoteInfo: socket.SocketRemoteInfo
}

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  let tcp = socket.constructTCPSocketInstance();
  let udp = socket.constructUDPSocketInstance();
  let socketType = "TCPSocket";
  if (socketType == "TCPSocket") {
    tcp.bind({address:"192.168.xxx.xxx",
              port:8080,
              family:1} as socket.NetAddress, (error: Error) => {
      if (error) {
        console.log('bind fail');
        return;
      }
      netHandle.bindSocket(tcp, (error: BusinessError, data: void) => {
        if (error) {
          console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`);
        } else {
          console.info(JSON.stringify(data));
        }
      });
    });
  } else {
    let callback: (value: Data) => void = (value: Data) => {
      console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo);
    };
    udp.bind({address:"192.168.xxx.xxx",
              port:8080,
              family:1} as socket.NetAddress, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to bind. Code:${error.code}, message:${error.message}`);
        return;
      }
      udp.on('message', (data: Data) => {
        console.info("Succeeded to get data: " + JSON.stringify(data));
      });
      netHandle.bindSocket(udp, (error: BusinessError, data: void) => {
        if (error) {
          console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`);
        } else {
          console.info(JSON.stringify(data));
        }
      });
    });
  }
});

bindSocket⁹⁺

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

Return value

Error codes

Example

import socket from "@ohos.net.socket";
import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';
interface Data {
  message: ArrayBuffer,
  remoteInfo: socket.SocketRemoteInfo
}

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  let tcp = socket.constructTCPSocketInstance();
  let udp = socket.constructUDPSocketInstance();
  let socketType = "TCPSocket";
  if (socketType == "TCPSocket") {
    tcp.bind({address:"192.168.xxx.xxx",
              port:8080,
              family:1} as socket.NetAddress, (error: Error) => {
      if (error) {
        console.log('bind fail');
        return;
      }
      netHandle.bindSocket(tcp).then(() => {
        console.info("bind socket success");
      }).catch((error: BusinessError) => {
        console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`);
      });
    });
  } else {
    let callback: (value: Data) => void = (value: Data) => {
      console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo);
    }
    udp.bind({address:"192.168.xxx.xxx",
              port:8080,
              family:1} as socket.NetAddress, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to bind. Code:${error.code}, message:${error.message}`);
      return;
    }
    udp.on('message', (data: Data) => {
      console.info("Succeeded to get data: " + JSON.stringify(data));
    });
    netHandle.bindSocket(udp).then(() => {
      console.info("bind socket success");
    }).catch((error: BusinessError) => {
      console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`);
    });
  });
}
});

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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  let host = "xxxx";
  netHandle.getAddressesByName(host, (error: BusinessError, data: connection.NetAddress[]) => {
    if (error) {
      console.error(`Failed to get addresses. Code:${error.code}, message:${error.message}`);
      return;
    }
    console.info("Succeeded to get data: " + 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

Return value

Error codes

Example

import connection from '@ohos.net.connection';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  let host = "xxxx";
  netHandle.getAddressesByName(host).then((data: connection.NetAddress[]) => {
    console.info("Succeeded to get data: " + 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

Error codes

Example

import connection from '@ohos.net.connection';
import { BusinessError } from "@ohos.base";

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  let host = "xxxx";
  netHandle.getAddressByName(host, (error: BusinessError, data: connection.NetAddress) => {
    if (error) {
      console.error(`Failed to get address. Code:${error.code}, message:${error.message}`);
      return;
    }
    console.info("Succeeded to get data: " + 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

Return value

Error codes

Example

import connection from '@ohos.net.connection';

connection.getDefaultNet().then((netHandle: connection.NetHandle) => {
  let host = "xxxx";
  netHandle.getAddressByName(host).then((data: connection.NetAddress) => {
    console.info("Succeeded to get data: " + JSON.stringify(data));
  });
});

NetCap

Defines the network capability.

System capability: SystemCapability.Communication.NetManager.Core

NetBearType

Enumerates network types.

System capability: SystemCapability.Communication.NetManager.Core

HttpProxy¹⁰⁺

Represents the HTTP proxy configuration.

System capability: SystemCapability.Communication.NetManager.Core

NetSpecifier

Provides an instance that bears data network capabilities.

System capability: SystemCapability.Communication.NetManager.Core

NetCapabilityInfo¹⁰⁺

Provides an instance that bears data network capabilities.

System capability: SystemCapability.Communication.NetManager.Core

NetCapabilities

Defines the network capability set.

System capability: SystemCapability.Communication.NetManager.Core

NetConnectionPropertyInfo¹¹⁺

Defines the network connection properties.

System capability: SystemCapability.Communication.NetManager.Core

Attributes

NetBlockStatusInfo¹¹⁺

Obtains the network block status information.

System capability: SystemCapability.Communication.NetManager.Core

Attributes

ConnectionProperties

Defines the network connection properties.

System capability: SystemCapability.Communication.NetManager.Core

RouteInfo

Defines network route information.

System capability: SystemCapability.Communication.NetManager.Core

LinkAddress

Defines network link information.

System capability: SystemCapability.Communication.NetManager.Core

NetAddress

Defines a network address.

System capability: SystemCapability.Communication.NetManager.Core