net_connection.h

Overview

Provides the C APIs of the network connection module for network management.

File to include: <network/netmanager/net_connection.h>

Library: libnet_connection.so

System capability: SystemCapability.Communication.NetManager.Core

Since: 11

Related module: NetConnection

Summary

Functions

Name	Description
int32_t OH_NetConn_HasDefaultNet(int32_t *hasDefaultNet)	Checks whether a default activated data network is available.
int32_t OH_NetConn_GetDefaultNet(NetConn_NetHandle *netHandle)	Obtains the default activated data network.
int32_t OH_NetConn_IsDefaultNetMetered(int32_t *isMetered)	Checks whether data traffic usage on the current network is metered.
int32_t OH_NetConn_GetConnectionProperties(NetConn_NetHandle netHandle, NetConn_ConnectionProperties prop)	Obtains the link information of a data network.
int32_t OH_NetConn_GetNetCapabilities(NetConn_NetHandle netHandle, NetConn_NetCapabilities netCapabilities)	Obtains the capabilities of a data network.
int32_t OH_NetConn_GetDefaultHttpProxy(NetConn_HttpProxy *httpProxy)	Obtains the default network proxy.
int32_t OH_NetConn_GetAddrInfo(char host, char serv, struct addrinfo hint, struct addrinfo *res, int32_t netId)	Obtains the DNS result based on the specified netId.
int32_t OH_NetConn_FreeDnsResult(struct addrinfo *res)	Releases the DNS query result.
int32_t OH_NetConn_GetAllNets(NetConn_NetHandleList *netHandleList)	Obtains all activated data networks.
int32_t OHOS_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver)	Registers a custom DNS resolver.
int32_t OHOS_NetConn_UnregisterDnsResolver(void)	Unregisters a custom DNS resolver.
int32_t OH_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver)	Registers a custom DNS resolver.
int32_t OH_NetConn_UnregisterDnsResolver(void)	Unregisters a custom DNS resolver.
int32_t OH_NetConn_BindSocket(int32_t socketFd, NetConn_NetHandle *netHandle)	Binds a socket to the specified network.
int32_t OH_NetConn_SetAppHttpProxy(NetConn_HttpProxy *httpProxy)	Sets an HTTP proxy for the current application.
int32_t OH_NetConn_RegisterAppHttpProxyCallback(OH_NetConn_AppHttpProxyChange appHttpProxyChange, uint32_t *callbackId)	Registers a callback for application-level HTTP proxy changes.
void OH_NetConn_UnregisterAppHttpProxyCallback(uint32_t callbackId)	Unregisters the callback for HTTP proxy changes of the application.
int32_t OH_NetConn_RegisterNetConnCallback(NetConn_NetSpecifier specifier, NetConn_NetConnCallback netConnCallback,uint32_t timeout, uint32_t *callbackId)	Registers a callback for network status changes.
int32_t OH_NetConn_RegisterDefaultNetConnCallback(NetConn_NetConnCallback netConnCallback, uint32_t callbackId)	Registers a callback for status changes of the default network.
int32_t OH_NetConn_UnregisterNetConnCallback(uint32_t callBackId)	Unregisters the callback for network status changes.
NetConn_ErrorCode OH_NetConn_SetPacUrl(const char *pacUrl)	Sets the URL of the system-level proxy auto-config (PAC) script.
NetConn_ErrorCode OH_NetConn_GetPacUrl(char *pacUrl)	Obtains the URL of the system-level PAC script.
int32_t OH_NetConn_QueryProbeResult(char destination, int32_t duration, NetConn_ProbeResultInfo probeResultInfo)	Queries network probe results.
int32_t OH_NetConn_QueryTraceRoute(char destination, NetConn_TraceRouteOption option,NetConn_TraceRouteInfo *traceRouteInfo)	Queries network trace route information.

Function Description

OH_NetConn_HasDefaultNet()

