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 * Protect a socket from VPN connections. After protecting, data sent through this socket will go directly to the 181 * underlying network so its traffic will not be forwarded through the VPN. 182 * 183 * @param { number } socketFd - File descriptor of socket, this socket from @ohos.net.socket. 184 * @returns { Promise<void> } The promise returned by the function. 185 * @throws { BusinessError } 401 - Parameter error. 186 * @throws { BusinessError } 2200001 - Invalid parameter value. 187 * @throws { BusinessError } 2200002 - Operation failed. Cannot connect to service. 188 * @throws { BusinessError } 2200003 - System internal error. 189 * @throws { BusinessError } 2203004 - Invalid socket file descriptor. 190 * @syscap SystemCapability.Communication.NetManager.Vpn 191 * @since 11 192 */ 193 protect(socketFd: number): Promise<void>; 194 195 /** 196 * Destroy the VPN network. 197 * 198 * @returns { Promise<void> } The promise returned by the function. 199 * @throws { BusinessError } 401 - Parameter error. 200 * @throws { BusinessError } 2200002 - Operation failed. Cannot connect to service. 201 * @throws { BusinessError } 2200003 - System internal error. 202 * @syscap SystemCapability.Communication.NetManager.Vpn 203 * @since 11 204 */ 205 destroy(): Promise<void>; 206 } 207 208 /** 209 * Define configuration of the VPN network. 210 * 211 * @interface VpnConfig 212 * @syscap SystemCapability.Communication.NetManager.Vpn 213 * @since 11 214 */ 215 export interface VpnConfig { 216 /** 217 * The array of addresses for VPN interface. 218 * 219 * @type {Array<LinkAddress>} 220 * @syscap SystemCapability.Communication.NetManager.Vpn 221 * @since 11 222 */ 223 addresses: Array<LinkAddress>; 224 225 /** 226 * The array of routes for VPN interface. 227 * 228 * @type {?Array<RouteInfo>} 229 * @syscap SystemCapability.Communication.NetManager.Vpn 230 * @since 11 231 */ 232 routes?: Array<RouteInfo>; 233 234 /** 235 * The array of DNS servers for the VPN network. 236 * 237 * @type {?Array<string>} 238 * @syscap SystemCapability.Communication.NetManager.Vpn 239 * @since 11 240 */ 241 dnsAddresses?: Array<string>; 242 243 /** 244 * The array of search domains for the DNS resolver. 245 * 246 * @type {?Array<string>} 247 * @syscap SystemCapability.Communication.NetManager.Vpn 248 * @since 11 249 */ 250 searchDomains?: Array<string>; 251 252 /** 253 * The maximum transmission unit (MTU) for the VPN interface. 254 * 255 * @type {?number} 256 * @syscap SystemCapability.Communication.NetManager.Vpn 257 * @since 11 258 */ 259 mtu?: number; 260 261 /** 262 * Whether ipv4 is supported. The default value is true. 263 * 264 * @type {?boolean} 265 * @syscap SystemCapability.Communication.NetManager.Vpn 266 * @since 11 267 */ 268 isIPv4Accepted?: boolean; 269 270 /** 271 * Whether ipv6 is supported. The default value is false. 272 * 273 * @type {?boolean} 274 * @syscap SystemCapability.Communication.NetManager.Vpn 275 * @since 11 276 */ 277 isIPv6Accepted?: boolean; 278 279 /** 280 * Whether to use the built-in VPN. The default value is false. 281 * 282 * @type {?boolean} 283 * @syscap SystemCapability.Communication.NetManager.Vpn 284 * @since 11 285 */ 286 isInternal?: boolean; 287 288 /** 289 * Whether the VPN interface's file descriptor is in blocking/non-blocking mode. The default value is false. 290 * 291 * @type {?boolean} 292 * @syscap SystemCapability.Communication.NetManager.Vpn 293 * @since 11 294 */ 295 isBlocking?: boolean; 296 297 /** 298 * The array of trustlist for the VPN network. The string indicates package name. 299 * 300 * @type {?Array<string>} 301 * @syscap SystemCapability.Communication.NetManager.Vpn 302 * @since 11 303 */ 304 trustedApplications?: Array<string>; 305 306 /** 307 * The array of blocklist for the VPN network. The string indicates package name. 308 * 309 * @type {?Array<string>} 310 * @syscap SystemCapability.Communication.NetManager.Vpn 311 * @since 11 312 */ 313 blockedApplications?: Array<string>; 314 } 315} 316export default vpnExtension; 317 318