### Simple Proxy Setup

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/quick-start.md

This example demonstrates how to set up a local SOCKS5 server and then create a TUN interface to tunnel traffic through it. It includes steps for configuring the TUN interface, setting IP addresses, and routing rules. Finally, it shows how to test the setup with a curl command.

```bash
# Terminal 1: Start a local SOCKS5 server (using dante-server or similar)
# Edit /etc/sockd.conf, then:
# sudo sockd -D

# Terminal 2: Create TUN and tunnel
sudo ip tuntap add dev tun0 mode tun
sudo ip addr add 198.18.0.1/24 dev tun0
sudo ip link set tun0 up
sudo sysctl -w net.ipv4.conf.all.rp_filter=0
sudo sysctl -w net.ipv4.conf.tun0.rp_filter=0
sudo ./bin/hev-socks5-tunnel config.yml

# Terminal 3: Test routing
sudo ip route add default dev tun0 table 20
sudo ip rule add lookup 20 pref 20
curl https://example.com
```

--------------------------------

### Create Wintun Adapters

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/third-part/wintun/README.md

Demonstrates how to create multiple Wintun adapters with different names and GUIDs. Ensure you have unique GUIDs for each adapter.

```C
WINTUN_ADAPTER_HANDLE Adapter1 = WintunCreateAdapter(L"OfficeNet", L"Wintun", &SomeFixedGUID1);
WINTUN_ADAPTER_HANDLE Adapter2 = WintunCreateAdapter(L"HomeNet", L"Wintun", &SomeFixedGUID2);
WINTUN_ADAPTER_HANDLE Adapter3 = WintunCreateAdapter(L"Data Center", L"Wintun", &SomeFixedGUID3);
```

--------------------------------

### Start SOCKS5 Tunnel Service Example

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/jni-reference.md

Example of starting the SOCKS5 tunnel service within an Android Activity. It obtains the TUN file descriptor and calls the native start method.

```java
public class ProxyService extends Service {
    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        try {
            // Get TUN file descriptor
            ParcelFileDescriptor tunFd = createTunDevice();
            int fd = tunFd.detachFd();
            
            // Start tunnel
            String configPath = "/data/local/tmp/config.yml";
            nativeStartService(configPath, fd);
            
            return Service.START_STICKY;
        } catch (Exception e) {
            Log.e(TAG, "Failed to start service", e);
            return Service.START_NOT_STICKY;
        }
    }
    
    private native void nativeStartService(String path, int fd);
}
```

--------------------------------

### Start SOCKS5 Tunnel from File

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-main.md

Starts and runs the SOCKS5 tunnel using a configuration file. Blocks until quit is called or an error occurs. Ensure the tunnel file descriptor is valid.

```c
int fd = open("/dev/net/tun", O_RDWR);
if (fd < 0) {
    perror("Failed to open TUN device");
    return -1;
}

int ret = hev_socks5_tunnel_main("config.yml", fd);
if (ret != 0) {
    fprintf(stderr, "Tunnel failed with code: %d\n", ret);
    close(fd);
    return ret;
}
return 0;
```

--------------------------------

### Example Log Output

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Provides concrete examples of log messages as they would appear in the output, demonstrating different log levels and their associated messages.

```text
2025-01-15 10:23:45.123 [INFO] Tunnel started on interface tun0
2025-01-15 10:23:45.124 [WARN] High memory usage detected
2025-01-15 10:23:45.125 [ERROR] Connection failed: timeout
```

--------------------------------

### Start SOCKS5 Tunnel from File

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Starts the SOCKS5 tunnel using a configuration file path. This function blocks until the tunnel is quit or an error occurs.

```c
/**
 * hev_socks5_tunnel_main_from_file:
 * @config_path: config file path
 * @tun_fd: tunnel file descriptor
 *
 * Start and run the socks5 tunnel, this function will blocks until the
 * hev_socks5_tunnel_quit is called or an error occurs.
 *
 * Returns: returns zero on successful, otherwise returns -1.
 *
 * Since: 2.6.7
 */
int hev_socks5_tunnel_main_from_file (const char *config_path, int tun_fd);
```

--------------------------------

### Start SOCKS5 Tunnel from String

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Starts the SOCKS5 tunnel using a configuration string. This function blocks until the tunnel is quit or an error occurs.