int32_t OH_NetConn_HasDefaultNet(int32_t *hasDefaultNet)

Description

Checks whether a default activated data network is available.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 11

Parameters

Name	Description
int32_t *hasDefaultNet	Whether there is a default network.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_GetDefaultNet()

int32_t OH_NetConn_GetDefaultNet(NetConn_NetHandle *netHandle)

Description

Obtains the default activated data network.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 11

Parameters

Name	Description
NetConn_NetHandle *netHandle	Network ID.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_IsDefaultNetMetered()

int32_t OH_NetConn_IsDefaultNetMetered(int32_t *isMetered)

Description

Checks whether metering is enabled for the default data network.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 11

Parameters

Name	Description
int32_t *isMetered	Whether metering is enabled.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_GetConnectionProperties()

int32_t OH_NetConn_GetConnectionProperties(NetConn_NetHandle *netHandle, NetConn_ConnectionProperties *prop)

Description

Obtains the link information of a data network.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 11

Parameters

Name	Description
NetConn_NetHandle *netHandle	Network ID.
NetConn_ConnectionProperties *prop	Link information.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_GetNetCapabilities()

int32_t OH_NetConn_GetNetCapabilities(NetConn_NetHandle *netHandle, NetConn_NetCapabilities *netCapabilities)

Description

Obtains the capabilities of a data network.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 11

Parameters

Name	Description
NetConn_NetHandle *netHandle	Network ID.
NetConn_NetCapabilities *netCapabilities	Capability set.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_GetDefaultHttpProxy()

int32_t OH_NetConn_GetDefaultHttpProxy(NetConn_HttpProxy *httpProxy)

Description

Obtains the default network proxy.

System capability: SystemCapability.Communication.NetManager.Core

Since: 11

Parameters

Name	Description
NetConn_HttpProxy *httpProxy	Proxy configuration.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_GetAddrInfo()

int32_t OH_NetConn_GetAddrInfo(char *host, char *serv, struct addrinfo *hint, struct addrinfo **res, int32_t netId)

Description

Obtains the DNS result based on the specified netId.

System capability: SystemCapability.Communication.NetManager.Core

Required permission: ohos.permission.INTERNET

Since: 11

Parameters

Name	Description
char *host	Host name.
char *serv	Service name.
struct addrinfo *hint	Pointer to the addrinfo structure.
struct addrinfo **res	DNS query result, which is in the format of linked lists.
int32_t netId	If netId is set to 0, the default netid is used for query.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_FreeDnsResult()

int32_t OH_NetConn_FreeDnsResult(struct addrinfo *res)

Description

Releases the DNS query result.

System capability: SystemCapability.Communication.NetManager.Core

Required permission: ohos.permission.INTERNET

Since: 11

Parameters

Name	Description
struct addrinfo *res	Header of the DNS query result, which is in the format of linked lists.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_GetAllNets()

int32_t OH_NetConn_GetAllNets(NetConn_NetHandleList *netHandleList)

Description

Obtains all activated data networks.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 11

Parameters

Name	Description
NetConn_NetHandleList *netHandleList	Network information list.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OHOS_NetConn_RegisterDnsResolver()

int32_t OHOS_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver)

Description

Registers a custom DNS resolver.

System capability: SystemCapability.Communication.NetManager.Core

Since: 11

Deprecated from: 13

Substitute: OH_NetConn_RegisterDnsResolver

Parameters

Name	Description
OH_NetConn_CustomDnsResolver resolver	Pointer to the custom DNS resolver.

Returns

Type	Description
int32_t	0: Success. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OHOS_NetConn_UnregisterDnsResolver()

int32_t OHOS_NetConn_UnregisterDnsResolver(void)

Description

Unregisters a custom DNS resolver.

System capability: SystemCapability.Communication.NetManager.Core

Since: 11

Deprecated from: 13

Substitute: OH_NetConn_UnregisterDnsResolver

Returns

