1 /* 2 * Copyright (c) 2023-2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef NATIVE_NET_CONN_API_H 17 #define NATIVE_NET_CONN_API_H 18 19 /** 20 * @addtogroup NetConnection 21 * @{ 22 * 23 * @brief Provide C interface for the data network connection module of network management. 24 * 25 * @since 11 26 * @version 1.0 27 */ 28 29 /** 30 * @file net_connection.h 31 * 32 * @brief Provide C interface for the data network connection module of network management. 33 * 34 * @kit NetworkKit 35 * @syscap SystemCapability.Communication.NetManager.Core 36 * @library libnet_connection.so 37 * @since 11 38 * @version 1.0 39 */ 40 41 #include <netdb.h> 42 43 #include "net_connection_type.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Checks whether a default activated data network is available. 51 * 52 * @param hasDefaultNet Pointer to the result that specifies whether a default activated data network is available. 53 * @return 0 - Success. 201 - Missing permissions. 54 * 401 - Parameter error. 2100002 - Unable to connect to service. 55 * 2100003 - Internal error. 56 * @permission ohos.permission.GET_NETWORK_INFO 57 * @syscap SystemCapability.Communication.NetManager.Core 58 * @since 11 59 * @version 1.0 60 */ 61 int32_t OH_NetConn_HasDefaultNet(int32_t *hasDefaultNet); 62 63 /** 64 * @brief Obtains the default activated data network. 65 * 66 * @param netHandle Pointer to the network handle that contains the network ID. 67 * @return 0 - Success. 201 - Missing permissions. 68 * 401 - Parameter error. 2100002 - Unable to connect to service. 69 * 2100003 - Internal error. 70 * @permission ohos.permission.GET_NETWORK_INFO 71 * @syscap SystemCapability.Communication.NetManager.Core 72 * @since 11 73 * @version 1.0 74 */ 75 int32_t OH_NetConn_GetDefaultNet(NetConn_NetHandle *netHandle); 76 77 /** 78 * @brief Checks whether metering is enabled for the default data network. 79 * 80 * @param isMetered Pointer to the result that specifies whether metering is enabled. 81 * @return 0 - Success. 201 - Missing permissions. 82 * 401 - Parameter error. 2100002 - Unable to connect to service. 83 * 2100003 - Internal error. 84 * @permission ohos.permission.GET_NETWORK_INFO 85 * @syscap SystemCapability.Communication.NetManager.Core 86 * @since 11 87 * @version 1.0 88 */ 89 int32_t OH_NetConn_IsDefaultNetMetered(int32_t *isMetered); 90 91 /** 92 * @brief Obtains the connection properties of a data network. 93 * 94 * @param netHandle Pointer to the network handle that contains the network ID. 95 * @param prop Pointer to the connection properties. 96 * @return 0 - Success. 201 - Missing permissions. 97 * 401 - Parameter error. 2100002 - Unable to connect to service. 98 * 2100003 - Internal error. 99 * @permission ohos.permission.GET_NETWORK_INFO 100 * @syscap SystemCapability.Communication.NetManager.Core 101 * @since 11 102 * @version 1.0 103 */ 104 int32_t OH_NetConn_GetConnectionProperties(NetConn_NetHandle *netHandle, NetConn_ConnectionProperties *prop); 105 106 /** 107 * @brief Obtains the capabilities of a data network. 108 * 109 * @param netHandle Pointer to the network handle that contains the network ID. 110 * @param netCapacities Pointer to the network capabilities. 111 * @return 0 - Success. 201 - Missing permissions. 112 * 401 - Parameter error. 2100002 - Unable to connect to service. 113 * 2100003 - Internal error. 114 * @permission ohos.permission.GET_NETWORK_INFO 115 * @syscap SystemCapability.Communication.NetManager.Core 116 * @since 11 117 * @version 1.0 118 */ 119 int32_t OH_NetConn_GetNetCapabilities(NetConn_NetHandle *netHandle, NetConn_NetCapabilities *netCapabilities); 120 121 /** 122 * @brief Obtains the default http proxy. 123 * 124 * @param httpProxy Pointer to the HTTP proxy. 125 * @return 0 - Success. 201 - Missing permissions. 126 * 401 - Parameter error. 2100002 - Unable to connect to service. 127 * 2100003 - Internal error. 128 * @syscap SystemCapability.Communication.NetManager.Core 129 * @since 11 130 * @version 1.0 131 */ 132 int32_t OH_NetConn_GetDefaultHttpProxy(NetConn_HttpProxy *httpProxy); 133 134 /** 135 * @brief Get DNS result with netId. 136 * 137 * @param host The host name to query. 138 * @param serv Service name. 139 * @param hint Pointer to the addrinfo structure. 140 * @param res Store DNS query results and return them in a linked list format. 141 * @param netId DNS query netId, 0 is used for default netid query. 142 * @return 0 - Success. 201 - Missing permissions. 143 * 401 - Parameter error. 2100002 - Unable to connect to service. 144 * 2100003 - Internal error. 145 * @permission ohos.permission.INTERNET 146 * @syscap SystemCapability.Communication.NetManager.Core 147 * @since 11 148 * @version 1.0 149 */ 150 int32_t OH_NetConn_GetAddrInfo(char *host, char *serv, struct addrinfo *hint, struct addrinfo **res, int32_t netId); 151 152 /** 153 * @brief Free DNS result. 154 * 155 * @param res DNS query result chain header. 156 * @return 0 - Success. 201 - Missing permissions. 157 * 401 - Parameter error. 2100002 - Unable to connect to service. 158 * 2100003 - Internal error. 159 * @permission ohos.permission.INTERNET 160 * @syscap SystemCapability.Communication.NetManager.Core 161 * @since 11 162 * @version 1.0 163 */ 164 int32_t OH_NetConn_FreeDnsResult(struct addrinfo *res); 165 166 /** 167 * @brief Queries all activated data networks. 168 * 169 * @param netHandleList Network handle that stores the network ID list. 170 * @return 0 - Success. 201 - Missing permissions. 171 * 401 - Parameter error. 2100002 - Unable to connect to service. 172 * 2100003 - Internal error. 173 * @permission ohos.permission.GET_NETWORK_INFO 174 * @syscap SystemCapability.Communication.NetManager.Core 175 * @since 11 176 * @version 1.0 177 */ 178 int32_t OH_NetConn_GetAllNets(NetConn_NetHandleList *netHandleList); 179 180 /** 181 * @brief Registers a custom DNS resolver. 182 * 183 * @param resolver Pointer to the custom DNS resolver. 184 * @return 0 - Success. 201 - Missing permissions. 185 * 401 - Parameter error. 2100002 - Unable to connect to service. 186 * 2100003 - Internal error. 187 * @permission ohos.permission.INTERNET 188 * @syscap SystemCapability.Communication.NetManager.Core 189 * @deprecated since 13 190 * @useinstead OH_NetConn_RegisterDnsResolver 191 * @since 11 192 * @version 1.0 193 */ 194 int32_t OHOS_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver); 195 196 /** 197 * @brief Unregisters a custom DNS resolver. 198 * 199 * @return 0 - Success. 201 - Missing permissions. 200 * 401 - Parameter error. 2100002 - Unable to connect to service. 201 * 2100003 - Internal error. 202 * @permission ohos.permission.INTERNET 203 * @syscap SystemCapability.Communication.NetManager.Core 204 * @deprecated since 13 205 * @useinstead OH_NetConn_UnregisterDnsResolver 206 * @since 11 207 * @version 1.0 208 */ 209 int32_t OHOS_NetConn_UnregisterDnsResolver(void); 210 211 /** 212 * @brief Registers a custom DNS resolver. 213 * 214 * @param resolver Pointer to the custom DNS resolver. 215 * @return Returns the result code. 216 * {@link NETMANAGER_EXT_SUCCESS} if the operation is successful. 217 * {@link NETMANAGER_ERR_PERMISSION_DENIED} Missing permissions, add permission. 218 * {@link NETMANAGER_ERR_PARAMETER_ERROR} Parameter error. Please enter a correct parameter. 219 * @permission ohos.permission.INTERNET 220 * @syscap SystemCapability.Communication.NetManager.Core 221 * @since 13 222 * @version 1.0 223 */ 224 int32_t OH_NetConn_RegisterDnsResolver(OH_NetConn_CustomDnsResolver resolver); 225 226 /** 227 * @brief Unregisters a custom DNS resolver. 228 * 229 * @return 0 - Success. 201 - Missing permissions. 230 * 401 - Parameter error. 2100002 - Unable to connect to service. 231 * 2100003 - Internal error. 232 * @permission ohos.permission.INTERNET 233 * @syscap SystemCapability.Communication.NetManager.Core 234 * @since 13 235 * @version 1.0 236 */ 237 int32_t OH_NetConn_UnregisterDnsResolver(void); 238 239 /** 240 * @brief Binds a socket to the specific network. 241 * 242 * @param socketFd Socket constructed by user. 243 * @param netHandle Pointer to the network handle that contains the network ID. 244 * @return 0 - Success. 245 * 401 - Parameter error. 246 * 2100002 - Unable to connect to service. 247 * 2100003 - Internal error. 248 * @syscap SystemCapability.Communication.NetManager.Core 249 * @since 12 250 * @version 1.0 251 */ 252 int32_t OH_NetConn_BindSocket(int32_t socketFd, NetConn_NetHandle *netHandle); 253 254 /** 255 * @brief Sets http proxy information to current application. 256 * 257 * @param httpProxy Information about the proxy that needs to be set. 258 * @return 0 - Success. 259 * 401 - Parameter error. 260 * @syscap SystemCapability.Communication.NetManager.Core 261 * @since 12 262 * @version 1.0 263 */ 264 int32_t OH_NetConn_SetAppHttpProxy(NetConn_HttpProxy *httpProxy); 265 266 /** 267 * @brief Registers callback to listen for changes to the application-level http proxy. 268 * 269 * @param appHttpProxyChange Callback that need to be registered to listen for changes to the http proxy. 270 * @param callbackId Callback id returned after registration, associated with a registered callback. 271 * @return 0 - Success. 272 * 401 - Parameter error. 273 * @syscap SystemCapability.Communication.NetManager.Core 274 * @since 12 275 * @version 1.0 276 */ 277 int32_t OH_NetConn_RegisterAppHttpProxyCallback(OH_NetConn_AppHttpProxyChange appHttpProxyChange, uint32_t *callbackId); 278 279 /** 280 * @brief Unregisters a callback function that listens for application-level proxy changes. 281 * 282 * @param callbackId Id of the callback function that needs to be deregistered. 283 * @syscap SystemCapability.Communication.NetManager.Core 284 * @since 12 285 * @version 1.0 286 */ 287 void OH_NetConn_UnregisterAppHttpProxyCallback(uint32_t callbackId); 288 289 /** 290 * @brief Registers callback, used to monitor specific network status. 291 * 292 * @param netSpecifier specifier information. 293 * @param callback The callback needed to be registered. 294 * @param timeout The timeout period in milliseconds. 295 * @param callbackId out param, corresponding to a registered callback. 296 * @return 0 - Success. 297 * 201 - Permission denied. 298 * 401 - Parameter error. 299 * 2100002 - Failed to connect to the service. 300 * 2100003 - System internal error. 301 * 2101008 - The callback already exists. 302 * 2101022 - The number of requests exceeded the maximum allowed. 303 * @permission ohos.permission.GET_NETWORK_INFO 304 * @syscap SystemCapability.Communication.NetManager.Core 305 * @since 12 306 * @version 1.0 307 */ 308 int32_t OH_NetConn_RegisterNetConnCallback(NetConn_NetSpecifier *specifier, NetConn_NetConnCallback *netConnCallback, 309 uint32_t timeout, uint32_t *callbackId); 310 311 /** 312 * @brief Registers a callback to listen default network's status changed. 313 * 314 * @param callback The callback needed to be registered. 315 * @param callbackId out param, corresponding to a registered callback. 316 * @return 0 - Success. 317 * 201 - Permission denied. 318 * 401 - Parameter error. 319 * 2100002 - Failed to connect to the service. 320 * 2100003 - System internal error. 321 * 2101008 - The callback already exists. 322 * 2101022 - The number of requests exceeded the maximum allowed. 323 * @permission ohos.permission.GET_NETWORK_INFO 324 * @syscap SystemCapability.Communication.NetManager.Core 325 * @since 12 326 * @version 1.0 327 */ 328 int32_t OH_NetConn_RegisterDefaultNetConnCallback(NetConn_NetConnCallback *netConnCallback, uint32_t *callbackId); 329 330 /** 331 * @brief Unregisters network status callback. 332 * 333 * @param callBackId the id corresponding to a registered callback. 334 * @return 0 - Success. 335 * 201 - Permission denied. 336 * 401 - Parameter error. 337 * 2100002 - Failed to connect to the service. 338 * 2100003 - System internal error. 339 * 2101007 - The callback does not exists. 340 * @permission ohos.permission.GET_NETWORK_INFO 341 * @syscap SystemCapability.Communication.NetManager.Core 342 * @since 12 343 * @version 1.0 344 */ 345 int32_t OH_NetConn_UnregisterNetConnCallback(uint32_t callBackId); 346 347 #ifdef __cplusplus 348 } 349 #endif 350 351 /** @} */ 352 #endif /* NATIVE_NET_CONN_API_H */ 353