```c
/**
 * hev_socks5_tunnel_main_from_str:
 * @config_str: string config
 * @config_len: the byte length of string config
 * @tun_fd: tunnel file descriptor
 *
 * Start and run the socks5 tunnel, this function will blocks until the
 * hev_socks5_tunnel_quit is called or an error occurs.
 *
 * Returns: returns zero on successful, otherwise returns -1.
 *
 * Since: 2.6.7
 */
int hev_socks5_tunnel_main_from_str (const unsigned char *config_str,
                                     unsigned int config_len, int tun_fd);
```

--------------------------------

### Activity Usage for Starting and Stopping the Proxy Service

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/jni-reference.md

Example methods within an Android `AppCompatActivity` to start and stop the `ProxyService`. It demonstrates how to create an Intent and pass necessary data like the configuration path.

```java
public class MainActivity extends AppCompatActivity {
    private void startProxy() {
        Intent intent = new Intent(this, ProxyService.class);
        intent.putExtra("config", "/data/local/tmp/config.yml");
        startService(intent);
    }
    
    private void stopProxy() {
        Intent intent = new Intent(this, ProxyService.class);
        stopService(intent);
    }
}
```

--------------------------------

### Start Tunnel

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Opens a TUN device and starts the socks5 tunnel. Requires root privileges for /dev/net/tun.

```c
int fd = open("/dev/net/tun", O_RDWR);
hev_socks5_tunnel_main("config.yml", fd);
```

--------------------------------

### Enable Logging

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Initializes the logger to INFO level and directs output to stderr. Logs a starting message.

```c
hev_logger_init(HEV_LOGGER_INFO, "stderr");
LOG_I("Starting...");
```

--------------------------------

### Run xjasonlyu-tun2socks

Source: https://github.com/heiher/hev-socks5-tunnel/wiki/Benchmarks

Command to start the xjasonlyu-tun2socks tool with a specified TUN device, MTU, and SOCKS5 proxy.

```bash
tun2socks-linux-amd64 -device tun0 -mtu 8500 -proxy socks5://192.168.1.1:1080
```

--------------------------------

### Wintun Adapter Creation

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/third-part/wintun/README.md

Demonstrates how to create Wintun adapters with specified names, types, and GUIDs.

```APIDOC
## WintunCreateAdapter

### Description
Creates a Wintun network adapter.

### Parameters
- **AdapterName** (LPCWSTR) - The name of the adapter (e.g., "OfficeNet").
- **AdapterType** (LPCWSTR) - The type of the adapter (e.g., "Wintun").
- **InstanceGuid** (const GUID*) - A unique GUID for the adapter instance.

### Returns
WINTUN_ADAPTER_HANDLE - A handle to the created adapter, or NULL on failure.

### Example
```C
WINTUN_ADAPTER_HANDLE Adapter1 = WintunCreateAdapter(L"OfficeNet", L"Wintun", &SomeFixedGUID1);
WINTUN_ADAPTER_HANDLE Adapter2 = WintunCreateAdapter(L"HomeNet", L"Wintun", &SomeFixedGUID2);
WINTUN_ADAPTER_HANDLE Adapter3 = WintunCreateAdapter(L"Data Center", L"Wintun", &SomeFixedGUID3);
```
```

--------------------------------

### Start SOCKS5 Tunnel from String

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-main.md

Loads SOCKS5 tunnel configuration from a memory buffer and starts the tunnel. Useful for embedded or dynamic configurations. Ensure the buffer contains valid YAML.

```c
const char config[] = 
    "tunnel:\n"
    "  name: tun0\n"
    "  mtu: 8500\n"
    "  ipv4: 198.18.0.1\n"
    "socks5:\n"
    "  address: 127.0.0.1\n"
    "  port: 1080\n";

int ret = hev_socks5_tunnel_main_from_str(
    (const unsigned char *)config, 
    strlen(config),
    tun_fd
);
```

--------------------------------

### hev-socks5-tunnel Configuration Example

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

An example YAML structure for configuring the hev-socks5-tunnel, including settings for the tunnel, SOCKS5 proxy, DNS mapping, and miscellaneous options.

```yaml
tunnel:
  name: tun0
  mtu: 8500
  ipv4: 198.18.0.1
  ipv6: 'fc00::1'

socks5:
  address: 127.0.0.1
  port: 1080
  username: user
  password: pass

mapdns:
  address: 198.18.0.2
  port: 53
  cache-size: 10000

misc:
  task-stack-size: 86016
  tcp-buffer-size: 65536
  max-session-count: 0
  log-level: warn
```

--------------------------------

### Initialize Configuration via Main Entry Point

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/configuration.md

Starts the SOCKS5 tunnel by loading configuration from a file and using a provided file descriptor for the network tunnel.