Type	Description
int32_t	0: Success. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_RegisterDnsResolver()

int32_t OH_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver)

Description

Registers a custom DNS resolver.

System capability: SystemCapability.Communication.NetManager.Core

Since: 13

Parameters

Name	Description
OH_NetConn_CustomDnsResolver resolver	Pointer to the custom DNS resolver.

Returns

Type	Description
int32_t	Result code. NETMANAGER_EXT_SUCCESS: Operation success. NETMANAGER_ERR_PARAMETER_ERROR: Parameter error. Enter a correct parameter.

OH_NetConn_UnregisterDnsResolver()

int32_t OH_NetConn_UnregisterDnsResolver(void)

Description

Unregisters a custom DNS resolver.

System capability: SystemCapability.Communication.NetManager.Core

Since: 13

Returns

Type	Description
int32_t	0: Success. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_BindSocket()

int32_t OH_NetConn_BindSocket(int32_t socketFd, NetConn_NetHandle *netHandle)

Description

Binds a socket to the specified network.

System capability: SystemCapability.Communication.NetManager.Core

Since: 12

Parameters

Name	Description
int32_t socketFd	Socket constructed by the user.
NetConn_NetHandle *netHandle	Pointer to the network handle containing the network ID.

Returns

Type	Description
int32_t	0: Success. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error.

OH_NetConn_SetAppHttpProxy()

int32_t OH_NetConn_SetAppHttpProxy(NetConn_HttpProxy *httpProxy)

Description

Sets an HTTP proxy for the current application.

System capability: SystemCapability.Communication.NetManager.Core

Since: 12

Parameters

Name	Description
NetConn_HttpProxy *httpProxy	HTTP proxy to set.

Returns

Type	Description
int32_t	0: Success. 401: Parameter error.

OH_NetConn_RegisterAppHttpProxyCallback()

int32_t OH_NetConn_RegisterAppHttpProxyCallback(OH_NetConn_AppHttpProxyChange appHttpProxyChange, uint32_t *callbackId)

Description

Registers a callback for HTTP proxy changes of the application.

System capability: SystemCapability.Communication.NetManager.Core

Since: 12

Parameters

Name	Description
OH_NetConn_AppHttpProxyChange appHttpProxyChange	Callback to register.
uint32_t *callbackId	ID of the registered callback.

Returns

Type	Description
int32_t	0: Success. 401: Parameter error.

OH_NetConn_UnregisterAppHttpProxyCallback()

void OH_NetConn_UnregisterAppHttpProxyCallback(uint32_t callbackId)

Description

Unregisters the callback for HTTP proxy changes of the application.

System capability: SystemCapability.Communication.NetManager.Core

Since: 12

Parameters

Name	Description
uint32_t callbackId	ID of the callback to unregister.

OH_NetConn_RegisterNetConnCallback()

int32_t OH_NetConn_RegisterNetConnCallback(NetConn_NetSpecifier *specifier, NetConn_NetConnCallback *netConnCallback,uint32_t timeout, uint32_t *callbackId)

Description

Registers a callback for network status changes.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 12

Parameters

Name	Description
netSpecifier	Network feature set.
callback	Registered callbacks.
uint32_t timeout	Timeout duration, in milliseconds. The value 0 indicates infinite waiting.
uint32_t *callbackId	Callback IDs.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error. 2101008: Callback already registered. 2101022: Maximum number of requests exceeded.

OH_NetConn_RegisterDefaultNetConnCallback()

int32_t OH_NetConn_RegisterDefaultNetConnCallback(NetConn_NetConnCallback *netConnCallback, uint32_t *callbackId)

Description

Registers a callback for status changes of the default network.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 12

Parameters

Name	Description
callback	Registered callbacks.
uint32_t *callbackId	Callback IDs.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error. 2101008: Callback already registered. 2101022: Maximum number of requests exceeded.

OH_NetConn_UnregisterNetConnCallback()

