A virtual private network (VPN) is a dedicated network established on a public network. On a VPN, the connection between any two nodes does not have an end-to-end physical link required by the traditional private network. Instead, user data is transmitted over a logical link because a VPN is a logical network deployed over the network platform (such as the Internet) provided by the public network service provider.
> **NOTE**
> To maximize the application running efficiency, most API calls are called asynchronously in callback or promise mode. The following code examples use the callback mode. For details about the APIs, see [Traffic Management](../reference/apis/js-apis-net-vpn.md).
The following describes the development procedure specific to each application scenario.
## Available APIs
For the complete list of APIs and example code, see [VPN Management](../reference/apis/js-apis-net-vpn.md).
| Type| API| Description|
| ---- | ---- | ---- |
| ohos.net.vpn | setUp(config: VpnConfig, callback: AsyncCallback\<number\>): void | Establishes a VPN. This API uses an asynchronous callback to return the result.|
| ohos.net.vpn | protect(socketFd: number, callback: AsyncCallback\<void\>): void | Enables VPN tunnel protection. This API uses an asynchronous callback to return the result.|
| ohos.net.vpn | destroy(callback: AsyncCallback\<void\>): void | Destroys a VPN. This API uses an asynchronous callback to return the result.|
## Starting a VPN
1. Establish a VPN tunnel. The following uses the UDP tunnel as an example.
2. Enable protection for the UDP tunnel.
3. Establish a VPN.
4. Process data of the virtual network interface card (vNIC), such as reading or writing data.
5. Destroy the VPN.
This example shows how to develop an application using native C++ code. For details, see [Simple Native C++ Example (ArkTS) (API9)] (https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/NativeTemplateDemo).
The sample application consists of two parts: JS code and C++ code.
## JS Code
The JS code is used to implement the service logic, such as creating a tunnel, establishing a VPN, enabling VPN protection, and destroying a VPN.
The **componentUtils** module provides API for obtaining the coordinates and size of the drawing area of a component.
> **NOTE**
>
> The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.
>
> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see [UIContext](./js-apis-arkui-UIContext.md#uicontext).
>
> Since API version 10, you can use the [getComponentUtils](./js-apis-arkui-UIContext.md#getcomponentutils) API in **UIContext** to obtain the **ComponentUtils** object associated with the current UI context. For this API to work correctly, call it after the notification indicating completion of component layout is received through [@ohos.arkui.inspector (layout callback)](js-apis-arkui-inspector.md).
| [ComponentInfo](#componentinfo) | **ComponentInfo** object, which provides the size, position, translation, scaling, rotation, and affine matrix information of the component.|
| localOffset | [Offset](#offset) | Yes| Offset of the component relative to the parent component. |
| windowOffset | [Offset](#offset) | Yes| Offset of the component relative to the window. |
| screenOffset | [Offset](#offset) | Yes| Offset of the component relative to the screen. |
| translate | [TranslateResult](#translateresult) | Yes| Translation of the component. |
| scale | [ScaleResult](#scaleresult) | Yes| Scaling of the component. |
| rotate | [RotateResult](#rotateresult) | Yes| Rotation of the component. |
| transform | [Matrix4Result](#matrix4result) | Yes| Affine matrix of the component, which is a 4x4 matrix object created based on the input parameter. |
| [number,number,number,number,<br>number,number,number,number,<br>number,number,number,number,<br>number,number,number,number] | A number array whose length is 16 (4 x 4). For details, see **4 x 4 matrix description**.|
The **dragInteraction** module provides the APIs to enable and disable listening for dragging status changes.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> - The APIs provided by this module are system APIs.
| type | string | Yes | Event type. This field has a fixed value of **drag**.|
| callback | Callback<[DragState](#dragstate)> | No | Callback to be unregistered. If this parameter is not specified, all callbacks registered by the current application will be unregistered.|
The **vpn** module implements virtual private network (VPN) management, such as starting and stopping a VPN.
> **NOTE**
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Defines a VPN connection object. Before calling **VpnConnection** APIs, you need to create a VPN connection object by calling [vpn.createVpnConnection](#vpncreatevpnconnection).
| callback | AsyncCallback\<number\> | Yes | Callback used to return the result. If a VPN is created successfully, **error** is **undefined** and **data** is the file descriptor of the vNIC. Otherwise, **error** is an error object.|
**Error codes**
For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md).
| ID| Error Message |
| ------- | ----------------------------- |
| 201 | Permission denied. |
| 202 | Non-system applications use system APIs. |
| 401 | Parameter error. |
| 2200001 | Invalid parameter value. |
| 2200002 | Operation failed. Cannot connect to service. |
| 2200003 | System internal error. |
| 2203001 | VPN creation denied, please check the user type. |
| Promise\<number\> | The obtaining result is returned in Promise format. The file descriptor fd of the specified virtual network adapter is returned.|
**Error codes**
For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md).
| ID| Error Message |
| ------- | ----------------------------- |
| 201 | Permission denied. |
| 202 | Non-system applications use system APIs. |
| 401 | Parameter error. |
| 2200001 | Invalid parameter value. |
| 2200002 | Operation failed. Cannot connect to service. |
| 2200003 | System internal error. |
| 2203001 | VPN creation denied, please check the user type. |
Protects sockets against a VPN connection. The data sent through sockets is directly transmitted over the physical network and therefore the traffic does not traverse through the VPN. This API uses an asynchronous callback to return the result.
| socketFd | number | Yes | Socket file descriptor. It can be obtained through [getSocketFd](js-apis-socket.md#getsocketfd10). |
| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the operation is successful, **error** is **undefined**. If the operation fails, an error message is returned.|
**Error codes**
For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md).
| ID| Error Message |
| ------- | ----------------------------- |
| 201 | Permission denied. |
| 202 | Non-system applications use system APIs. |
| 401 | Parameter error. |
| 2200001 | Invalid parameter value. |
| 2200002 | Operation failed. Cannot connect to service. |
| 2200003 | System internal error. |
| 2203004 | Invalid socket file descriptor. |
**Example**
```js
importsocketfrom"@ohos.net.socket";
vartcp=socket.constructTCPSocketInstance();
tcp.bind({
address:"0.0.0.0",
family:1
})
letconnectAddress={
address:"192.168.1.11",
port:8888,
family:1
};
tcp.connect({
address:connectAddress,timeout:6000
})
tcp.getSocketFd().then((tunnelfd)=>{
console.info("tunenlfd: "+tunnelfd);
VpnConnection.protect(tunnelfd,(error)=>{
console.info(JSON.stringify(error));
})
})
```
### protect
protect(socketFd: number): Promise\<void\>
Protects sockets against a VPN connection. The data sent through sockets is directly transmitted over the physical network and therefore traffic does not traverse through the VPN. This API uses a promise to return the result.
| Promise\<void\> | Promise used to return the result. If the operation is successful, the operation result is returned. If the operation fails, an error message is returned.|
**Error codes**
For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md).
| ID| Error Message |
| ------- | ----------------------------- |
| 201 | Permission denied. |
| 202 | Non-system applications use system APIs. |
| 401 | Parameter error. |
| 2200001 | Invalid parameter value. |
| 2200002 | Operation failed. Cannot connect to service. |
| 2200003 | System internal error. |
| 2203004 | Invalid socket file descriptor. |
**Example**
```js
importsocketfrom"@ohos.net.socket";
vartcp=socket.constructTCPSocketInstance();
tcp.bind({
address:"0.0.0.0",
family:1
})
letconnectAddress={
address:"192.168.1.11",
port:8888,
family:1
};
tcp.connect({
address:connectAddress,timeout:6000
})
tcp.getSocketFd().then((tunnelfd)=>{
console.info("tunenlfd: "+tunnelfd);
VpnConnection.protect(tunnelfd).then(()=>{
console.info("protect success.")
}).catch(err=>{
console.info("protect fail"+JSON.stringify(err))
})
})
```
### destroy
destroy(callback: AsyncCallback\<void\>): void
Destroys a VPN. This API uses an asynchronous callback to return the result.
| callback | AsyncCallback\<void\> | Yes | Callback used to return the result. If the operation is successful, **error** is **undefined**. If the operation fails, an error message is returned.|
**Error codes**
For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md).
| ID| Error Message |
| ------- | ----------------------------- |
| 201 | Permission denied. |
| 202 | Non-system applications use system APIs. |
| 401 | Parameter error. |
| 2200002 | Operation failed. Cannot connect to service. |
| 2200003 | System internal error. |
**Example**
```js
VpnConnection.destroy((error)=>{
console.info(JSON.stringify(error));
})
```
### destroy
destroy(): Promise\<void\>
Destroys a VPN. This API uses a promise to return the result.
| Promise\<void\> | Promise used to return the result. If the operation is successful, the operation result is returned. If the operation fails, an error message is returned.|
**Error codes**
For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md).
| ID| Error Message |
| ------- | ----------------------------- |
| 201 | Permission denied. |
| 202 | Non-system applications use system APIs. |
| 2200002 | Operation failed. Cannot connect to service. |