```c
int tun_fd = open("/dev/net/tun", O_RDWR);
int ret = hev_socks5_tunnel_main("/etc/config.yml", tun_fd);
```

--------------------------------

### Install and Configure hev-socks5-tunnel on OpenWrt

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Install the hev-socks5-tunnel package on OpenWrt using opkg. After installation, edit the configuration file and restart the service.

```sh
# Install package
opkg install hev-socks5-tunnel

# Edit /etc/config/hev-socks5-tunnel

# Restart service
/etc/init.d/hev-socks5-tunnel restart
```

--------------------------------

### WintunStartSession

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/third-part/wintun/README.md

Starts a new Wintun session on a given adapter with a specified ring capacity.

```APIDOC
## WintunStartSession()

### Description
Starts a Wintun session.

### Parameters
- **Adapter** (WINTUN_ADAPTER_HANDLE) - The adapter handle obtained from WintunOpenAdapter or WintunCreateAdapter.
- **Capacity** (DWORD) - The capacity of the ring buffer. Must be between WINTUN_MIN_RING_CAPACITY and WINTUN_MAX_RING_CAPACITY (inclusive) and must be a power of two.

### Returns
- **WINTUN_SESSION_HANDLE** - A handle to the Wintun session if successful. NULL if the function fails. Call GetLastError for extended error information.

### Remarks
Must be released with WintunEndSession.
```

--------------------------------

### Example Usage of LOG_W

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Demonstrates how to use the LOG_W macro to log a warning message with a formatted string.

```c
LOG_W("High memory usage: %zu MB", mem_mb);
```

--------------------------------

### Run hev-socks5-tunnel

Source: https://github.com/heiher/hev-socks5-tunnel/wiki/Benchmarks

Command to start the hev-socks5-tunnel with a specified configuration file. Assumes multi-queue is enabled for performance.

```bash
# Multi-queue on, 6 processes
hev-socks5-tunnel conf/main.yml
```

--------------------------------

### Wintun Session Management

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/third-part/wintun/README.md

Shows how to start a session on a Wintun adapter and allocate memory for sending packets.

```APIDOC
## WintunStartSession

### Description
Starts a session on a Wintun adapter.

### Parameters
- **Adapter** (WINTUN_ADAPTER_HANDLE) - The handle to the Wintun adapter.
- **Capacity** (UINT32) - The desired capacity of the session's ring buffer (e.g., 0x400000 for 64MiB).

### Returns
WINTUN_SESSION_HANDLE - A handle to the created session, or NULL on failure.

### Example
```C
WINTUN_SESSION_HANDLE Session = WintunStartSession(Adapter2, 0x400000);
```

## WintunAllocateSendPacket

### Description
Allocates a buffer within the Wintun session's ring for sending a packet.

### Parameters
- **Session** (WINTUN_SESSION_HANDLE) - The handle to the Wintun session.
- **PacketSize** (UINT32) - The size of the packet to be sent.

### Returns
BYTE* - A pointer to the allocated buffer, or NULL if allocation fails (e.g., due to buffer overflow).

### Example
```C
BYTE *OutgoingPacket = WintunAllocateSendPacket(Session, PacketDataSize);
if (OutgoingPacket)
{
    memcpy(OutgoingPacket, PacketData, PacketDataSize);
    WintunSendPacket(Session, OutgoingPacket);
}
else if (GetLastError() != ERROR_BUFFER_OVERFLOW) // Silently drop packets if the ring is full
    Log(L"Packet write failed");
```
```

--------------------------------

### Example Usage of LOG_I

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Demonstrates how to use the LOG_I macro to log an informational message with a formatted string.

```c
LOG_I("Tunnel started on interface %s", name);
```

--------------------------------

### Run sing-box

Source: https://github.com/heiher/hev-socks5-tunnel/wiki/Benchmarks

Command to start the sing-box with a specified configuration file for tun2socks functionality.

```bash
sing-box -c tun2socks.json run
```

--------------------------------

### Start and Control Tunnel Functions

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Functions to start a tunnel using a configuration path or string, and to gracefully shut down the tunnel and retrieve statistics.

```c
// Start tunnel
int hev_socks5_tunnel_main(const char *config_path, int tun_fd);
int hev_socks5_tunnel_main_from_str(const unsigned char *config, unsigned int len, int fd);

// Control tunnel
void hev_socks5_tunnel_quit(void);
void hev_socks5_tunnel_stats(size_t *tx_pkts, size_t *tx_bytes, 
                              size_t *rx_pkts, size_t *rx_bytes);
```