int32_t OH_NetConn_UnregisterNetConnCallback(uint32_t callBackId)

Description

Unregisters the callback for network status changes.

System capability: SystemCapability.Communication.NetManager.Core

Required permissions: ohos.permission.GET_NETWORK_INFO

Since: 12

Parameters

Name	Description
uint32_t callBackId	ID of the callback to unregister.

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100002: Service connection failure. 2100003: Internal error. 2101007: Callback not exist.

OH_NetConn_SetPacUrl()

NetConn_ErrorCode OH_NetConn_SetPacUrl(const char *pacUrl)

Description

Sets the URL of the system-level Proxy Auto Config (PAC) script, for example, http://127.0.0.1:21998/PacProxyScript.pac. You can obtain the proxy information by parsing the URL.

Required permissions: ohos.permission.SET_PAC_URL

Since: 15

Parameters

Name	Description
const char *pacUrl	Address of the PAC script.

Returns

Type	Description
NetConn_ErrorCode	Result code defined in NetConn_ErrorCode. NETCONN_SUCCESS: success. NETCONN_PERMISSION_DENIED: permission denied. NETCONN_PARAMETER_ERROR: parameter error. NETCONN_OPERATION_FAILED: unable to connect to the service. NETCONN_INTERNAL_ERROR: internal error.

OH_NetConn_GetPacUrl()

NetConn_ErrorCode OH_NetConn_GetPacUrl(char *pacUrl)

Description

Obtains the URL of the system-level PAC script.

Since: 15

Parameters

Name	Description
char *pacUrl	URL of the PAC script.

Returns

Type	Description
NetConn_ErrorCode	Result code defined in NetConn_ErrorCode. NETCONN_SUCCESS: success. NETCONN_PARAMETER_ERROR: parameter error. NETCONN_OPERATION_FAILED: unable to connect to the service. NETCONN_INTERNAL_ERROR: internal error.

OH_NetConn_QueryProbeResult()

int32_t OH_NetConn_QueryProbeResult(char *destination, int32_t duration, NetConn_ProbeResultInfo *probeResultInfo)

Description

Queries network probe results. If an exception (for example, network disconnection) occurs and the request fails to be sent, the API immediately returns the result without performing subsequent detection. This API involves network operations. Do not call it in the main process. Otherwise, the UI may freeze.

System capability: SystemCapability.Communication.NetManager.Core

Required permission: ohos.permission.INTERNET

Since: 20

Parameters

Name	Description
char *destination	Target domain name or IP address to be detected. For a domain name, the domain name is resolved to the target IP address before the detection, and then the detection is initiated. The domain name resolution time is not included in the probe duration indicated by duration.
int32_t duration	Probe duration. in seconds. The detection interval is 1 second. Therefore, you can use this field to control the number of detections.
NetConn_ProbeResultInfo *probeResultInfo	Packet loss rate and round-trip time (RTT).

Returns

Type	Description
int32_t	0: Success. 201: Missing permissions. 401: Parameter error. 2100003: Internal error.

OH_NetConn_QueryTraceRoute()

int32_t OH_NetConn_QueryTraceRoute(char *destination, NetConn_TraceRouteOption *option,NetConn_TraceRouteInfo *traceRouteInfo)

Description

Queries network trace route information.

NOTE

To call this API, the app needs to apply for the precise location permission. According to Applying for Location Permissions (ArkTS), the caller needs to apply for both ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION.

Required permissions: ohos.permission.INTERNET, ohos.permission.LOCATION, and ohos.permission.ACCESS_NET_TRACE_INFO

Since: 20

Parameters

Name	Description
char *destination	Destination address.
NetConn_TraceRouteOption *option	Route options.
NetConn_TraceRouteInfo *traceRouteInfo	Route result. An array pointer needs to be passed. The array size indicates the number of route hops, which is 30 by default. If you customize the number of hops, ensure that the array size is the same as the value of maxJumpNumber in the option field.