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