--------------------------------

### Start Wintun Session

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/third-part/wintun/README.md

Initiates a Wintun session for a given adapter with a specified ring buffer capacity. The capacity should be within the defined minimum and maximum limits.

```C
WINTUN_SESSION_HANDLE Session = WintunStartSession(Adapter2, 0x400000);
```

--------------------------------

### hev_socks5_tunnel_main_from_file

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Starts and runs the SOCKS5 tunnel using a configuration file. This function blocks until the tunnel is quit or an error occurs.

```APIDOC
## hev_socks5_tunnel_main_from_file

### Description
Starts and runs the SOCKS5 tunnel using a configuration file. This function blocks until `hev_socks5_tunnel_quit` is called or an error occurs.

### Parameters
#### Path Parameters
- **config_path** (const char *) - The path to the configuration file.
- **tun_fd** (int) - The file descriptor for the tunnel.

### Returns
- **int** - Returns zero on successful, otherwise returns -1.
```

--------------------------------

### Example Usage of LOG_D

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Demonstrates how to use the LOG_D macro to log a debug message with a formatted string.

```c
LOG_D("Processing packet of size %zu", size);
```

--------------------------------

### Declare TProxyStartService JNI Method

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/jni-reference.md

Declares the native method for starting the SOCKS5 tunnel service. Requires a configuration path and a file descriptor for the TUN device.

```java
public native void TProxyStartService(String configPath, int fd);
```

--------------------------------

### WintunCreateAdapter

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/third-part/wintun/README.md

Creates a new Wintun adapter with a specified name, tunnel type, and an optional GUID for deterministic NLA generation.

```APIDOC
## WintunCreateAdapter()

### Description
Creates a new Wintun adapter.

### Parameters
- **Name** (const WCHAR *) - The requested name of the adapter. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
- **TunnelType** (const WCHAR *) - Name of the adapter tunnel type. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
- **RequestedGUID** (const GUID *) - The GUID of the created network adapter. If NULL, the GUID is chosen randomly by the system.

### Returns
- **WINTUN_ADAPTER_HANDLE** - A handle to the created adapter if successful. NULL if the function fails. Call GetLastError for extended error information.

### Remarks
Must be released with WintunCloseAdapter.
```

--------------------------------

### Example Usage of LOG_E

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Demonstrates how to use the LOG_E macro to log an error message with a formatted string, including system error information.

```c
LOG_E("Socket error: %s", strerror(errno));
```

--------------------------------

### Log Message Output Format Example

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Illustrates the standard format for log messages, which includes timestamp, log level, and the message content.

```text
[TIMESTAMP] [LEVEL] message
```

--------------------------------

### Retrieve Tunnel Statistics Example

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/jni-reference.md

Example of retrieving and displaying tunnel interface statistics. It calls the native get stats method and formats the output.

```java
public class StatsActivity extends AppCompatActivity {
    private native long[] nativeGetStats();
    
    private void displayStats() {
        long[] stats = nativeGetStats();
        if (stats != null && stats.length == 4) {
            long txPackets = stats[0];
            long txBytes = stats[1];
            long rxPackets = stats[2];
            long rxBytes = stats[3];
            
            textView.setText(String.format(
                "TX: %d packets, %d bytes\nRX: %d packets, %d bytes",
                txPackets, txBytes, rxPackets, rxBytes
            ));
        }
    }
}
```

--------------------------------

### Initialize Configuration from File

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/configuration.md

Loads configuration settings from a specified YAML file. Returns -1 on failure.

```c
int ret = hev_config_init_from_file("/etc/hev-socks5-tunnel.yml");
```

--------------------------------

### Initialize Configuration from File (C)

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Initializes the configuration by loading settings from a specified YAML file. Returns an error code if the configuration cannot be loaded.

```c
int hev_config_init_from_file(const char *config_path);
// Initialize configuration
if (hev_config_init_from_file("config.yml") < 0) {
    fprintf(stderr, "Configuration error\n");
    return -1;
}
```

--------------------------------

### Configuration Utility Usage

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-utilities.md

Demonstrates how to retrieve configuration values for PID file, nofile limit, and SOCKS5 server settings, and apply them.

```c
// From hev_main.c
const char *pid_file = hev_config_get_misc_pid_file();
if (pid_file) {
    run_as_daemon(pid_file);
}

int nofile = hev_config_get_misc_limit_nofile();
set_limit_nofile(nofile);

HevConfigServer *srv = hev_config_get_socks5_server();
set_sock_mark(socket_fd, srv->mark);
set_sock_tcp_fastopen(socket_fd, srv->fastopen);
```

