openharmony 鸿蒙 js-apis-net-vpn-sys

2025-06-16 浏览 (1)

@ohos.net.vpn (VPN 管理)（系统接口）

VPN 管理模块，支持 VPN 的启动和停止功能。 本模块是操作系统提供的内置VPN功能，允许用户通过系统的网络设置进行VPN连接，通常提供的功能较少，而且有比较严格的限制。

说明： 本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 本模块为系统接口。

导入模块

import { vpn } from '@kit.NetworkKit';

vpn.createVpnConnection

createVpnConnection(context: AbilityContext): VpnConnection

创建一个 VPN 连接对象。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Communication.NetManager.Vpn

参数：

参数名类型必填说明
contextAbilityContext是指定 context。

返回值：

类型说明
VpnConnection返回一个 VPN 连接对象。

错误码：

以下错误码的详细介绍参见VPN 错误码。

错误码 ID错误信息
202Non-system applications use system APIs.
401Parameter error.

示例：

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

Stage 模型示例：

import { vpn } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context);
  functiontest()
  {
    console.info("vpn createVpnConnection: " + JSON.stringify(this.VpnConnection));
  }
  build() {  }
}

VpnConnection

VPN 连接对象。在调用 VpnConnection 的方法前，需要先通过vpn.createVpnConnection创建 VPN 连接对象。

setUp

setUp(config: VpnConfig, callback: AsyncCallback<number>): void

使用 config 创建一个 vpn 网络，使用 callback 方式作为异步方法。

系统接口：此接口为系统接口。

需要权限：ohos.permission.MANAGE_VPN

系统能力：SystemCapability.Communication.NetManager.Vpn

参数：

参数名类型必填说明
configVpnConfig是指定 VPN 网络的配置信息。
callbackAsyncCallback<number>是回调函数，当成功启动 VPN 网络时，返回虚拟网卡的文件描述符 fd, error 为 undefined，否则为错误对象。

错误码：

以下错误码的详细介绍参见VPN 错误码。

错误码 ID错误信息
201Permission denied.
202Non-system applications use system APIs.
401Parameter error.
2200001Invalid parameter value.
2200002Operation failed. Cannot connect to service.
2200003System internal error.
2203001VPN creation denied. Check the user type.
2203002VPN already exists.

示例：

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

import { vpn } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context);
  SetUp(): void {
    let config: vpn.VpnConfig = {
      addresses: [{
        address: {
          address: "10.0.0.5",
          family: 1
        },
        prefixLength: 24
      }],
      mtu: 1400,
      dnsAddresses: ["114.114.114.114"]
    }
    this.VpnConnection.setUp(config, (error: BusinessError, data: number) => {
      console.error(JSON.stringify(error));
      console.info("tunfd: " + JSON.stringify(data));
    });
  }
  build() { }
}

setUp

setUp(config: VpnConfig): Promise<number>

使用 config 创建一个 vpn 网络，使用 Promise 方式作为异步方法。

系统接口：此接口为系统接口。

需要权限：ohos.permission.MANAGE_VPN

系统能力：SystemCapability.Communication.NetManager.Vpn

参数：

参数名类型必填说明
configVpnConfig是指定 VPN 网络的配置信息。

返回值：

类型说明
Promise<number>以 Promise 形式返回获取结果，返回指定虚拟网卡的文件描述符 fd。

错误码：

以下错误码的详细介绍参见VPN 错误码。

错误码 ID错误信息
201Permission denied.
202Non-system applications use system APIs.
401Parameter error.
2200001Invalid parameter value.
2200002Operation failed. Cannot connect to service.
2200003System internal error.
2203001VPN creation denied. Check the user type.
2203002VPN already exists.

示例：

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

import { vpn } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context);
  SetUp(): void {
    let config: vpn.VpnConfig = {
      addresses: [{
        address: {
          address: "10.0.0.5",
          family: 1
        },
        prefixLength: 24
      }],
      mtu: 1400,
      dnsAddresses: ["114.114.114.114"]
    }
    this.VpnConnection.setUp(config).then((data: number) => {
      console.info("setUp success, tunfd: " + JSON.stringify(data));
    }).catch((err: BusinessError) => {
      console.error("setUp fail" + JSON.stringify(err));
    });
  }
  build() { }
}

protect

protect(socketFd: number, callback: AsyncCallback<void>): void

保护套接字不受 VPN 连接影响，通过该套接字发送的数据将直接基于物理网络收发，因此其流量不会通过 VPN 转发，使用 callback 方式作为异步方法。

系统接口：此接口为系统接口。

需要权限：ohos.permission.MANAGE_VPN

系统能力：SystemCapability.Communication.NetManager.Vpn

参数：

参数名类型必填说明
socketFdnumber是指定保护的 socketfd, 该文件描述符通过getSocketFd获取。
callbackAsyncCallback<void>是回调函数，成功时，error 为 undefined，失败返回错误码错误信息。

错误码：

以下错误码的详细介绍参见VPN 错误码。

错误码 ID错误信息
201Permission denied.
202Non-system applications use system APIs.
401Parameter error.
2200001Invalid parameter value.
2200002Operation failed. Cannot connect to service.
2200003System internal error.
2203004Invalid socket file descriptor.

示例：

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

