1/* 2 * Copyright (C) 2023 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/** 17 * @file 18 * @kit NetworkKit 19 */ 20 21import type connection from './@ohos.net.connection'; 22import type _VpnExtensionContext from './application/VpnExtensionContext'; 23import type Want from './@ohos.app.ability.Want'; 24 25/** 26 * Provides VPN related interfaces. 27 * @namespace vpnExtension 28 * @syscap SystemCapability.Communication.NetManager.Vpn 29 * @since 11 30 */ 31declare namespace vpnExtension { 32 /** 33 * Get network link information. 34 * @typedef { connection.LinkAddress } 35 * @syscap SystemCapability.Communication.NetManager.Core 36 * @since 11 37 */ 38 export type LinkAddress = connection.LinkAddress; 39 40 /** 41 * Get network route information. 42 * @typedef { connection.RouteInfo } 43 * @syscap SystemCapability.Communication.NetManager.Core 44 * @since 11 45 */ 46 export type RouteInfo = connection.RouteInfo; 47 48 /** 49 * The context of vpn extension. It allows access to 50 * serviceExtension-specific resources. 51 * @typedef _VpnExtensionContext 52 * @syscap SystemCapability.Ability.AbilityRuntime.Core 53 * @since 11 54 */ 55 export type VpnExtensionContext = _VpnExtensionContext; 56 57 /** 58 * Starts a new vpn extension ability. 59 * 60 * @param { Want } want - Indicates the want info to start. 61 * @returns { Promise<void> } The promise returned by the function. 62 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 63 * @throws { BusinessError } 16000001 - The specified ability does not exist. 64 * @throws { BusinessError } 16000002 - Incorrect ability type. 65 * @throws { BusinessError } 16000006 - Cross-user operations are not allowed. 66 * @throws { BusinessError } 16000008 - The crowdtesting application expires. 67 * @throws { BusinessError } 16000011 - The context does not exist. 68 * @throws { BusinessError } 16000050 - Internal error. 69 * @throws { BusinessError } 16200001 - The caller has been released. 70 * @syscap SystemCapability.Ability.AbilityRuntime.Core 71 * @stagemodelonly 72 * @since 11 73 */ 74 function startVpnExtensionAbility(want: Want): Promise<void>; 75 76 /** 77 * Stops a service within the same application. 78 * 79 * @param { Want } want - Indicates the want info to start. 80 * @returns { Promise<void> } The promise returned by the function. 81 * @throws { BusinessError } 401 - If the input parameter is not valid parameter. 82 * @throws { BusinessError } 16000001 - The specified ability does not exist. 83 * @throws { BusinessError } 16000002 - Incorrect ability type. 84 * @throws { BusinessError } 16000006 - Cross-user operations are not allowed. 85 * @throws { BusinessError } 16000011 - The context does not exist. 86 * @throws { BusinessError } 16000050 - Internal error. 87 * @throws { BusinessError } 16200001 - The caller has been released. 88 * @syscap SystemCapability.Ability.AbilityRuntime.Core 89 * @stagemodelonly 90 * @since 11 91 */ 92 function stopVpnExtensionAbility(want: Want): Promise<void>; 93 94 /** 95 * Set the Enable/Disable Always on VPN mode for a device. 96 * 97 * @permission ohos.permission.MANAGE_VPN 98 * @param { boolean } enable - Always on enable or disable 99 * @param { string } bundleName - bundleName is used to set always on. 100 * @returns { Promise<void> } The promise returned by the function. 101 * @throws { BusinessError } 201 - Permission denied. 102 * @throws { BusinessError } 202 - Non-system applications use system APIs. 103 * @throws { BusinessError } 401 - Parameter error. 104 * @syscap SystemCapability.Communication.NetManager.Vpn 105 * @systemapi Hide this for inner system use. 106 * @stagemodelonly 107 * @since 11 108 */ 109 function setAlwaysOnVpnEnabled(enable: boolean, bundleName: string): Promise<void>; 110 111 /** 112 * Get the Always on VPN mode status for a device. 113 * 114 * @permission ohos.permission.MANAGE_VPN 115 * @param { string } bundleName - bundleName is used to retrieve whether it has the always on. 116 * @returns { Promise<boolean>} return the mode for alway on vpn status 117 * @throws { BusinessError } 201 - Permission denied. 118 * @throws { BusinessError } 202 - Non-system applications use system APIs. 119 * @throws { BusinessError } 401 - Parameter error. 120 * @syscap SystemCapability.Communication.NetManager.Vpn 121 * @systemapi Hide this for inner system use. 122 * @stagemodelonly 123 * @since 11 124 */ 125 function isAlwaysOnVpnEnabled(bundleName: string): Promise<boolean>; 126 127 /** 128 * Update a VPN dialog authorize information 129 * 130 * @permission ohos.permission.MANAGE_VPN 131 * @param { string } bundleName - authorize or not 132 * @returns { boolean } The promise returned by the function. 133 * @throws { BusinessError } 201 - Permission denied. 134 * @throws { BusinessError } 202 - Non-system applications use system APIs. 135 * @throws { BusinessError } 401 - Parameter error. 136 * @syscap SystemCapability.Communication.NetManager.Vpn 137 * @systemapi Hide this for inner system use. 138 * @stagemodelonly 139 * @since 11 140 */ 141 function updateVpnAuthorizedState(bundleName: string): boolean; 142 /** 143 * Create a VPN connection using the VpnExtensionContext. 144 * 145 * @param { VpnExtensionContext } context - Indicates the context of application or capability. 146 * @returns { VpnConnection } the VpnConnection of the construct VpnConnection instance. 147 * @throws { BusinessError } 401 - Parameter error. 148 * @syscap SystemCapability.Communication.NetManager.Vpn 149 * @stagemodelonly 150 * @since 11 151 */ 152 function createVpnConnection(context: VpnExtensionContext): VpnConnection; 153 154 /** 155 * Defines a VPN connection. 156 * 157 * @interface VpnConnection 158 * @syscap SystemCapability.Communication.NetManager.Vpn 159 * @since 11 160 */ 161 export interface VpnConnection { 162 163 /** 164 * Create a VPN network using the VpnConfig. 165 * 166 * @param { VpnConfig } config - Indicates the {@link VpnConfig} configuration of the VPN network. 167 * @returns { Promise<number> } The promise returns file descriptor of VPN interface. 168 * @throws { BusinessError } 401 - Parameter error. 169 * @throws { BusinessError } 2200001 - Invalid parameter value. 170 * @throws { BusinessError } 2200002 - Operation failed. Cannot connect to service. 171 * @throws { BusinessError } 2200003 - System internal error. 172 * @throws { BusinessError } 2203001 - VPN creation denied, please check the user type. 173 * @throws { BusinessError } 2203002 - VPN exist already, please execute destroy first. 174 * @syscap SystemCapability.Communication.NetManager.Vpn 175 * @since 11 176 */ 177 create(config: VpnConfig): Promise<number>; 178 179 /** 180 * generate vpn id. 181 * 182 * @returns { Promise<string> } The promise returns vpn id. 183 * @throws { BusinessError } 19900001 - Invalid parameter value. 184 * @throws { BusinessError } 19900002 - System internal error. 185 * @syscap SystemCapability.Communication.NetManager.Vpn 186 * @since 20 187 */ 188 generateVpnId(): Promise<string>; 189 190 /** 191 * Protect a socket from VPN connections. After protecting, data sent through this socket will go directly to the 192 * underlying network so its traffic will not be forwarded through the VPN. 193 * 194 * @param { number } socketFd - File descriptor of socket, this socket from @ohos.net.socket. 195 * @returns { Promise<void> } The promise returned by the function. 196 * @throws { BusinessError } 401 - Parameter error. 197 * @throws { BusinessError } 2200001 - Invalid parameter value. 198 * @throws { BusinessError } 2200002 - Operation failed. Cannot connect to service. 199 * @throws { BusinessError } 2200003 - System internal error. 200 * @throws { BusinessError } 2203004 - Invalid socket file descriptor. 201 * @syscap SystemCapability.Communication.NetManager.Vpn 202 * @since 11 203 */ 204 protect(socketFd: number): Promise<void>; 205 206 /** 207 * Destroy the VPN network. 208 * 209 * @returns { Promise<void> } The promise returned by the function. 210 * @throws { BusinessError } 401 - Parameter error. 211 * @throws { BusinessError } 2200002 - Operation failed. Cannot connect to service. 212 * @throws { BusinessError } 2200003 - System internal error. 213 * @syscap SystemCapability.Communication.NetManager.Vpn 214 * @since 11 215 */ 216 destroy(): Promise<void>; 217 218 /** 219 * Destroy the VPN network. 220 * 221 * @param { string } vpnId - vpn id. 222 * @returns { Promise<void> } The promise returned by the function. 223 * @throws { BusinessError } 19900001 - Invalid parameter value. 224 * @throws { BusinessError } 19900002 - System internal error. 225 * @syscap SystemCapability.Communication.NetManager.Vpn 226 * @since 20 227 */ 228 destroy(vpnId: string): Promise<void>; 229 } 230 231 /** 232 * Define configuration of the VPN network. 233 * 234 * @interface VpnConfig 235 * @syscap SystemCapability.Communication.NetManager.Vpn 236 * @since 11 237 */ 238 export interface VpnConfig { 239 /** 240 * The uuid for the VPN network. 241 * @type {?string} 242 * @syscap SystemCapability.Communication.NetManager.Vpn 243 * @since 20 244 */ 245 vpnId?: string; 246 247 /** 248 * The array of addresses for VPN interface. 249 * 250 * @type {Array<LinkAddress>} 251 * @syscap SystemCapability.Communication.NetManager.Vpn 252 * @since 11 253 */ 254 addresses: Array<LinkAddress>; 255 256 /** 257 * The array of routes for VPN interface. 258 * 259 * @type {?Array<RouteInfo>} 260 * @syscap SystemCapability.Communication.NetManager.Vpn 261 * @since 11 262 */ 263 routes?: Array<RouteInfo>; 264 265 /** 266 * The array of DNS servers for the VPN network. 267 * 268 * @type {?Array<string>} 269 * @syscap SystemCapability.Communication.NetManager.Vpn 270 * @since 11 271 */ 272 dnsAddresses?: Array<string>; 273 274 /** 275 * The array of search domains for the DNS resolver. 276 * 277 * @type {?Array<string>} 278 * @syscap SystemCapability.Communication.NetManager.Vpn 279 * @since 11 280 */ 281 searchDomains?: Array<string>; 282 283 /** 284 * The maximum transmission unit (MTU) for the VPN interface. 285 * 286 * @type {?number} 287 * @syscap SystemCapability.Communication.NetManager.Vpn 288 * @since 11 289 */ 290 mtu?: number; 291 292 /** 293 * Whether ipv4 is supported. The default value is true. 294 * 295 * @type {?boolean} 296 * @syscap SystemCapability.Communication.NetManager.Vpn 297 * @since 11 298 */ 299 isIPv4Accepted?: boolean; 300 301 /** 302 * Whether ipv6 is supported. The default value is false. 303 * 304 * @type {?boolean} 305 * @syscap SystemCapability.Communication.NetManager.Vpn 306 * @since 11 307 */ 308 isIPv6Accepted?: boolean; 309 310 /** 311 * Whether to use the built-in VPN. The default value is false. 312 * 313 * @type {?boolean} 314 * @syscap SystemCapability.Communication.NetManager.Vpn 315 * @since 11 316 */ 317 isInternal?: boolean; 318 319 /** 320 * Whether the VPN interface's file descriptor is in blocking/non-blocking mode. The default value is false. 321 * 322 * @type {?boolean} 323 * @syscap SystemCapability.Communication.NetManager.Vpn 324 * @since 11 325 */ 326 isBlocking?: boolean; 327 328 /** 329 * The array of trustlist for the VPN network. The string indicates package name. 330 * 331 * @type {?Array<string>} 332 * @syscap SystemCapability.Communication.NetManager.Vpn 333 * @since 11 334 */ 335 trustedApplications?: Array<string>; 336 337 /** 338 * The array of blocklist for the VPN network. The string indicates package name. 339 * 340 * @type {?Array<string>} 341 * @syscap SystemCapability.Communication.NetManager.Vpn 342 * @since 11 343 */ 344 blockedApplications?: Array<string>; 345 } 346} 347export default vpnExtension; 348 349