--------------------------------

### Initialize Configuration from Memory

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/configuration.md

Loads configuration settings from a YAML string. Returns -1 on failure.

```c
const char *yaml = "...";
int ret = hev_config_init_from_str((unsigned char *)yaml, strlen(yaml));
```

--------------------------------

### Initialize and Handle DNS Queries

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-mapped-dns.md

Demonstrates how to initialize the mapped DNS mapper with configuration values and set up a handler for incoming DNS queries. The handler processes A/AAAA records, forwards other types upstream, and manages potential errors. Cleanup of the mapper object is also shown.

```c
// Configuration-driven initialization
int net = hev_config_get_mapdns_network();
int mask = hev_config_get_mapdns_netmask();
int cache = hev_config_get_mapdns_cache_size();

HevMappedDNS *mapper = hev_mapped_dns_new(net, mask, cache);
if (!mapper) {
    LOG_E("Failed to create DNS mapper");
    return -1;
}

// DNS handler
void dns_receive_handler(uint8_t *query, int qlen) {
    uint8_t response[512];
    int rlen = hev_mapped_dns_handle(mapper, query, qlen, response, 512);
    
    if (rlen > 0) {
        send_response(response, rlen);
    } else if (rlen == 0) {
        // Not an A/AAAA query; forward to upstream
        forward_upstream(query, qlen);
    } else {
        // Error
        LOG_E("DNS handling failed");
    }
}

// Cleanup
hev_object_unref(HEV_OBJECT(mapper));
```

--------------------------------

### Stop SOCKS5 Tunnel Service Example

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/jni-reference.md

Example of stopping the SOCKS5 tunnel service, typically called during the service's onDestroy lifecycle method. It invokes the native stop method.

```java
@Override
public void onDestroy() {
    super.onDestroy();
    try {
        nativeStopService();
    } catch (Exception e) {
        Log.e(TAG, "Error stopping service", e);
    }
}

private native void nativeStopService();
```

--------------------------------

### TProxyStartService

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/jni-reference.md

Starts the SOCKS5 tunnel service. This method is non-blocking and loads configuration from a specified file path. The TUN device must be opened by the calling Java code.

```APIDOC
## TProxyStartService

### Description
Starts the SOCKS5 tunnel service in a background thread. This method is non-blocking and returns immediately after initiating the tunnel.

### Method
`native` (Java Native Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **configPath** (String) - Required - Path to the YAML configuration file for the tunnel.
- **fd** (int) - Required - File descriptor of the TUN device that has been opened by the Java code.

### Return Value
void

### Behavior
- Starts the tunnel in a background thread.
- Non-blocking; returns immediately.
- Tunnel runs until `TProxyStopService` is called.
- Configuration is loaded from the specified file path.
- The TUN device must be opened by the Java code prior to calling this method.

### Exceptions
- `OutOfMemoryError` if thread creation fails.
- May throw if the JNI environment is not available.

### Example (Android Activity)
```java
public class ProxyService extends Service {
    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        try {
            // Get TUN file descriptor
            ParcelFileDescriptor tunFd = createTunDevice();
            int fd = tunFd.detachFd();
            
            // Start tunnel
            String configPath = "/data/local/tmp/config.yml";
            nativeStartService(configPath, fd);
            
            return Service.START_STICKY;
        } catch (Exception e) {
            Log.e(TAG, "Failed to start service", e);
            return Service.START_NOT_STICKY;
        }
    }
    
    private native void nativeStartService(String path, int fd);
}
```
```

--------------------------------

### Core Tunnel Functions

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Functions to start and control the SOCKS5 tunnel. `hev_socks5_tunnel_main` starts the tunnel using a configuration file, while `hev_socks5_tunnel_main_from_str` uses a configuration string. `hev_socks5_tunnel_quit` stops the tunnel, and `hev_socks5_tunnel_stats` retrieves statistics.

```APIDOC
## Core Tunnel Functions

### Start tunnel

`int hev_socks5_tunnel_main(const char *config_path, int tun_fd);`
Starts the tunnel using a configuration file.

`int hev_socks5_tunnel_main_from_str(const unsigned char *config, unsigned int len, int fd);`
Starts the tunnel using a configuration string.

### Control tunnel

`void hev_socks5_tunnel_quit(void);`
Quits the tunnel.

`void hev_socks5_tunnel_stats(size_t *tx_pkts, size_t *tx_bytes, size_t *rx_pkts, size_t *rx_bytes);`
Retrieves tunnel statistics.
```

