Quick Start

Quick Start

This page shows the shortest safe path for embedding V2Root Core. Read the complete integration guide before shipping a production application.

1. Download the Correct Package

Choose the ZIP matching the host process:

Host	Package
Windows 64-bit	V2Root-Core-windows-amd64-<version>.zip
Windows 32-bit	V2Root-Core-windows-386-<version>.zip
Linux x86-64	V2Root-Core-linux-amd64-<version>.zip
Linux ARM64	V2Root-Core-linux-arm64-<version>.zip
Linux 32-bit x86	V2Root-Core-linux-386-<version>.zip

Each ZIP contains the shared library, matching C header, and SHA256SUMS.

2. Verify the Package

sha256sum -c SHA256SUMS

Never combine a header and binary from different releases or architectures.

3. Load and Declare the API

Use the generated header for C/C++, ctypes for Python, P/Invoke for C#, or dart:ffi for Dart/Flutter.

The most important ABI rule is:

Every non-null string returned by V2Root Core must be released exactly once with FreeCString.

4. Validate Before Starting

char *result = ValidateConfig(config_json, "{}");
if (result == NULL) {
    /* Unexpected: validation normally returns JSON. */
} else {
    /* Parse JSON and check for "error" or "result". */
    FreeCString(result);
}

config_json may also be a path to an Xray JSON file or a supported share URI.

5. Start the Runtime

char *error = Start(config_json, "{}");
if (error != NULL) {
    fprintf(stderr, "V2Root start failed: %s\n", error);
    FreeCString(error);
}

A null pointer means success. A non-null pointer is an allocated error string.

V2Root Core manages one process-global Xray instance. It is a local proxy runtime and does not create or manage a TUN/VPN interface.

6. Read Status and Statistics

char *status = GetStatus();
printf("Status: %s\n", status);
FreeCString(status);

While running:

• GetTotalTraffics returns cumulative bytes.
• GetRealtimeSpeed returns bytes per second.
• The first speed call establishes a baseline and normally returns zero.

7. Stop Before Shutdown

char *error = Stop();
if (error != NULL) {
    fprintf(stderr, "V2Root stop warning: %s\n", error);
    FreeCString(error);
}

Stop the engine before unloading the library or terminating the host process.

Minimal Integration Checklist

• Correct package for the process architecture
• ZIP checksum verified
• UTF-8 strings used
• Every returned pointer released through FreeCString
• Configuration validated before startup
• Lifecycle calls serialized
• Only one runtime instance per process
• Blocking network calls kept off the UI thread
• Runtime stopped before library unload

Continue with the complete developer guide.