Skip to content

Commit 80a0434

Browse files
ccnndeccnnde
committed
📃 docs: add Reference
1 parent e640649 commit 80a0434

File tree

4 files changed

+258
-244
lines changed

4 files changed

+258
-244
lines changed

‎README.md‎

Lines changed: 1 addition & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -189,128 +189,7 @@ const App = () => {
189189
export default App;
190190
```
191191

192-
## Methods
193-
194-
| Name | iOS | Android | Parameters | Return | Description |
195-
| ---------------------- | --- | ------- | -------------------------------------------------------- | ------- | ------------------------------------------- |
196-
| connect | ✅ | ✅ | options: [VpnOptions](#vpnoptions) | promise | Connecting to OpenVPN |
197-
| disconnect | ✅ | ✅ | none | promise | Close the OpenVPN connection |
198-
| observeState | ✅ | ❌ | none | promise | Listening for VPN status |
199-
| stopObserveState | ✅ | ❌ | none | promise | Stop listening to VPN status |
200-
| addVpnStateListener | ✅ | ✅ | callback: (e: [VpnEventParams](#vpneventparams)) => void | void | Add VPN status change event listener |
201-
| removeVpnStateListener | ✅ | ✅ | none | void | Remove the VPN status change event listener |
202-
203-
## Properties
204-
205-
| Name | Value | Description |
206-
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
207-
| VpnState | VPN_STATE_DISCONNECTED = 0 <br/> VPN_STATE_CONNECTING = 1 <br/> VPN_STATE_CONNECTED = 2 <br/> VPN_STATE_DISCONNECTING = 3 <br/> VPN_OTHER_STATE = 4 <br/> | VPN Current Status |
208-
| CompatMode | MODERN_DEFAULTS = 0 <br/> OVPN_TWO_FIVE_PEER = 1 <br/> OVPN_TWO_FOUR_PEER = 2 <br/> OVPN_TWO_THREE_PEER = 3 <br/> | OpenVPN Compatibility Mode(**Android only**) |
209-
210-
## Types
211-
212-
### VpnOptions
213-
214-
```ts
215-
interface VpnOptions {
216-
remoteAddress?: string;
217-
ovpnString?: string;
218-
ovpnFileName?: string;
219-
assetsPath?: string;
220-
notificationTitle?: string;
221-
compatMode?: RNSimpleOpenvpn.CompatMode;
222-
useLegacyProvider?: boolean;
223-
providerBundleIdentifier: string;
224-
localizedDescription?: string;
225-
}
226-
```
227-
228-
#### remoteAddress
229-
230-
VPN server address, the format is `<ip> <port>`, use the address in the configuration file of `xxx.ovpn` when it is not passed in
231-
232-
#### ovpnString
233-
234-
The string format of the content of the OpenVPN configuration file. When it is not passed in or an empty string `''` is passed, the module will look for the `xxx.ovpn` configuration file string format
235-
236-
String format reference [example.ovpn](example/android/app/src/main/assets/Japan.ovpn)
237-
238-
#### ovpnFileName
239-
240-
The name of the OpenVPN configuration file, without extensions, using the default name `client` if not passed in
241-
242-
#### assetsPath
243-
244-
**Android only**，the path to the OpenVPN configuration file under `android/app/src/main/assets/`
245-
246-
- `assetsPath` is `''` when not passed in, the file path is `assets/xxx.ovpn`
247-
- When passing in a path, such as `'ovpn/'`, the file path is `assets/ovpn/xxx.ovpn`
248-
249-
#### notificationTitle
250-
251-
**Android only**，the title of the notification, using the default value `OpenVPN` if not passed in
252-
253-
#### compatMode
254-
255-
**Android only**，[OpenVPN compatibility mode](#properties), using the default value `MODERN_DEFAULTS` if not passed in
256-
257-
| Mode | Description |
258-
| ------------------- | ----------------------------- |
259-
| MODERN_DEFAULTS | Modern defaults |
260-
| OVPN_TWO_FIVE_PEER | OpenVPN 2.5.x peers |
261-
| OVPN_TWO_FOUR_PEER | OpenVPN 2.4.x peers |
262-
| OVPN_TWO_THREE_PEER | OpenVPN 2.3.x and older peers |
263-
264-
#### useLegacyProvider
265-
266-
**Android only**，load OpenSSL legacy provider or not, using the default value `false` if not passed in
267-
268-
#### providerBundleIdentifier
269-
270-
**iOS only**，the bundle identifier of the Network Extension target
271-
272-
#### localizedDescription
273-
274-
**iOS only**，the localized description name of the app in Settings -> VPN. If it is not passed in, the default name `RNSimpleOpenvpn` will be used
275-
276-
### VpnEventParams
277-
278-
```ts
279-
interface VpnEventParams {
280-
state: RNSimpleOpenvpn.VpnState; // VPN Status
281-
message: string; // VPN Status Related Messages
282-
level?: string; // Description of the connection status provided by the Android OpenVPN library
283-
}
284-
```
285-
286-
## Attention
287-
288-
### `xxx.ovpn` configuration file
289-
290-
If you don’t use [ovpnString](#ovpnstring), don’t forget to add the configuration file to your project
291-
292-
- The Android path is `android/app/src/main/assets/`，create a new `assets` folder if you don't have one
293-
- The iOS path is the main bundle, just drag and drop the file into the project
294-
295-
![ios-ovpn-file](.github/images/ios-ovpn-file.png)
296-
297-
The format of the line where `remote` is located in the file must be of the following form
298-
299-
```text
300-
...
301-
remote <IP address> <port>
302-
...
303-
```
304-
305-
If you don't need to dynamically modify the `remote` address in the configuration file, the same configuration file is used for Android and iOS, and the `remoteAddress` of `options` can be left out
306-
307-
However, if you need to dynamically change the `remote` address in the configuration file, the iOS configuration file needs to comment out the line where `remote` is located (below) and always pass `remoteAddress` for `options`
308-
309-
```text
310-
...
311-
;remote <IP address> <port>>
312-
...
313-
```
192+
For more, read the [API Reference](docs/Reference.md)
314193

315194
## OpenVPN library
316195

‎README.zh-CN.md‎

Lines changed: 1 addition & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -189,128 +189,7 @@ const App = () => {
189189
export default App;
190190
```
191191

192-
## 方法
193-
194-
| 名称 | iOS | Android | 参数 | 返回值 | 描述 |
195-
| ---------------------- | --- | ------- | -------------------------------------------------------- | ------- | ------------------------- |
196-
| connect | ✅ | ✅ | options: [VpnOptions](#vpnoptions) | promise | 连接 OpenVPN |
197-
| disconnect | ✅ | ✅ | 无 | promise | 关闭 OpenVPN 连接 |
198-
| observeState | ✅ | ❌ | 无 | promise | 监听 VPN 状态 |
199-
| stopObserveState | ✅ | ❌ | 无 | promise | 停止监听 VPN 状态 |
200-
| addVpnStateListener | ✅ | ✅ | callback: (e: [VpnEventParams](#vpneventparams)) => void | void | 添加 VPN 状态变更事件监听 |
201-
| removeVpnStateListener | ✅ | ✅ | 无 | void | 移除 VPN 状态变更事件监听 |
202-
203-
## 属性
204-
205-
| 名称 | 值 | 描述 |
206-
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
207-
| VpnState | VPN_STATE_DISCONNECTED = 0 <br/> VPN_STATE_CONNECTING = 1 <br/> VPN_STATE_CONNECTED = 2 <br/> VPN_STATE_DISCONNECTING = 3 <br/> VPN_OTHER_STATE = 4 <br/> | VPN 当前状态 |
208-
| CompatMode | MODERN_DEFAULTS = 0 <br/> OVPN_TWO_FIVE_PEER = 1 <br/> OVPN_TWO_FOUR_PEER = 2 <br/> OVPN_TWO_THREE_PEER = 3 <br> | OpenVPN 兼容模式(**Android only**) |
209-
210-
## 类型
211-
212-
### VpnOptions
213-
214-
```ts
215-
interface VpnOptions {
216-
remoteAddress?: string;
217-
ovpnString?: string;
218-
ovpnFileName?: string;
219-
assetsPath?: string;
220-
notificationTitle?: string;
221-
compatMode?: RNSimpleOpenvpn.CompatMode;
222-
useLegacyProvider?: boolean;
223-
providerBundleIdentifier: string;
224-
localizedDescription?: string;
225-
}
226-
```
227-
228-
#### remoteAddress
229-
230-
VPN 服务端地址，格式为 `<ip> <port>`，未传入时使用 `xxx.ovpn` 配置文件中的地址
231-
232-
#### ovpnString
233-
234-
OpenVPN 配置文件内容的字符串形式，未传入时或传递空字符串 `''`，模块将寻找 `xxx.ovpn` 配置文件
235-
236-
字符串格式参考 [example.ovpn](example/android/app/src/main/assets/Japan.ovpn)
237-
238-
#### ovpnFileName
239-
240-
OpenVPN 配置文件的名称，不含扩展名，未传入时使用默认名称 `client`
241-
242-
#### assetsPath
243-
244-
**Android 专用**，OpenVPN 配置文件在 `android/app/src/main/assets/` 下的路径
245-
246-
- 未传入时 `assetsPath` 为 `''`，文件路径为 `assets/xxx.ovpn`
247-
- 传入路径时，比如 `'ovpn/'`，文件路径为 `assets/ovpn/xxx.ovpn`
248-
249-
#### notificationTitle
250-
251-
**Android 专用**，通知的标题，未传入时使用默认值 `OpenVPN`
252-
253-
#### compatMode
254-
255-
**Android 专用**，[OpenVPN 兼容模式](#properties)，未传入时使用默认值 `MODERN_DEFAULTS`
256-
257-
| 模式 | 描述 |
258-
| ------------------- | ----------------------------- |
259-
| MODERN_DEFAULTS | Modern defaults |
260-
| OVPN_TWO_FIVE_PEER | OpenVPN 2.5.x peers |
261-
| OVPN_TWO_FOUR_PEER | OpenVPN 2.4.x peers |
262-
| OVPN_TWO_THREE_PEER | OpenVPN 2.3.x and older peers |
263-
264-
#### useLegacyProvider
265-
266-
**Android 专用**，是否加载 OpenSSL legacy provider，未传入时使用默认值 `false`
267-
268-
#### providerBundleIdentifier
269-
270-
**iOS 专用**，Network Extension target 的 bundle identifier
271-
272-
#### localizedDescription
273-
274-
**iOS 专用**，应用在设置 -> VPN 中的本地化描述名称，未传入时使用默认名称 `RNSimpleOpenvpn`
275-
276-
### VpnEventParams
277-
278-
```ts
279-
interface VpnEventParams {
280-
state: RNSimpleOpenvpn.VpnState; // VPN 状态
281-
message: string; // VPN 状态相关的消息
282-
level?: string; // Android OpenVPN 库提供的连接状态描述
283-
}
284-
```
285-
286-
## 注意
287-
288-
### `xxx.ovpn` 配置文件
289-
290-
如果你不使用 [ovpnString](#ovpnstring)，不要忘记将配置文件添加你的项目中
291-
292-
- Android 路径 `android/app/src/main/assets/`，没有 `assets` 文件夹就新建一个
293-
- iOS 路径为 main bundle，将文件拖拽到工程下即可
294-
295-
![ios-ovpn-file](.github/images/ios-ovpn-file.png)
296-
297-
文件中 `remote` 所在行的格式必须如下形式
298-
299-
```text
300-
...
301-
remote <IP address> <port>
302-
...
303-
```
304-
305-
如果你不需要动态修改配置文件中的 `remote` 地址，则 Android 和 iOS 使用相同的配置文件，`options` 的 `remoteAddress` 可不传
306-
307-
但是，如果你需要动态修改配置文件中的 `remote` 地址，则 iOS 端配置文件需要注释掉 `remote` 所在行（如下），且始终传递 `options` 的 `remoteAddress`
308-
309-
```text
310-
...
311-
;remote <IP address> <port>>
312-
...
313-
```
192+
更多内容请查看 [API Reference](docs/Reference.zh-CN.md)
314193

315194
## OpenVPN library
316195

‎docs/Reference.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# React Native Simple OpenVPN API Reference
2+
3+
English | [简体中文](./Reference.zh-CN.md)
4+
5+
This document lays out the current public properties and methods for the React Native Simple OpenVPN
6+
7+
## Methods
8+
9+
| Name | iOS | Android | Parameters | Return | Description |
10+
| ---------------------- | --- | ------- | -------------------------------------------------------- | ------- | ------------------------------------------- |
11+
| connect | ✅ | ✅ | options: [VpnOptions](#vpnoptions) | promise | Connecting to OpenVPN |
12+
| disconnect | ✅ | ✅ | none | promise | Close the OpenVPN connection |
13+
| observeState | ✅ | ❌ | none | promise | Listening for VPN status |
14+
| stopObserveState | ✅ | ❌ | none | promise | Stop listening to VPN status |
15+
| addVpnStateListener | ✅ | ✅ | callback: (e: [VpnEventParams](#vpneventparams)) => void | void | Add VPN status change event listener |
16+
| removeVpnStateListener | ✅ | ✅ | none | void | Remove the VPN status change event listener |
17+
18+
## Properties
19+
20+
| Name | Value | Description |
21+
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
22+
| VpnState | VPN_STATE_DISCONNECTED = 0 <br/> VPN_STATE_CONNECTING = 1 <br/> VPN_STATE_CONNECTED = 2 <br/> VPN_STATE_DISCONNECTING = 3 <br/> VPN_OTHER_STATE = 4 <br/> | VPN Current Status |
23+
| CompatMode | MODERN_DEFAULTS = 0 <br/> OVPN_TWO_FIVE_PEER = 1 <br/> OVPN_TWO_FOUR_PEER = 2 <br/> OVPN_TWO_THREE_PEER = 3 <br/> | OpenVPN Compatibility Mode(**Android only**) |
24+
25+
## Types
26+
27+
### VpnOptions
28+
29+
```ts
30+
interface VpnOptions {
31+
remoteAddress?: string;
32+
ovpnString?: string;
33+
ovpnFileName?: string;
34+
assetsPath?: string;
35+
notificationTitle?: string;
36+
compatMode?: RNSimpleOpenvpn.CompatMode;
37+
useLegacyProvider?: boolean;
38+
providerBundleIdentifier: string;
39+
localizedDescription?: string;
40+
}
41+
```
42+
43+
#### remoteAddress
44+
45+
VPN server address, the format is `<ip> <port>`, use the address in the configuration file of `xxx.ovpn` when it is not passed in
46+
47+
#### ovpnString
48+
49+
The string format of the content of the OpenVPN configuration file. When it is not passed in or an empty string `''` is passed, the module will look for the `xxx.ovpn` configuration file string format
50+
51+
String format reference [example.ovpn](../example/android/app/src/main/assets/Japan.ovpn)
52+
53+
#### ovpnFileName
54+
55+
The name of the OpenVPN configuration file, without extensions, using the default name `client` if not passed in
56+
57+
#### assetsPath
58+
59+
**Android only**，the path to the OpenVPN configuration file under `android/app/src/main/assets/`
60+
61+
- `assetsPath` is `''` when not passed in, the file path is `assets/xxx.ovpn`
62+
- When passing in a path, such as `'ovpn/'`, the file path is `assets/ovpn/xxx.ovpn`
63+
64+
#### notificationTitle
65+
66+
**Android only**，the title of the notification, using the default value `OpenVPN` if not passed in
67+
68+
#### compatMode
69+
70+
**Android only**，[OpenVPN compatibility mode](#properties), using the default value `MODERN_DEFAULTS` if not passed in
71+
72+
| Mode | Description |
73+
| ------------------- | ----------------------------- |
74+
| MODERN_DEFAULTS | Modern defaults |
75+
| OVPN_TWO_FIVE_PEER | OpenVPN 2.5.x peers |
76+
| OVPN_TWO_FOUR_PEER | OpenVPN 2.4.x peers |
77+
| OVPN_TWO_THREE_PEER | OpenVPN 2.3.x and older peers |
78+
79+
#### useLegacyProvider
80+
81+
**Android only**，load OpenSSL legacy provider or not, using the default value `false` if not passed in
82+
83+
#### providerBundleIdentifier
84+
85+
**iOS only**，the bundle identifier of the Network Extension target
86+
87+
#### localizedDescription
88+
89+
**iOS only**，the localized description name of the app in Settings -> VPN. If it is not passed in, the default name `RNSimpleOpenvpn` will be used
90+
91+
### VpnEventParams
92+
93+
```ts
94+
interface VpnEventParams {
95+
state: RNSimpleOpenvpn.VpnState; // VPN Status
96+
message: string; // VPN Status Related Messages
97+
level?: string; // Description of the connection status provided by the Android OpenVPN library
98+
}
99+
```
100+
101+
## Attention
102+
103+
### `xxx.ovpn` configuration file
104+
105+
If you don’t use [ovpnString](#ovpnstring), don’t forget to add the configuration file to your project
106+
107+
- The Android path is `android/app/src/main/assets/`，create a new `assets` folder if you don't have one
108+
- The iOS path is the main bundle, just drag and drop the file into the project
109+
110+
![ios-ovpn-file](../.github/images/ios-ovpn-file.png)
111+
112+
The format of the line where `remote` is located in the file must be of the following form
113+
114+
```text
115+
...
116+
remote <IP address> <port>
117+
...
118+
```
119+
120+
If you don't need to dynamically modify the `remote` address in the configuration file, the same configuration file is used for Android and iOS, and the `remoteAddress` of `options` can be left out
121+
122+
However, if you need to dynamically change the `remote` address in the configuration file, the iOS configuration file needs to comment out the line where `remote` is located (below) and always pass `remoteAddress` for `options`
123+
124+
```text
125+
...
126+
;remote <IP address> <port>>
127+
...
128+
```

0 commit comments

Comments
 (0)