--------------------------------

### Get SOCKS5 Server Configuration

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/configuration.md

Retrieves the SOCKS5 server configuration object.

```c
HevConfigServer *srv = hev_config_get_socks5_server();
```

--------------------------------

### Configuration Functions

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Functions for initializing and finalizing the library's configuration, either from a file path or a string.

```c
// Configuration
int hev_config_init_from_file(const char *path);
int hev_config_init_from_str(const unsigned char *config, unsigned int len);
void hev_config_fini(void);
```

--------------------------------

### Get Tunnel Name Configuration

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/configuration.md

Retrieves the configured tunnel interface name.

```c
const char *iface = hev_config_get_tunnel_name();
```

--------------------------------

### Docker Quick Start

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/quick-start.md

This snippet shows how to run HevSocks5Tunnel using Docker. It requires the NET_ADMIN capability and access to the TUN device. Environment variables can be used to configure the upstream SOCKS5 server address and port, as well as tunnel interface name, MTU, and IPv4 address.

```bash
docker run --cap-add=NET_ADMIN \
           --device=/dev/net/tun \
           -e SOCKS5_ADDR=proxy.example.com \
           -e SOCKS5_PORT=1080 \
           ghcr.io/heiher/hev-socks5-tunnel:latest
```

--------------------------------

### Get Tunnel Statistics

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Retrieves the transmitted and received packet and byte counts for the tunnel.

```c
hev_socks5_tunnel_stats(&tx_pkts, &tx_bytes, &rx_pkts, &rx_bytes);
```

--------------------------------

### Get Connection Timeout Configuration

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/configuration.md

Retrieves the configured connection timeout value in milliseconds.

```c
int timeout = hev_config_get_misc_connect_timeout();
```

--------------------------------

### Minimal Configuration

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/configuration.md

A basic configuration with essential tunnel and SOCKS5 settings.

```yaml
tunnel:
  name: tun0
  ipv4: 198.18.0.1
  ipv6: 'fc00::1'

socks5:
  address: 127.0.0.1
  port: 1080
```

--------------------------------

### Get Connection Timeout

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the timeout in milliseconds for outbound connection attempts. Defaults to 10000.

```c
int hev_config_get_misc_connect_timeout(void);
```

--------------------------------

### Get UDP Session Class

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-socks5-session.md

Retrieves the class descriptor for HevSocks5SessionUDP. This is used for object-oriented operations.

```c
HevObjectClass *hev_socks5_session_udp_class(void);
```

--------------------------------

### Build HevSocks5Tunnel as a Library

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Clone the repository recursively and navigate to the directory. Use 'make static' to build a static library or 'make shared' to build a shared library.

```bash
git clone --recursive https://github.com/heiher/hev-socks5-tunnel
cd hev-socks5-tunnel

# Static library
make static

# Shared library
make shared
```

--------------------------------

### iperf3 Download Benchmark (10 Parallel Streams, Second Run)

Source: https://github.com/heiher/hev-socks5-tunnel/wiki/Benchmarks

Second benchmark run for iperf3 download speed with 10 parallel streams. Higher stream counts can saturate links.

```bash
$ iperf3 -c 192.168.0.8 -R -P 10
- - - - - - - - - - - - - - - - - - - - - - - - - -
[SUM]   0.00-10.04  sec  36.4 GBytes  31.2 Gbits/sec  166            sender
[SUM]   0.00-10.00  sec  36.3 GBytes  31.2 Gbits/sec                 receiver
CPU usage: 610%
MEM usage: 68M
```

--------------------------------

### Configuration Loading and Querying

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/MANIFEST.txt

Functions for initializing configuration from files or strings, and accessing configuration values.

```APIDOC
## hev_config_init_from_file(const char *config_path)

### Description
Initializes the configuration system by loading settings from a YAML file.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
- **config_path** (const char *) - Required - Path to the configuration file.

### Request Example
```c
hev_config_init_from_file("/etc/hev-socks5-tunnel.yaml");
```

### Response
None (configuration is loaded globally)

```

```APIDOC
## hev_config_init_from_str(const char *config_str)

### Description
Initializes the configuration system by loading settings from a configuration string.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
- **config_str** (const char *) - Required - String containing the configuration.

### Request Example
```c
hev_config_init_from_str("server:\n  port: 1080\n");
```

### Response
None (configuration is loaded globally)

```

