* Copyright (c) 2023-2024 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
* @addtogroup NetConnection
* @{
*
* @brief Provide C interface for the data network connection module of network management.
*
* @since 11
* @version 1.0
*/
* @file net_connection.h
*
* @brief Provide C interface for the data network connection module of network management.
*
* @kit NetworkKit
* @syscap SystemCapability.Communication.NetManager.Core
* @library libnet_connection.so
* @since 11
* @version 1.0
*/
#ifndef NATIVE_NET_CONN_API_H
#define NATIVE_NET_CONN_API_H
#include <netdb.h>
#include "net_connection_type.h"
#ifdef __cplusplus
extern "C" {
#endif
* @brief Checks whether a default activated data network is available.
*
* @param hasDefaultNet Pointer to the result that specifies whether a default activated data network is available.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_HasDefaultNet(int32_t *hasDefaultNet);
* @brief Obtains the default activated data network.
*
* @param netHandle Pointer to the network handle that contains the network ID.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_GetDefaultNet(NetConn_NetHandle *netHandle);
* @brief Checks whether metering is enabled for the default data network.
*
* @param isMetered Pointer to the result that specifies whether metering is enabled.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_IsDefaultNetMetered(int32_t *isMetered);
* @brief Obtains the connection properties of a data network.
*
* @param netHandle Pointer to the network handle that contains the network ID.
* @param prop Pointer to the connection properties.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_GetConnectionProperties(NetConn_NetHandle *netHandle, NetConn_ConnectionProperties *prop);
* @brief Obtains the capabilities of a data network.
*
* @param netHandle Pointer to the network handle that contains the network ID.
* @param netCapacities Pointer to the network capabilities.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_GetNetCapabilities(NetConn_NetHandle *netHandle, NetConn_NetCapabilities *netCapabilities);
* @brief Obtains the default http proxy.
*
* @param httpProxy Pointer to the HTTP proxy.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_GetDefaultHttpProxy(NetConn_HttpProxy *httpProxy);
* @brief Get DNS result with netId.
*
* @param host The host name to query.
* @param serv Service name.
* @param hint Pointer to the addrinfo structure.
* @param res Store DNS query results and return them in a linked list format.
* @param netId DNS query netId, 0 is used for default netid query.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.INTERNET
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_GetAddrInfo(char *host, char *serv, struct addrinfo *hint, struct addrinfo **res, int32_t netId);
* @brief Free DNS result.
*
* @param res DNS query result chain header.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.INTERNET
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_FreeDnsResult(struct addrinfo *res);
* @brief Queries all activated data networks.
*
* @param netHandleList Network handle that stores the network ID list.
* @return 0 - Success. 201 - Missing permissions.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 11
* @version 1.0
*/
int32_t OH_NetConn_GetAllNets(NetConn_NetHandleList *netHandleList);
* @brief Registers a custom DNS resolver.
*
* @param resolver Pointer to the custom DNS resolver.
* @return 0 - Success.
* 401 - Parameter error. 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @syscap SystemCapability.Communication.NetManager.Core
* @deprecated since 13
* @useinstead OH_NetConn_RegisterDnsResolver
* @since 11
* @version 1.0
*/
int32_t OHOS_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver);
* @brief Unregisters a custom DNS resolver.
*
* @return 0 - Success.
* 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @syscap SystemCapability.Communication.NetManager.Core
* @deprecated since 13
* @useinstead OH_NetConn_UnregisterDnsResolver
* @since 11
* @version 1.0
*/
int32_t OHOS_NetConn_UnregisterDnsResolver(void);
* @brief Registers a custom DNS resolver.
*
* @param resolver Pointer to the custom DNS resolver.
* @return Returns the result code.
* {@link NETMANAGER_EXT_SUCCESS} if the operation is successful.
* {@link NETMANAGER_ERR_PARAMETER_ERROR} Parameter error. Please enter a correct parameter.
* @syscap SystemCapability.Communication.NetManager.Core
* @since 13
* @version 1.0
*/
int32_t OH_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver);
* @brief Unregisters a custom DNS resolver.
*
* @return 0 - Success.
* 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @syscap SystemCapability.Communication.NetManager.Core
* @since 13
* @version 1.0
*/
int32_t OH_NetConn_UnregisterDnsResolver(void);
* @brief Registers a custom DNS resolver to intercept and override DNS queries.
* Falls back to system DNS if no result is specified.
* Only a single resolver is allowed. You must unregister the existing one before registering a new one.
*
* @param resolver Pointer to the custom DNS resolver.
* If the resolver returns 0, skip system DNS; otherwise, fallback to system DNS.
* @return 0 - Success.
* 401 - Parameter error. Please enter a correct parameter.
* 2101008 - Resolver already exists. use OH_NetConn_UnregisterCustomDnsResolver before registering a new one.
* @stagemodelonly
* @since 26.0.0
*/
int32_t OH_NetConn_RegisterCustomDnsResolver(OH_NetConn_CustomDnsResolver resolver);
* @brief Unregisters the custom DNS resolver.
*
* @return 0 - Success.
* 2100003 - Internal error.
* @stagemodelonly
* @since 26.0.0
*/
int32_t OH_NetConn_UnregisterCustomDnsResolver(void);
* @brief Binds a socket to the specific network.
*
* @param socketFd Socket constructed by user.
* @param netHandle Pointer to the network handle that contains the network ID.
* @return 0 - Success.
* 401 - Parameter error.
* 2100002 - Unable to connect to service.
* 2100003 - Internal error.
* @syscap SystemCapability.Communication.NetManager.Core
* @since 12
* @version 1.0
*/
int32_t OH_NetConn_BindSocket(int32_t socketFd, NetConn_NetHandle *netHandle);
* @brief Sets http proxy information to current application.
*
* @param httpProxy Information about the proxy that needs to be set.
* @return 0 - Success.
* 401 - Parameter error.
* @syscap SystemCapability.Communication.NetManager.Core
* @since 12
* @version 1.0
*/
int32_t OH_NetConn_SetAppHttpProxy(NetConn_HttpProxy *httpProxy);
* @brief Registers callback to listen for changes to the application-level http proxy.
*
* @param appHttpProxyChange Callback that need to be registered to listen for changes to the http proxy.
* @param callbackId Callback id returned after registration, associated with a registered callback.
* @return 0 - Success.
* 401 - Parameter error.
* @syscap SystemCapability.Communication.NetManager.Core
* @since 12
* @version 1.0
*/
int32_t OH_NetConn_RegisterAppHttpProxyCallback(OH_NetConn_AppHttpProxyChange appHttpProxyChange, uint32_t *callbackId);
* @brief Unregisters a callback function that listens for application-level proxy changes.
*
* @param callbackId Id of the callback function that needs to be deregistered.
* @syscap SystemCapability.Communication.NetManager.Core
* @since 12
* @version 1.0
*/
void OH_NetConn_UnregisterAppHttpProxyCallback(uint32_t callbackId);
* @brief Requests global HTTP proxy re-authentication and reports the result through a one-shot callback.
*
* This function submits an asynchronous re-authentication request. A return value of 0 indicates
* that the request has been accepted. It does not indicate that re-authentication has succeeded.
* The final result is reported through the callback.<br>
*
* If this function returns 0, the callback will be invoked at most once. After the callback is
* invoked, it is automatically released by the system.<br>
*
* If this function returns a non-zero value, the callback will not be invoked.<br>
*
* The callback may be invoked on a system worker thread. The caller must ensure that the callback
* implementation is thread-safe and returns quickly.<br>
*
* The caller must ensure that the callback function and userData remain valid until the callback
* is invoked.
*
* @permission ohos.permission.INTERNET
* @param callback The one-shot callback used to receive the re-authentication result. It must not be NULL.
* @param userContext The user-defined data passed to the callback. It can be NULL. The system does
* not access, copy, or release it.
* @return <ul><li>0 - Success.</li>
* <li>201 - Permission denied.</li>
* <li>401 - Parameter error.</li></ul>
* @since 26.0.0
*/
int32_t OH_NetConn_RefreshGlobalHttpProxyWithCallback(
OH_NetConn_GlobalHttpProxyRefreshCallback callback,
void *userContext);
* @brief Registers callback, used to monitor specific network status.
*
* @param netSpecifier specifier information.
* @param callback The callback needed to be registered.
* @param timeout The timeout period in milliseconds.
* @param callbackId out param, corresponding to a registered callback.
* @return 0 - Success.
* 201 - Permission denied.
* 401 - Parameter error.
* 2100002 - Failed to connect to the service.
* 2100003 - System internal error.
* 2101008 - The callback already exists.
* 2101022 - The number of requests exceeded the maximum allowed.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 12
* @version 1.0
*/
int32_t OH_NetConn_RegisterNetConnCallback(NetConn_NetSpecifier *specifier, NetConn_NetConnCallback *netConnCallback,
uint32_t timeout, uint32_t *callbackId);
* @brief Registers a callback to listen default network's status changed.
*
* @param callback The callback needed to be registered.
* @param callbackId out param, corresponding to a registered callback.
* @return 0 - Success.
* 201 - Permission denied.
* 401 - Parameter error.
* 2100002 - Failed to connect to the service.
* 2100003 - System internal error.
* 2101008 - The callback already exists.
* 2101022 - The number of requests exceeded the maximum allowed.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 12
* @version 1.0
*/
int32_t OH_NetConn_RegisterDefaultNetConnCallback(NetConn_NetConnCallback *netConnCallback, uint32_t *callbackId);
* @brief Unregisters network status callback.
*
* @param callBackId the id corresponding to a registered callback.
* @return 0 - Success.
* 201 - Permission denied.
* 401 - Parameter error.
* 2100002 - Failed to connect to the service.
* 2100003 - System internal error.
* 2101007 - The callback does not exists.
* @permission ohos.permission.GET_NETWORK_INFO
* @syscap SystemCapability.Communication.NetManager.Core
* @since 12
* @version 1.0
*/
int32_t OH_NetConn_UnregisterNetConnCallback(uint32_t callBackId);
* @brief Sets the URL of the current PAC script.
*
* @param pacUrl the URL of the current PAC script.
* @return the result defines in {@link NetConn_ErrorCode}.
* {@link NETCONN_SUCCESS} Success.
* {@link NETCONN_PERMISSION_DENIED} Permission denied.
* {@link NETCONN_PARAMETER_ERROR} Parameter check failed.
* {@link NETCONN_OPERATION_FAILED} Failed to connect to the service.
* {@link NETCONN_INTERNAL_ERROR} System internal error.
* @permission ohos.permission.SET_PAC_URL
* @since 15
*/
NetConn_ErrorCode OH_NetConn_SetPacUrl(const char *pacUrl);
* @brief Obtains the URL of the current PAC script.
*
* @param pacUrl the URL of the current PAC script.
* @return the result defines in {@link NetConn_ErrorCode}.
* {@link NETCONN_SUCCESS} Success.
* {@link NETCONN_PARAMETER_ERROR} Parameter check failed.
* {@link NETCONN_OPERATION_FAILED} Failed to connect to the service.
* {@link NETCONN_INTERNAL_ERROR} System internal error.
* @since 15
*/
NetConn_ErrorCode OH_NetConn_GetPacUrl(char *pacUrl);
* @brief Query a network probe result.
*
* @param destination Pointer to the destination.
* @param duration probe duration. Unit: second.
* @param probeResultInfo Pointer to probe loss rate and rtt.
* @return 0 - Success.
* 201 - Missing permissions.
* 401 - Parameter error.
* 2100003 - Internal error.
* @permission ohos.permission.INTERNET
* @since 20
*/
int32_t OH_NetConn_QueryProbeResult(char *destination, int32_t duration, NetConn_ProbeResultInfo *probeResultInfo);
* @brief Query a network trace route.
*
* @param destination Pointer to the destination.
* @param option Pointer to the trace route option
* @param traceRouteInfo Pointer to trace route result.
* @return 0 - Success.
* 201 - Missing permissions.
* @permission ohos.permission.INTERNET and ohos.permission.LOCATION and ohos.permission.ACCESS_NET_TRACE_INFO
* @since 20
*/
int32_t OH_NetConn_QueryTraceRoute(char *destination, NetConn_TraceRouteOption *option,
NetConn_TraceRouteInfo *traceRouteInfo);
#ifdef __cplusplus
}
#endif
#endif