import { socket, vpn } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context);

  Protect(): void {
    let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
    let ipAddress: socket.NetAddress = {
      address: "0.0.0.0"
    }
    tcp.bind(ipAddress);
    let netAddress: socket.NetAddress = {
      address: "192.168.1.11",
      port: 8888
    }
    let addressConnect: socket.TCPConnectOptions = {
      address: netAddress,
      timeout: 6000
    }
    tcp.connect(addressConnect);
    tcp.getSocketFd().then((tunnelfd: number) => {
      console.info("tunenlfd: " + tunnelfd);
      this.VpnConnection.protect(tunnelfd, (error: BusinessError) => {
        console.error(JSON.stringify(error));
      });
    });
  }
  build() { }
}

protect

protect(socketFd: number): Promise<void>

保护套接字不受 VPN 连接影响，通过该套接字发送的数据将直接基于物理网络收发，因此其流量不会通过 VPN 转发, 使用 Promise 方式作为异步方法。

系统接口：此接口为系统接口。

需要权限：ohos.permission.MANAGE_VPN

系统能力：SystemCapability.Communication.NetManager.Vpn

参数：

参数名类型必填说明
socketFdnumber是指定保护的 socketfd, 该文件描述符通过getSocketFd获取。

返回值：

类型说明
Promise<void>以 Promise 形式返回设定结果，失败返回错误码错误信息。

错误码：

以下错误码的详细介绍参见VPN 错误码。

错误码 ID错误信息
201Permission denied.
202Non-system applications use system APIs.
401Parameter error.
2200001Invalid parameter value.
2200002Operation failed. Cannot connect to service.
2200003System internal error.
2203004Invalid socket file descriptor.

示例：

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

import { socket, vpn } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context);

  Protect(): void {
    let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
    let ipAddress: socket.NetAddress = {
      address: "0.0.0.0"
    }
    tcp.bind(ipAddress);
    let netAddress: socket.NetAddress = {
      address: "192.168.1.11",
      port: 8888
    }
    let addressConnect: socket.TCPConnectOptions = {
      address: netAddress,
      timeout: 6000
    }
    tcp.connect(addressConnect);
    tcp.getSocketFd().then((tunnelfd: number) => {
      console.info("tunenlfd: " + tunnelfd);
      this.VpnConnection.protect(tunnelfd).then(() => {
        console.info("protect success.");
      }).catch((err: BusinessError) => {
        console.error("protect fail" + JSON.stringify(err));
      });
    });
  }
  build() { }
}

destroy

destroy(callback: AsyncCallback<void>): void

销毁启动的 VPN 网络，使用 callback 方式作为异步方法。

系统接口：此接口为系统接口。

需要权限：ohos.permission.MANAGE_VPN

系统能力：SystemCapability.Communication.NetManager.Vpn

参数：

参数名类型必填说明
callbackAsyncCallback<void>是回调函数，成功时，error 为 undefined，失败返回错误码错误信息。

错误码：

以下错误码的详细介绍参见VPN 错误码。

错误码 ID错误信息
201Permission denied.
202Non-system applications use system APIs.
401Parameter error.
2200002Operation failed. Cannot connect to service.
2200003System internal error.

示例：

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

import { vpn } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context);
  Destroy(): void {
    this.VpnConnection.destroy((error: BusinessError) => {
      console.error(JSON.stringify(error));
    });
  }
  build() { }
}

destroy

destroy(): Promise<void>

销毁启动的 VPN 网络，使用 Promise 方式作为异步方法。

系统接口：此接口为系统接口。

需要权限：ohos.permission.MANAGE_VPN

系统能力：SystemCapability.Communication.NetManager.Vpn

返回值：

类型说明
Promise<void>以 Promise 形式返回设定结果，失败返回错误码错误信息。

错误码：

以下错误码的详细介绍参见VPN 错误码。

错误码 ID错误信息
201Permission denied.
401Parameter error.
202Non-system applications use system APIs.
2200002Operation failed. Cannot connect to service.
2200003System internal error.

示例：

说明：

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。如需在页面中使用UIAbilityContext提供的能力，请参见获取UIAbility的上下文信息。

import { vpn } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  private VpnConnection: vpn.VpnConnection = vpn.createVpnConnection(this.context);
  Destroy(): void {
    this.VpnConnection.destroy().then(() => {
      console.info("destroy success.");
    }).catch((err: BusinessError) => {
      console.error("destroy fail" + JSON.stringify(err));
    });
  }
  build() { }
}

VpnConfig

VPN 配置参数。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Communication.NetManager.Vpn

名称类型必填说明
addressesArray<LinkAddress>是VPN 虚拟网卡的 IP 地址。
routesArray<RouteInfo>否VPN 虚拟网卡的路由信息。
dnsAddressesArray<string>否DNS 服务器地址信息。
searchDomainsArray<string>否DNS 的搜索域列表。
mtunumber否最大传输单元 MTU 值(单位:字节)。
isIPv4Acceptedboolean否是否支持 IPV4, 默认值为 true。
isIPv6Acceptedboolean否是否支持 IPV6, 默认值为 flase。
isLegacyboolean否是否支持内置 VPN, 默认值为 flase。
isBlockingboolean否是否阻塞模式, 默认值为 flase。
trustedApplicationsArray<string>否白名单信息, string 类型表示的包名。
blockedApplicationsArray<string>否黑名单信息, string 类型表示的包名。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Network Kit（网络服务）

harmony 鸿蒙NetConn_ConnectionProperties

harmony 鸿蒙NetConn_HttpProxy

harmony 鸿蒙NetConn_NetAddr

harmony 鸿蒙NetConn_NetCapabilities

harmony 鸿蒙NetConn_NetConnCallback

harmony 鸿蒙NetConn_NetHandle

harmony 鸿蒙NetConn_NetHandleList

harmony 鸿蒙NetConn_NetSpecifier

harmony 鸿蒙NetConn_Route

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/5rfVWv