```APIDOC
## hev_config_fini()

### Description
Cleans up and releases resources used by the configuration system.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
None

### Request Example
```c
hev_config_fini();
```

### Response
None

```

--------------------------------

### hev_config_get_tunnel_post_up_script

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the path to the script that should be executed after the tunnel interface is brought up. This script can be used for setup tasks.

```APIDOC
## hev_config_get_tunnel_post_up_script

### Description
Retrieves the path to the script executed after the tunnel interface is brought up.

### Method
C Function

### Endpoint
N/A

### Parameters
None

### Response
#### Success Response
- **return value** (const char *) - The script path, or NULL if not set.
```

--------------------------------

### hev_socks5_tunnel_main

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Starts and runs the SOCKS5 tunnel. This function blocks until the tunnel is quit or an error occurs. It is an alias for hev_socks5_tunnel_main_from_file.

```APIDOC
## hev_socks5_tunnel_main

### Description
Starts and runs the SOCKS5 tunnel using a configuration file. This function blocks until `hev_socks5_tunnel_quit` is called or an error occurs.

### Parameters
#### Path Parameters
- **config_path** (const char *) - The path to the configuration file.
- **tun_fd** (int) - The file descriptor for the tunnel.

### Returns
- **int** - Returns zero on success, otherwise returns -1.
```

--------------------------------

### Load Configuration

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Initializes configuration from a file, retrieves the tunnel interface name, and then cleans up the configuration.

```c
hev_config_init_from_file("path.yml");
const char *iface = hev_config_get_tunnel_name();
hev_config_fini();
```

--------------------------------

### hev_socks5_session_tcp_class

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-socks5-session.md

Retrieves the class descriptor for HevSocks5SessionTCP objects. This function is used to get the type information for TCP sessions.

```APIDOC
## hev_socks5_session_tcp_class

### Description
Get TCP session class type.

### Returns
Class descriptor for HevSocks5SessionTCP
```

--------------------------------

### Build HevSocks5Tunnel on Unix

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Clone the repository recursively, navigate to the directory, and run 'make' to build the project on Unix-like systems.

```bash
git clone --recursive https://github.com/heiher/hev-socks5-tunnel
cd hev-socks5-tunnel
make
```

--------------------------------

### hev_socks5_tunnel_main_from_str

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Starts and runs the SOCKS5 tunnel using a configuration string. This function blocks until the tunnel is quit or an error occurs.

```APIDOC
## hev_socks5_tunnel_main_from_str

### Description
Starts and runs the SOCKS5 tunnel using a configuration string. This function blocks until `hev_socks5_tunnel_quit` is called or an error occurs.

### Parameters
#### Path Parameters
- **config_str** (const unsigned char *) - The configuration string.
- **config_len** (unsigned int) - The byte length of the configuration string.
- **tun_fd** (int) - The file descriptor for the tunnel.

### Returns
- **int** - Returns zero on successful, otherwise returns -1.
```

--------------------------------

### Load Android JNI Library

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/exported-symbols.md

Load the hev-socks5-tunnel library for use with Android JNI. This is typically done once when your service starts.

```java
System.loadLibrary("hev-socks5-tunnel");
```

--------------------------------

### Initialize Logger with Info Level to Stderr

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Basic setup for the logger, initializing it to output messages with INFO level or higher to standard error. Ensure logger is finalized before application exit.

```c
int main() {
    // Initialize logging
    if (hev_logger_init(HEV_LOGGER_INFO, "stderr") < 0) {
        fprintf(stderr, "Failed to initialize logger\n");
        return -1;
    }

    LOG_I("Application started");

    // ... main code ...

    LOG_I("Application shutting down");
    hev_logger_fini();
    return 0;
}
```

--------------------------------

### Build HevSocks5Tunnel on Windows (MSYS2)

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Set the MSYS environment variable for native symbolic links, clone the repository recursively, navigate to the directory, and run 'make' to build on Windows using MSYS2.

```bash
export MSYS=winsymlinks:native
git clone --recursive https://github.com/heiher/hev-socks5-tunnel
cd hev-socks5-tunnel
make
```

--------------------------------

### Build HevSocks5Tunnel for Android

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/README.md

Create a directory, clone the repository into the 'jni' subdirectory, and run 'ndk-build' to build for Android.

```bash
mkdir hev-socks5-tunnel
cd hev-socks5-tunnel
git clone --recursive https://github.com/heiher/hev-socks5-tunnel jni
ndk-build
```

