1# @ohos.net.vpnExtension (VPN 增强管理) 2 3三方VPN管理模块，支持三方VPN的启动和停止功能。三方VPN是指由第三方提供的VPN服务，它们通常提供更多的功能和更广泛的网络连接选项，包括更多的安全和隐私功能，以及更全面的定制选项。 4 5> **说明：** 6> 本模块首批接口从 API version 11 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8## 导入模块 9 10```js 11import { vpnExtension } from '@kit.NetworkKit'; 12``` 13 14## LinkAddress<sup>11+</sup> 15type LinkAddress = connection.LinkAddress 16 17获取网络链接信息。 18 19**系统能力**：SystemCapability.Communication.NetManager.Core 20 21| 类型 | 说明 | 22| ------ | ------------------------------------------------------------ | 23| [connection.LinkAddress](./js-apis-net-connection.md#linkaddress) | 网络链路信息 | 24 25## RouteInfo<sup>11+</sup> 26type RouteInfo = connection.RouteInfo 27 28获取网络路由信息。 29 30**系统能力**：SystemCapability.Communication.NetManager.Core 31 32| 类型 | 说明 | 33| ------ | ------------------------------------------------------------ | 34| [connection.RouteInfo](./js-apis-net-connection.md#routeinfo) | 网络路由信息 | 35 36## VpnExtensionContext<sup>11+</sup> 37type VpnExtensionContext = _VpnExtensionContext 38 39vpn扩展的上下文。它允许访问serviceExtension特定资源。 40 41**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 42 43| 类型 | 说明 | 44| ------ | ------------------------------------------------------------ | 45| [_VpnExtensionContext](./js-apis-inner-application-VpnExtensionContext.md) | vpn扩展的上下文 | 46 47## vpnExtension.startVpnExtensionAbility 48 49startVpnExtensionAbility(want: Want): Promise\<void> 50 51启动新的三方vpn功能。 52 53**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 54 55**模型约束**：此接口仅可在Stage模型下使用。 56 57**参数：** 58 59| 参数名 | 类型 | 必填 | 说明 | 60| ------ | ----------------------------------- | ---- | ------------------ | 61| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 指示要启动的信息。 | 62 63**返回值：** 64 65| 类型 | 说明 | 66| -------------- | ----------------------- | 67| Promise\<void> | 无返回值的Promise对象。 | 68 69**错误码：** 70 71| 错误码 ID | 错误信息 | 72| --------- | -------------------------------------- | 73| 401 | If the input parameter is not valid parameter.| 74| 16000001 | The specified ability does not exist. | 75| 16000002 | Incorrect ability type. | 76| 16000006 | Cross-user operations are not allowed. | 77| 16000008 | The crowdtesting application expires. | 78| 16000011 | The context does not exist. | 79| 16000050 | Internal error. | 80| 16200001 | The caller has been released. | 81 82**示例：** 83Stage 模型示例： 84 85```ts 86import { common, Want } from '@kit.AbilityKit'; 87import { vpnExtension } from '@kit.NetworkKit'; 88 89let want: Want = { 90 deviceId: "", 91 bundleName: "com.example.myvpndemo", 92 abilityName: "MyVpnExtAbility", 93}; 94 95@Entry 96@Component 97struct Index { 98 @State message: string = 'Hello World' 99 100 build() { 101 Row() { 102 Column() { 103 Text(this.message) 104 .fontSize(50) 105 .fontWeight(FontWeight.Bold).onClick(() => { 106 console.info("btn click") }) 107 Button('Start Extension').onClick(() => { 108 vpnExtension.startVpnExtensionAbility(want); 109 }).width('70%').fontSize(45).margin(16) 110 }.width('100%') 111 }.height('100%') 112 } 113} 114``` 115 116## vpnExtension.stopVpnExtensionAbility 117 118stopVpnExtensionAbility(want: Want): Promise\<void> 119 120停止同一应用程序中的服务。 121 122**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 123 124**模型约束**：此接口仅可在Stage模型下使用。 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ----------------------------------- | ---- | ---------------- | 130| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 指示要启动的信息 | 131 132**返回值：** 133 134| 类型 | 说明 | 135| -------------- | ----------------------- | 136| Promise\<void> | 无返回值的Promise对象。 | 137 138**错误码：** 139 140| 错误码 ID | 错误信息 | 141| --------- | -------------------------------------- | 142| 401 | If the input parameter is not valid parameter.| 143| 16000001 | The specified ability does not exist. | 144| 16000002 | Incorrect ability type. | 145| 16000006 | Cross-user operations are not allowed. | 146| 16000011 | The context does not exist. | 147| 16000050 | Internal error. | 148| 16200001 | The caller has been released. | 149 150**示例：** 151Stage 模型示例： 152 153```ts 154import { common, Want } from '@kit.AbilityKit'; 155import { vpnExtension } from '@kit.NetworkKit'; 156 157let want: Want = { 158 deviceId: "", 159 bundleName: "com.example.myvpndemo", 160 abilityName: "MyVpnExtAbility", 161}; 162 163@Entry 164@Component 165struct Index { 166 @State message: string = 'Hello World' 167 168 build() { 169 Row() { 170 Column() { 171 Text(this.message) 172 .fontSize(50) 173 .fontWeight(FontWeight.Bold).onClick(() => { 174 console.info("btn click") }) 175 Button('Start Extension').onClick(() => { 176 vpnExtension.startVpnExtensionAbility(want); 177 }).width('70%').fontSize(45).margin(16) 178 Button('Stop Extension').onClick(() => { 179 console.info("btn end") 180 vpnExtension.stopVpnExtensionAbility(want); 181 }).width('70%').fontSize(45).margin(16) 182 183 }.width('100%') 184 }.height('100%') 185 } 186} 187``` 188 189## vpnExtension.createVpnConnection 190 191createVpnConnection(context: VpnExtensionContext): VpnConnection 192 193创建一个 三方VPN 连接对象。 194 195> **说明：** 196> 197> 调用createVpnConnection接口前，需要先调用startVpnExtensionAbility接口启用vpn功能。 198 199**系统能力**：SystemCapability.Communication.NetManager.Vpn 200 201**模型约束**：此接口仅可在Stage模型下使用。 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------- | ------------------------------------------------------------ | ---- | -------------- | 207| context | [VpnExtensionContext](js-apis-inner-application-VpnExtensionContext.md) | 是 | 指定 context。 | 208 209**返回值：** 210 211| 类型 | 说明 | 212| :------------------------------ | :---------------------- | 213| [VpnConnection](#vpnconnection) | 返回一个 VPN 连接对象。 | 214 215**错误码：** 216 217| 错误码 ID | 错误信息 | 218| --------- | ---------------- | 219| 401 | Parameter error. | 220 221**示例：** 222Stage 模型示例： 223 224```ts 225import { vpnExtension, VpnExtensionAbility } from '@kit.NetworkKit'; 226import { common, Want } from '@kit.AbilityKit'; 227 228let context: vpnExtension.VpnExtensionContext; 229export default class MyVpnExtAbility extends VpnExtensionAbility { 230 onCreate(want: Want) { 231 let VpnConnection : vpnExtension.VpnConnection = vpnExtension.createVpnConnection(context); 232 console.info("vpn createVpnConnection: " + JSON.stringify(VpnConnection)); 233 } 234} 235``` 236 237## VpnConnection 238 239VPN 连接对象。在调用 VpnConnection 的方法前，需要先通过vpnExt.createVpnConnection创建 VPN 连接对象。 240 241### create 242 243create(config: VpnConfig): Promise\<number\> 244 245使用 config 创建一个 vpn 网络，使用 Promise 方式作为异步方法。 246 247**系统能力**：SystemCapability.Communication.NetManager.Vpn 248 249**参数：** 250 251| 参数名 | 类型 | 必填 | 说明 | 252| ------ | ----------------------- | ---- | ------------------------- | 253| config | [VpnConfig](#vpnconfig) | 是 | 指定 VPN 网络的配置信息。 | 254 255**返回值：** 256 257| 类型 | 说明 | 258| ----------------- | -------------------------------------------------------------- | 259| Promise\<number\> | 以 Promise 形式返回获取结果，返回指定虚拟网卡的文件描述符 fd。 | 260 261**错误码：** 262 263| 错误码 ID | 错误信息 | 264| --------- | ------------------------------------------------ | 265| 401 | Parameter error. | 266| 2200001 | Invalid parameter value. | 267| 2200002 | Operation failed. Cannot connect to service. | 268| 2200003 | System internal error. | 269| 2203001 | VPN creation denied, please check the user type. | 270| 2203002 | VPN exist already, please execute destroy first. | 271 272**示例：** 273 274```js 275import { vpnExtension, VpnExtensionAbility } from '@kit.NetworkKit'; 276import { common, Want } from '@kit.AbilityKit'; 277import { hilog } from '@kit.PerformanceAnalysisKit'; 278 279let context: vpnExtension.VpnExtensionContext; 280export default class MyVpnExtAbility extends VpnExtensionAbility { 281 private tunIp: string = '10.0.0.5'; 282 private blockedAppName: string = 'com.example.myvpndemo'; 283 onCreate(want: Want) { 284 let VpnConnection : vpnExtension.VpnConnection = vpnExtension.createVpnConnection(context); 285 console.info("vpn createVpnConnection: " + JSON.stringify(VpnConnection)); 286 this.SetupVpn(); 287 } 288 SetupVpn() { 289 class Address { 290 address: string; 291 family: number; 292 293 constructor(address: string, family: number) { 294 this.address = address; 295 this.family = family; 296 } 297 } 298 299 class AddressWithPrefix { 300 address: Address; 301 prefixLength: number; 302 303 constructor(address: Address, prefixLength: number) { 304 this.address = address; 305 this.prefixLength = prefixLength; 306 } 307 } 308 309 class Config { 310 addresses: AddressWithPrefix[]; 311 mtu: number; 312 dnsAddresses: string[]; 313 trustedApplications: string[]; 314 blockedApplications: string[]; 315 316 constructor( 317 tunIp: string, 318 blockedAppName: string 319 ) { 320 this.addresses = [ 321 new AddressWithPrefix(new Address(tunIp, 1), 24) 322 ]; 323 this.mtu = 1400; 324 this.dnsAddresses = ["114.114.114.114"]; 325 this.trustedApplications = []; 326 this.blockedApplications = [blockedAppName]; 327 } 328 } 329 330 let config = new Config(this.tunIp, this.blockedAppName); 331 332 try { 333 let VpnConnection : vpnExtension.VpnConnection = vpnExtension.createVpnConnection(context); 334 VpnConnection.create(config).then((data) => { 335 hilog.error(0x0000, 'developTag', 'tunfd: %{public}s', JSON.stringify(data) ?? ''); 336 }) 337 } catch (error) { 338 hilog.error(0x0000, 'developTag', 'vpn setUp fail: %{public}s', JSON.stringify(error) ?? ''); 339 } 340 } 341} 342``` 343 344### protect 345 346protect(socketFd: number): Promise\<void\> 347 348保护套接字不受 VPN 连接影响，通过该套接字发送的数据将直接基于物理网络收发，因此其流量不会通过 VPN 转发，使用 Promise 方式作为异步方法。 349 350**系统能力**：SystemCapability.Communication.NetManager.Vpn 351 352**参数：** 353 354| 参数名 | 类型 | 必填 | 说明 | 355| -------- | ------ | ---- | ------------------------------------------------------------------------------------------- | 356| socketFd | number | 是 | 指定保护的 socketfd，该文件描述符通过[getSocketFd](js-apis-socket.md#getsocketfd10-1)获取。 | 357 358**返回值：** 359 360| 类型 | 说明 | 361| --------------- | ----------------------------------------------------- | 362| Promise\<void\> | 以 Promise 形式返回设定结果，失败返回错误码错误信息。 | 363 364**错误码：** 365 366| 错误码 ID | 错误信息 | 367| --------- | -------------------------------------------- | 368| 401 | Parameter error. | 369| 2200001 | Invalid parameter value. | 370| 2200002 | Operation failed. Cannot connect to service. | 371| 2200003 | System internal error. | 372| 2203004 | Invalid socket file descriptor. | 373 374**示例：** 375 376```js 377import { vpnExtension, VpnExtensionAbility } from '@kit.NetworkKit'; 378import { common, Want } from '@kit.AbilityKit'; 379import { hilog } from '@kit.PerformanceAnalysisKit'; 380 381let g_tunnelFd = -1; 382let context: vpnExtension.VpnExtensionContext; 383export default class MyVpnExtAbility extends VpnExtensionAbility { 384 private vpnServerIp: string = '192.168.31.13'; 385 onCreate(want: Want) { 386 let VpnConnection : vpnExtension.VpnConnection = vpnExtension.createVpnConnection(context); 387 console.info("vpn createVpnConnection: " + JSON.stringify(VpnConnection)); 388 this.CreateTunnel(); 389 this.Protect(); 390 } 391 CreateTunnel() { 392 g_tunnelFd = 8888; 393 } 394 Protect() { 395 hilog.info(0x0000, 'developTag', '%{public}s', 'vpn Protect'); 396 let VpnConnection : vpnExtension.VpnConnection = vpnExtension.createVpnConnection(context); 397 VpnConnection.protect(g_tunnelFd).then(() => { 398 hilog.info(0x0000, 'developTag', '%{public}s', 'vpn Protect Success'); 399 }).catch((err : Error) => { 400 hilog.error(0x0000, 'developTag', 'vpn Protect Failed %{public}s', JSON.stringify(err) ?? ''); 401 }) 402 } 403} 404``` 405 406### destroy 407 408destroy(): Promise\<void\> 409 410销毁启动的 VPN 网络，使用 Promise 方式作为异步方法。 411 412**系统能力**：SystemCapability.Communication.NetManager.Vpn 413 414**返回值：** 415 416| 类型 | 说明 | 417| --------------- | ----------------------------------------------------- | 418| Promise\<void\> | 以 Promise 形式返回设定结果，失败返回错误码错误信息。 | 419 420**错误码：** 421 422| 错误码 ID | 错误信息 | 423| --------- | -------------------------------------------- | 424| 401 | Parameter error. | 425| 2200002 | Operation failed. Cannot connect to service. | 426| 2200003 | System internal error. | 427 428**示例：** 429 430```js 431import { vpnExtension, VpnExtensionAbility } from '@kit.NetworkKit'; 432import { common, Want } from '@kit.AbilityKit'; 433import { BusinessError } from '@kit.BasicServicesKit'; 434 435let context: vpnExtension.VpnExtensionContext; 436export default class MyVpnExtAbility extends VpnExtensionAbility { 437 onCreate(want: Want) { 438 let VpnConnection : vpnExtension.VpnConnection = vpnExtension.createVpnConnection(context); 439 console.info("vpn createVpnConnection: " + JSON.stringify(VpnConnection)); 440 VpnConnection.destroy().then(() => { 441 console.info("destroy success."); 442 }).catch((error : BusinessError) => { 443 console.error("destroy fail" + JSON.stringify(error)); 444 }); 445 } 446} 447``` 448 449## VpnConfig 450 451三方VPN配置参数。 452 453**系统能力**：SystemCapability.Communication.NetManager.Vpn 454 455| 名称 | 类型 | 必填 | 说明 | 456| ------------------- | -------------------------------------------------------------- | ---- | ----------------------------------- | 457| addresses | Array\<[LinkAddress](js-apis-net-connection.md#linkaddress)\> | 是 | VPN 虚拟网卡的 IP 地址。 | 458| routes | Array\<[RouteInfo](js-apis-net-connection.md#routeinfo)\> | 否 | VPN 虚拟网卡的路由信息(目前最多可配置1024条路由)。 | 459| dnsAddresses | Array\<string\> | 否 | DNS 服务器地址信息。 | 460| searchDomains | Array\<string\> | 否 | DNS 的搜索域列表。 | 461| mtu | number | 否 | 最大传输单元 MTU 值(单位:字节)。取值范围：576-1500。 | 462| isIPv4Accepted | boolean | 否 | 是否支持 IPV4, 默认值为 true。true：支持 IPV4；false：不支持 IPV4。 | 463| isIPv6Accepted | boolean | 否 | 是否支持 IPV6, 默认值为 false。true：支持 IPV6；false：不支持 IPV6。 | 464| isInternal | boolean | 否 | 是否支持内置 VPN, 默认值为 false。true：支持内置 VPN；false：不支持内置 VPN。 | 465| isBlocking | boolean | 否 | 是否阻塞模式, 默认值为 false。true：阻塞模式；false：非阻塞模式。 | 466| trustedApplications | Array\<string\> | 否 | 白名单信息, string 类型表示的包名。 | 467| blockedApplications | Array\<string\> | 否 | 黑名单信息, string 类型表示的包名。 | 468 469**示例：** 470 471```js 472import { vpnExtension} from '@kit.NetworkKit'; 473 474let vpnConfig: vpnExtension.VpnConfig = { 475 addresses: [], 476 routes: [{ 477 interface: "eth0", 478 destination: { 479 address: { 480 address:'', 481 family:1, 482 port:8080 483 }, 484 prefixLength:1 485 }, 486 gateway: { 487 address:'', 488 family:1, 489 port:8080 490 }, 491 hasGateway: true, 492 isDefaultRoute: true, 493 }], 494 mtu: 1400, 495 dnsAddresses: ["223.5.5.5", "223.6.6.6"], 496 trustedApplications: [], 497 blockedApplications: [], 498} 499let context: vpnExtension.VpnExtensionContext; 500 501function vpnCreate(){ 502 let VpnConnection: vpnExtension.VpnConnection = vpnExtension.createVpnConnection(context); 503 VpnConnection.create(vpnConfig).then((data) => { 504 console.info("vpn create " + JSON.stringify(data)); 505 }) 506} 507```