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