--------------------------------

### Get File Descriptor Limit

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the file descriptor limit. Defaults to 65535. This sets the RLIMIT_NOFILE resource limit.

```c
int hev_config_get_misc_limit_nofile(void);
```

--------------------------------

### Get UDP Read/Write Timeout

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the timeout in milliseconds for idle UDP sessions. Defaults to 60000 (1 minute).

```c
int hev_config_get_misc_udp_read_write_timeout(void);
```

--------------------------------

### iperf3 Download Benchmark (Single Stream, Second Run)

Source: https://github.com/heiher/hev-socks5-tunnel/wiki/Benchmarks

Second benchmark run for iperf3 download speed. Results may vary based on network conditions.

```bash
$ iperf3 -c 192.168.0.8 -R
- - - - - - - - - - - - - - - - - - - - - - - - - -
[  5]   0.00-10.04  sec  12.8 GBytes  10.9 Gbits/sec    0            sender
[  5]   0.00-10.00  sec  12.7 GBytes  10.9 Gbits/sec                 receiver
CPU usage: 160%
MEM usage: 67M
```

--------------------------------

### Initialize Loggers from Configuration

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-logger.md

Loads logging configuration, including log file path and level, from application settings. Initializes both the main logger and a separate logger for the socks5 library.

```c
// From hev_config.c
const char *log_file = hev_config_get_misc_log_file();
int log_level = hev_config_get_misc_log_level();

hev_logger_init(log_level, log_file);
hev_socks5_logger_init(log_level, log_file);  // separate logger for socks5 library
```

--------------------------------

### Get TCP Read/Write Timeout

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the timeout in milliseconds for idle TCP sessions. Defaults to 300000 (5 minutes).

```c
int hev_config_get_misc_tcp_read_write_timeout(void);
```

--------------------------------

### Get Tunnel MTU

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the Maximum Transmission Unit (MTU) for the tunnel interface in bytes. The default MTU is 8500.

```c
unsigned int hev_config_get_tunnel_mtu(void);
```

--------------------------------

### Get Tunnel Name

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the name of the tunnel interface. This is typically used to identify the network interface associated with the tunnel.

```c
const char *hev_config_get_tunnel_name(void);
```

--------------------------------

### Logging Functions

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/README.md

Functions to initialize the logger with a specified level and path, and to log messages.

```c
// Logging
int hev_logger_init(HevLoggerLevel level, const char *path);
void hev_logger_log(HevLoggerLevel level, const char *fmt, ...);
```

--------------------------------

### Get SOCKS5 Session Interface Type

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-socks5-session.md

Retrieves the class type descriptor for HevSocks5Session. Used internally for polymorphic dispatch.

```c
void *hev_socks5_session_iface(void);
```

--------------------------------

### Initialize Configuration from File

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Loads and parses the hev-socks5-tunnel configuration from a specified YAML file. This function must be called before querying any configuration parameters and requires the 'tunnel' and 'socks5' sections. Ensure `hev_config_fini()` is called before re-initializing.

```c
int hev_config_init_from_file(const char *config_path);

```

```c
if (hev_config_init_from_file("config.yml") < 0) {
    fprintf(stderr, "Failed to load config\n");
    return -1;
}

```

--------------------------------

### Get HevMappedDNS Class Descriptor

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-mapped-dns.md

Retrieves the class descriptor for HevMappedDNS. This is typically used for object-oriented operations within the library.

```c
HevObjectClass *hev_mapped_dns_class(void);
```

--------------------------------

### iperf3 Download Test with 10 Parallel Streams (sing-box)

Source: https://github.com/heiher/hev-socks5-tunnel/wiki/Benchmarks

iperf3 command to test download speed with 10 parallel streams using sing-box. Performance metrics are reported.

```bash
$ iperf3 -c 192.168.0.8 -R -P 10
```

```bash
- - - - - - - - - - - - - - - - - - - - - - - - - -
[SUM]   0.00-10.04  sec   19.0 GBytes  16.2 Gbits/sec  4776            sender
[SUM]   0.00-10.00  sec   18.8 GBytes  16.1 Gbits/sec                  receiver
CPU usage: 125%
MEM usage: 37.4M
```

--------------------------------

### Get Log File Path

Source: https://github.com/heiher/hev-socks5-tunnel/blob/main/_autodocs/api-reference-config.md

Retrieves the log file path. Can be a file path, 'stdout', 'stderr', or default. Defaults to 'stderr'.

```c
const char *hev_config_get_misc_log_file(void);
```