From 5d6722c547b1e82d8039f0e77244c24389ff5cec Mon Sep 17 00:00:00 2001 From: xujie Date: Wed, 5 Jul 2023 14:36:22 +0800 Subject: [PATCH] Add vpn md Change-Id: If4a8f87f34e63938ce63b1a216916f9ee8b6dc92 Signed-off-by: xujie --- .../reference/apis/js-apis-net-vpn.md | 399 ++++++++++++++++++ .../reference/apis/js-apis-socket.md | 81 ++++ .../reference/errorcodes/errorcode-net-vpn.md | 61 +++ 3 files changed, 541 insertions(+) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-net-vpn.md create mode 100644 zh-cn/application-dev/reference/errorcodes/errorcode-net-vpn.md diff --git a/zh-cn/application-dev/reference/apis/js-apis-net-vpn.md b/zh-cn/application-dev/reference/apis/js-apis-net-vpn.md new file mode 100644 index 0000000000..b30e503c82 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-net-vpn.md @@ -0,0 +1,399 @@ +# @ohos.net.vpn (VPN管理) + +VPN管理模块，支持VPN的启动和停止功能。 + +> **说明：** +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```js +import vpn from '@ohos.net.vpn'; +``` + +## vpn.createVpnConnection10+ + +function createVpnConnection(context: AbilityContext): VpnConnection; + +创建一个VPN连接对象。 + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| context | AbilityContext | 是 | 指定context | + +**错误码：** + +以下错误码的详细介绍参见[VPN错误码](../errorcodes/errorcode-net-vpn)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 401 | Parameter error. | + +**示例：** + +```js + import featureAbility from '@ohos.ability.featureAbility'; + + let context = featureAbility.getContext(); + VpnConnection = vpn.createVpnConnection(context); + console.info("vpn onInit: " + JSON.stringify(VpnConnection)); +``` + +## VpnConnection.setUp10+ + +setUp(config: VpnConfig, callback: AsyncCallback\): void; + +使用config创建一个vpn网络，使用callback方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.MANAGE_VPN + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| config | [VpnConfig](#vpnconfig10) | 是 | 指定VPN网络的配置信息。 | +| callback | AsyncCallback\ | 是 | 回调函数，当成功启动VPN网络时，返回虚拟网卡的tunfd, error为undefined，否则为错误对象。 | + +**错误码：** + +以下错误码的详细介绍参见[VPN错误码](../errorcodes/errorcode-net-vpn)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2100003 | System internal error. | +| 2203001 | VPN creation denied, please check the user type. | +| 2203002 | VPN exist already, please execute destroy first. | + +**示例：** + +```js + let config = { + addresses: [{ + address: { + address: "10.0.0.5", + family: 1, + }, + prefixLength: 24, + }], + routes: [], + mtu: 1400, + dnsAddresses:[ + "8.8.8.8", // 114.114.114.114 + ], + acceptedApplications:[], + refusedApplications:[], + } + VpnConnection.setUp(config, (error, data) => { + console.info(JSON.stringify(error)); + console.info("tunfd: " + JSON.stringify(data)); + }) +``` + +## VpnConnection.setUp10+ + +setUp(config: VpnConfig): Promise\; + +使用config创建一个vpn网络，使用Promise方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.MANAGE_VPN + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| config | [VpnConfig](#vpnconfig10) | 是 | 指定VPN网络的配置信息。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回获取结果，返回指定虚拟网卡的tunfd。 | + +**错误码：** + +以下错误码的详细介绍参见[VPN错误码](../errorcodes/errorcode-net-vpn)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2100003 | System internal error. | +| 2203001 | VPN creation denied, please check the user type. | +| 2203002 | VPN exist already, please execute destroy first. | + +**示例：** + +```js + let config = { + addresses: [{ + address: { + address: "10.0.0.5", + family: 1, + }, + prefixLength: 24, + }], + routes: [], + mtu: 1400, + dnsAddresses:[ + "8.8.8.8", // 114.114.114.114 + ], + acceptedApplications:[], + refusedApplications:[], + } + VpnConnection.setUp(config).then((data) => { + console.info(TAG + "setUp success, tunfd: " + JSON.stringify(data)) + }).catch(err => { + console.info(TAG + "setUp fail" + JSON.stringify(err)) + }) +``` + +## VpnConnection.protect10+ + +protect(socketFd: number, callback: AsyncCallback\): void; + +保护套接字不受VPN连接。经过保护后，通过此套接字发送的数据将直接进入底层网络，因此其流量不会通过VPN转发，使用callback方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.MANAGE_VPN + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| socketFd | number | 是 | 指定保护的socketfd。 | +| callback | AsyncCallback\ | 是 | 回调函数，成功时，err为undefined，失败返回错误码错误信息。 | + +**错误码：** + +以下错误码的详细介绍参见[VPN错误码](../errorcodes/errorcode-net-vpn)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2100003 | System internal error. | +| 2203004 | Invalid socket file descriptor. | + +**示例：** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + let tunnelfd = 0 + tcp.bind({ + address: "0.0.0.0", + family: 1, + port: 0 + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd().then((data) => { + console.info("tunenlfd: " + data); + tunnelfd = data + }) + VpnConnection.protect(tunnelfd, (error, data) => { + console.info(JSON.stringify(error)); + console.info(JSON.stringify(data)); + }) +``` + +## VpnConnection.protect10+ + +protect(socketFd: number): Promise; + +保护套接字不受VPN连接。经过保护后，通过此套接字发送的数据将直接进入底层网络，因此其流量不会通过VPN转发, 使用Promise方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.MANAGE_VPN + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| socketFd | number | 是 | 指定保护的socketfd。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果，失败返回错误码错误信息。 | + +**错误码：** + +以下错误码的详细介绍参见[VPN错误码](../errorcodes/errorcode-net-vpn)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2100003 | System internal error. | +| 2203004 | Invalid socket file descriptor. | + +**示例：** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + let tunnelfd = 0 + tcp.bind({ + address: "0.0.0.0", + family: 1, + port: 0 + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd().then((data) => { + console.info("tunenlfd: " + data); + tunnelfd = data + }) + VpnConnection.protect(tunnelfd).then((data) => { + console.info("protect success" + JSON.stringify(data)) + }).catch(err => { + console.info("protect fail" + JSON.stringify(err)) + }) +``` + +## VpnConnection.destroy10+ + +destroy(callback: AsyncCallback\): void; + +销毁启动的VPN网络，使用callback方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.MANAGE_VPN + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback\ | 是 | 回调函数，成功时，err为undefined，失败返回错误码错误信息。 | + +**错误码：** + +以下错误码的详细介绍参见[VPN错误码](../errorcodes/errorcode-net-vpn)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2100003 | System internal error. | + +**示例：** + +```js + VpnConnection.destroy((error, data) => { + console.info(JSON.stringify(error)); + console.info(JSON.stringify(data)); + }) +``` + +## VpnConnection.destroy10+ + +destroy(): Promise; + +销毁启动的VPN网络，使用Promise方式作为异步方法。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.MANAGE_VPN + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回设定结果，失败返回错误码错误信息。 | + +**错误码：** + +以下错误码的详细介绍参见[VPN错误码](../errorcodes/errorcode-net-vpn)。 + +| 错误码ID | 错误信息 | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2100003 | System internal error. | + +**示例：** + +```js + VpnConnection.destroy().then((data) => { + console.info("destroy success" + JSON.stringify(data)) + }).catch(err => { + console.info("destroy fail" + JSON.stringify(err)) + }); +``` + +## VpnConfig10+ + +VPN配置参数。 + +**系统接口**：此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.NetManager.Vpn + +| 名称 | 类型 | 必填 | 说明 | +| ------- | ------ | -- |------------------------------ | +| addresses | Array | 是 | VPN虚拟网卡的IP地址。 | +| routes | Array | 否 | VPN虚拟网卡的路由信息。 | +| dnsAddresses | Array | 否 | DNS服务器地址信息。 | +| searchDomains | Array | 否 | DNS的搜索域列表。 | +| mtu | number | 否 | 最大传输单元MTU值(单位:字节)。 | +| isIPv4Accepted | boolean | 否 | 是否支持IPV4, 默认值为true。 | +| isIPv6Accepted | boolean | 否 | 是否支持IPV6, 默认值为flase。 || +| isLegacy | boolean | 否 | 是否支持内置VPN, 默认值为flase。 | +| isBlocking | boolean | 否 | 是否阻塞模式, 默认值为flase。 | +| trustedApplications | Array | 否 | 白名单信息, string类型表示的包名。 | +| blockedApplications | Array | 否 | 黑名单信息, string类型表示的包名。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-socket.md b/zh-cn/application-dev/reference/apis/js-apis-socket.md index e47fab1465..50c0a75098 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-socket.md +++ b/zh-cn/application-dev/reference/apis/js-apis-socket.md @@ -1235,6 +1235,87 @@ promise.then(() => { }); ``` +### getSocketFd10+ + +getSocketFd(callback: AsyncCallback\): void + +获取TCPSocket的文件描述符。使用callback方式作为异步方法。 + +> **说明：** +> bind或connect方法调用成功后，才可调用此方法。 + +**系统能力**：SystemCapability.Communication.NetStack + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------ | ---- | ---------- | +| callback | AsyncCallback\ | 是 | 回调函数，当成功获取fd时，返回tcpsocket的fd。 | + +**示例：** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + let tunnelfd = 0 + tcp.bind({ + address: "0.0.0.0", + family: 1, + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd((data) => { + console.info("tunenlfd: " + data); + tunnelfd = data + }) +``` +### getSocketFd10+ + +getSocketFd(): Promise\ + +获取TCPSocket的文件描述符。使用Promise方式作为异步方法。 + +> **说明：** +> bind或connect方法调用成功后，才可调用此方法。 + +**系统能力**：SystemCapability.Communication.NetStack + +**返回值：** + +| 类型 | 说明 | +| :----------------------------------------------- | :----------------------------------------- | +| Promise\ | 以Promise形式返回获取TCPSocket的文件描述符。 | + +**示例：** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + let tunnelfd = 0 + tcp.bind({ + address: "0.0.0.0", + family: 1, + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd().then((data) => { + console.info("tunenlfd: " + data); + tunnelfd = data + }) +``` + ### setExtraOptions7+ setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback\): void diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-net-vpn.md b/zh-cn/application-dev/reference/errorcodes/errorcode-net-vpn.md new file mode 100644 index 0000000000..797b14388e --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-net-vpn.md @@ -0,0 +1,61 @@ +# VPN错误码 + +> **说明：** +> +> 以下仅介绍本模块特有错误码，通用错误码请参考[通用错误码说明文档](errorcode-universal.md)。 + +## 2203001 VPN创建失败 + +**错误信息** + +VPN creation denied, please check the user type. + +**错误描述** + +VPN创建拒绝，请检测当前用户的类型。 + +**可能原因** + +用户的type不匹配, GUEST用户不能调用setUp接口。 + +**处理步骤** + +检查当前用户的类型。 + + +## 2203002 VPN已存在 + +**错误信息** + +VPN exist already, please execute destroy first. + +**错误描述** + +VPN已经存在，请先执行destory接口。 + +**可能原因** + +VPN已经被创建。 + +**处理步骤** + +先执行destory接口，再调用该接口。 + + +## 2203004 无效描述符 + +**错误信息** + +Invalid socket file descriptor. + +**错误描述** + +无效的文件描述符。 + +**可能原因** + +tcp链路建立失败。 + +**处理步骤** + +检查tcp链路是否建立成功。 \ No newline at end of file -- GitLab