1# @ohos.net.vpn (VPN 管理)（系统接口） 2 3VPN 管理模块，支持 VPN 的启动和停止功能。 4本模块是操作系统提供的内置VPN功能，允许用户通过系统的网络设置进行VPN连接，通常提供的功能较少，而且有比较严格的限制。 5 6> **说明：** 7> 本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 本模块为系统接口。 9 10## 导入模块 11 12```js 13import { vpn } from '@kit.NetworkKit'; 14``` 15 16## vpn.createVpnConnection 17 18createVpnConnection(context: AbilityContext): VpnConnection 19 20创建一个 VPN 连接对象。 21 22**系统接口**：此接口为系统接口。 23 24**系统能力**：SystemCapability.Communication.NetManager.Vpn 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ------- | -------------------------------------------------------------------------------- | ---- | ------------ | 30| context | [AbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontext) | 是 | 指定 context。 | 31 32**返回值：** 33 34| 类型 | 说明 | 35| :------------------------------ | :---------------------- | 36| [VpnConnection](#vpnconnection) | 返回一个 VPN 连接对象。 | 37 38**错误码：** 39 40以下错误码的详细介绍参见[VPN 错误码](errorcode-net-vpn.md)。 41 42| 错误码 ID | 错误信息 | 43| --------- | ---------------- | 44| 202 | Non-system applications use system APIs. | 45| 401 | Parameter error. | 46 47**示例：** 48 49**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 50 51Stage 模型示例： 52 53```ts 54import { vpn } from '@kit.NetworkKit'; 55import { common } from '@kit.AbilityKit'; 56 57@Entry 58@Component 59struct Index { 60 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 61 private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context); 62 functiontest() 63 { 64 console.info("vpn createVpnConnection: " + JSON.stringify(this.VpnConnection)); 65 } 66 build() { } 67} 68``` 69 70## VpnConnection 71 72VPN 连接对象。在调用 VpnConnection 的方法前，需要先通过[vpn.createVpnConnection](#vpncreatevpnconnection)创建 VPN 连接对象。 73 74### setUp 75 76setUp(config: VpnConfig, callback: AsyncCallback\<number\>): void 77 78使用 config 创建一个 vpn 网络，使用 callback 方式作为异步方法。 79 80**系统接口**：此接口为系统接口。 81 82**需要权限**：ohos.permission.MANAGE_VPN 83 84**系统能力**：SystemCapability.Communication.NetManager.Vpn 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| -------- | ----------------------- | ---- | -------------------------------------------------------------------------------------------------- | 90| config | [VpnConfig](#vpnconfig) | 是 | 指定 VPN 网络的配置信息。 | 91| callback | AsyncCallback\<number\> | 是 | 回调函数，当成功启动 VPN 网络时，返回虚拟网卡的文件描述符 fd, error 为 undefined，否则为错误对象。 | 92 93**错误码：** 94 95以下错误码的详细介绍参见[VPN 错误码](errorcode-net-vpn.md)。 96 97| 错误码 ID | 错误信息 | 98| --------- | ------------------------------------------------ | 99| 201 | Permission denied. | 100| 202 | Non-system applications use system APIs. | 101| 401 | Parameter error. | 102| 2200001 | Invalid parameter value. | 103| 2200002 | Operation failed. Cannot connect to service. | 104| 2200003 | System internal error. | 105| 2203001 | VPN creation denied. Check the user type. | 106| 2203002 | VPN already exists. | 107 108**示例：** 109 110**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 111 112```js 113import { vpn } from '@kit.NetworkKit'; 114import { common } from '@kit.AbilityKit'; 115import { BusinessError } from '@kit.BasicServicesKit'; 116 117@Entry 118@Component 119struct Index { 120 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 121 private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context); 122 SetUp(): void { 123 let config: vpn.VpnConfig = { 124 addresses: [{ 125 address: { 126 address: "10.0.0.5", 127 family: 1 128 }, 129 prefixLength: 24 130 }], 131 mtu: 1400, 132 dnsAddresses: ["114.114.114.114"] 133 } 134 this.VpnConnection.setUp(config, (error: BusinessError, data: number) => { 135 console.info(JSON.stringify(error)); 136 console.info("tunfd: " + JSON.stringify(data)); 137 }); 138 } 139 build() { } 140} 141``` 142 143### setUp 144 145setUp(config: VpnConfig): Promise\<number\> 146 147使用 config 创建一个 vpn 网络，使用 Promise 方式作为异步方法。 148 149**系统接口**：此接口为系统接口。 150 151**需要权限**：ohos.permission.MANAGE_VPN 152 153**系统能力**：SystemCapability.Communication.NetManager.Vpn 154 155**参数：** 156 157| 参数名 | 类型 | 必填 | 说明 | 158| ------ | ----------------------- | ---- | ------------------------- | 159| config | [VpnConfig](#vpnconfig) | 是 | 指定 VPN 网络的配置信息。 | 160 161**返回值：** 162 163| 类型 | 说明 | 164| ----------------- | -------------------------------------------------------------- | 165| Promise\<number\> | 以 Promise 形式返回获取结果，返回指定虚拟网卡的文件描述符 fd。 | 166 167**错误码：** 168 169以下错误码的详细介绍参见[VPN 错误码](errorcode-net-vpn.md)。 170 171| 错误码 ID | 错误信息 | 172| --------- | ------------------------------------------------ | 173| 201 | Permission denied. | 174| 202 | Non-system applications use system APIs. | 175| 401 | Parameter error. | 176| 2200001 | Invalid parameter value. | 177| 2200002 | Operation failed. Cannot connect to service. | 178| 2200003 | System internal error. | 179| 2203001 | VPN creation denied. Check the user type. | 180| 2203002 | VPN already exists. | 181 182**示例：** 183 184**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 185 186```js 187import { vpn } from '@kit.NetworkKit'; 188import { common } from '@kit.AbilityKit'; 189import { BusinessError } from '@kit.BasicServicesKit'; 190 191@Entry 192@Component 193struct Index { 194 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 195 private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context); 196 SetUp(): void { 197 let config: vpn.VpnConfig = { 198 addresses: [{ 199 address: { 200 address: "10.0.0.5", 201 family: 1 202 }, 203 prefixLength: 24 204 }], 205 mtu: 1400, 206 dnsAddresses: ["114.114.114.114"] 207 } 208 this.VpnConnection.setUp(config).then((data: number) => { 209 console.info("setUp success, tunfd: " + JSON.stringify(data)); 210 }).catch((err: BusinessError) => { 211 console.info("setUp fail" + JSON.stringify(err)); 212 }); 213 } 214 build() { } 215} 216``` 217 218### protect 219 220protect(socketFd: number, callback: AsyncCallback\<void\>): void 221 222保护套接字不受 VPN 连接影响，通过该套接字发送的数据将直接基于物理网络收发，因此其流量不会通过 VPN 转发，使用 callback 方式作为异步方法。 223 224**系统接口**：此接口为系统接口。 225 226**需要权限**：ohos.permission.MANAGE_VPN 227 228**系统能力**：SystemCapability.Communication.NetManager.Vpn 229 230**参数：** 231 232| 参数名 | 类型 | 必填 | 说明 | 233| -------- | --------------------- | ---- | ----------------------------------------------------------------------------------------- | 234| socketFd | number | 是 | 指定保护的 socketfd, 该文件描述符通过[getSocketFd](js-apis-socket.md#getsocketfd10)获取。 | 235| callback | AsyncCallback\<void\> | 是 | 回调函数，成功时，error 为 undefined，失败返回错误码错误信息。 | 236 237**错误码：** 238 239以下错误码的详细介绍参见[VPN 错误码](errorcode-net-vpn.md)。 240 241| 错误码 ID | 错误信息 | 242| --------- | -------------------------------------------- | 243| 201 | Permission denied. | 244| 202 | Non-system applications use system APIs. | 245| 401 | Parameter error. | 246| 2200001 | Invalid parameter value. | 247| 2200002 | Operation failed. Cannot connect to service. | 248| 2200003 | System internal error. | 249| 2203004 | Invalid socket file descriptor. | 250 251**示例：** 252 253**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 254 255```js 256import { socket, vpn } from '@kit.NetworkKit'; 257import { common } from '@kit.AbilityKit'; 258import { BusinessError } from '@kit.BasicServicesKit'; 259 260@Entry 261@Component 262struct Index { 263 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 264 private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context); 265 266 Protect(): void { 267 let tcp: socket.TCPSocket = socket.constructTCPSocketInstance(); 268 let ipAddress: socket.NetAddress = { 269 address: "0.0.0.0" 270 } 271 tcp.bind(ipAddress); 272 let netAddress: socket.NetAddress = { 273 address: "192.168.1.11", 274 port: 8888 275 } 276 let addressConnect: socket.TCPConnectOptions = { 277 address: netAddress, 278 timeout: 6000 279 } 280 tcp.connect(addressConnect); 281 tcp.getSocketFd().then((tunnelfd: number) => { 282 console.info("tunenlfd: " + tunnelfd); 283 this.VpnConnection.protect(tunnelfd, (error: BusinessError) => { 284 console.info(JSON.stringify(error)); 285 }); 286 }); 287 } 288 build() { } 289} 290``` 291 292### protect 293 294protect(socketFd: number): Promise\<void\> 295 296保护套接字不受 VPN 连接影响，通过该套接字发送的数据将直接基于物理网络收发，因此其流量不会通过 VPN 转发, 使用 Promise 方式作为异步方法。 297 298**系统接口**：此接口为系统接口。 299 300**需要权限**：ohos.permission.MANAGE_VPN 301 302**系统能力**：SystemCapability.Communication.NetManager.Vpn 303 304**参数：** 305 306| 参数名 | 类型 | 必填 | 说明 | 307| -------- | ------ | ---- | ------------------------------------------------------------------------------------------- | 308| socketFd | number | 是 | 指定保护的 socketfd, 该文件描述符通过[getSocketFd](js-apis-socket.md#getsocketfd10-1)获取。 | 309 310**返回值：** 311 312| 类型 | 说明 | 313| --------------- | ----------------------------------------------------- | 314| Promise\<void\> | 以 Promise 形式返回设定结果，失败返回错误码错误信息。 | 315 316**错误码：** 317 318以下错误码的详细介绍参见[VPN 错误码](errorcode-net-vpn.md)。 319 320| 错误码 ID | 错误信息 | 321| --------- | -------------------------------------------- | 322| 201 | Permission denied. | 323| 202 | Non-system applications use system APIs. | 324| 401 | Parameter error. | 325| 2200001 | Invalid parameter value. | 326| 2200002 | Operation failed. Cannot connect to service. | 327| 2200003 | System internal error. | 328| 2203004 | Invalid socket file descriptor. | 329 330**示例：** 331 332**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 333 334```js 335import { socket, vpn } from '@kit.NetworkKit'; 336import { common } from '@kit.AbilityKit'; 337import { BusinessError } from '@kit.BasicServicesKit'; 338 339@Entry 340@Component 341struct Index { 342 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 343 private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context); 344 345 Protect(): void { 346 let tcp: socket.TCPSocket = socket.constructTCPSocketInstance(); 347 let ipAddress: socket.NetAddress = { 348 address: "0.0.0.0" 349 } 350 tcp.bind(ipAddress); 351 let netAddress: socket.NetAddress = { 352 address: "192.168.1.11", 353 port: 8888 354 } 355 let addressConnect: socket.TCPConnectOptions = { 356 address: netAddress, 357 timeout: 6000 358 } 359 tcp.connect(addressConnect); 360 tcp.getSocketFd().then((tunnelfd: number) => { 361 console.info("tunenlfd: " + tunnelfd); 362 this.VpnConnection.protect(tunnelfd).then(() => { 363 console.info("protect success."); 364 }).catch((err: BusinessError) => { 365 console.info("protect fail" + JSON.stringify(err)); 366 }); 367 }); 368 } 369 build() { } 370} 371``` 372 373### destroy 374 375destroy(callback: AsyncCallback\<void\>): void 376 377销毁启动的 VPN 网络，使用 callback 方式作为异步方法。 378 379**系统接口**：此接口为系统接口。 380 381**需要权限**：ohos.permission.MANAGE_VPN 382 383**系统能力**：SystemCapability.Communication.NetManager.Vpn 384 385**参数：** 386 387| 参数名 | 类型 | 必填 | 说明 | 388| -------- | --------------------- | ---- | -------------------------------------------------------------- | 389| callback | AsyncCallback\<void\> | 是 | 回调函数，成功时，error 为 undefined，失败返回错误码错误信息。 | 390 391**错误码：** 392 393以下错误码的详细介绍参见[VPN 错误码](errorcode-net-vpn.md)。 394 395| 错误码 ID | 错误信息 | 396| --------- | -------------------------------------------- | 397| 201 | Permission denied. | 398| 202 | Non-system applications use system APIs. | 399| 401 | Parameter error. | 400| 2200002 | Operation failed. Cannot connect to service. | 401| 2200003 | System internal error. | 402 403**示例：** 404 405**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 406 407```js 408import { vpn } from '@kit.NetworkKit'; 409import { common } from '@kit.AbilityKit'; 410import { BusinessError } from '@kit.BasicServicesKit'; 411 412@Entry 413@Component 414struct Index { 415 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 416 private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context); 417 Destroy(): void { 418 this.VpnConnection.destroy((error: BusinessError) => { 419 console.info(JSON.stringify(error)); 420 }); 421 } 422 build() { } 423} 424``` 425 426### destroy 427 428destroy(): Promise\<void\> 429 430销毁启动的 VPN 网络，使用 Promise 方式作为异步方法。 431 432**系统接口**：此接口为系统接口。 433 434**需要权限**：ohos.permission.MANAGE_VPN 435 436**系统能力**：SystemCapability.Communication.NetManager.Vpn 437 438**返回值：** 439 440| 类型 | 说明 | 441| --------------- | ----------------------------------------------------- | 442| Promise\<void\> | 以 Promise 形式返回设定结果，失败返回错误码错误信息。 | 443 444**错误码：** 445 446以下错误码的详细介绍参见[VPN 错误码](errorcode-net-vpn.md)。 447 448| 错误码 ID | 错误信息 | 449| --------- | -------------------------------------------- | 450| 201 | Permission denied. | 451| 401 | Parameter error. | 452| 202 | Non-system applications use system APIs. | 453| 2200002 | Operation failed. Cannot connect to service. | 454| 2200003 | System internal error. | 455 456**示例：** 457 458**注意：** 关于示例代码中this的说明：在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，[请参见获取UIAbility的上下文消息](http://gitee.com/openharmony/docs/blob/222f8d93e6f0056409aac096e041df3fdd8ae5ec/zh-cn/application-dev/application-models/uiability-usage.md)。 459 460```js 461import { vpn } from '@kit.NetworkKit'; 462import { common } from '@kit.AbilityKit'; 463import { BusinessError } from '@kit.BasicServicesKit'; 464 465@Entry 466@Component 467struct Index { 468 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 469 private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context); 470 Destroy(): void { 471 this.VpnConnection.destroy().then(() => { 472 console.info("destroy success."); 473 }).catch((err: BusinessError) => { 474 console.info("destroy fail" + JSON.stringify(err)); 475 }); 476 } 477 build() { } 478} 479``` 480 481## VpnConfig 482 483VPN 配置参数。 484 485**系统接口**：此接口为系统接口。 486 487**系统能力**：SystemCapability.Communication.NetManager.Vpn 488 489| 名称 | 类型 | 必填 | 说明 | 490| ------------------- | -------------------------------------------------------------- | ---- | ----------------------------------- | 491| addresses | Array\<[LinkAddress](js-apis-net-connection.md#linkaddress)\> | 是 | VPN 虚拟网卡的 IP 地址。 | 492| routes | Array\<[RouteInfo](js-apis-net-connection.md#routeinfo)\> | 否 | VPN 虚拟网卡的路由信息。 | 493| dnsAddresses | Array\<string\> | 否 | DNS 服务器地址信息。 | 494| searchDomains | Array\<string\> | 否 | DNS 的搜索域列表。 | 495| mtu | number | 否 | 最大传输单元 MTU 值(单位:字节)。 | 496| isIPv4Accepted | boolean | 否 | 是否支持 IPV4, 默认值为 true。 | 497| isIPv6Accepted | boolean | 否 | 是否支持 IPV6, 默认值为 flase。 | 498| isLegacy | boolean | 否 | 是否支持内置 VPN, 默认值为 flase。 | 499| isBlocking | boolean | 否 | 是否阻塞模式, 默认值为 flase。 | 500| trustedApplications | Array\<string\> | 否 | 白名单信息, string 类型表示的包名。 | 501| blockedApplications | Array\<string\> | 否 | 黑名单信息, string 类型表示的包名。 |