Christian Nennemann
2e081ead8e
Rename all project references from quicproquo/qpq to quicprochat/qpc across documentation, Docker configuration, CI workflows, packaging scripts, operational configs, and build tooling. - Docker: crate paths, binary names, user/group, data dirs, env vars - CI: workflow crate references, binary names, artifact names - Docs: all markdown files under docs/, SDK READMEs, book.toml - Packaging: OpenWrt Makefile, init script, UCI config (file renames) - Scripts: justfile, dev-shell, screenshot, cross-compile, ai_team - Operations: Prometheus config, alert rules, Grafana dashboard - Config: .env.example (QPQ_* → QPC_*), CODEOWNERS paths - Top-level: README, CONTRIBUTING, ROADMAP, CLAUDE.md
112 lines
2.7 KiB
Markdown
112 lines
2.7 KiB
Markdown
# QuicProChat Kotlin SDK
|
|
|
|
Kotlin/JVM wrapper over `libquicprochat_ffi` via JNI for Android and JVM platforms.
|
|
|
|
## Prerequisites
|
|
|
|
- Kotlin 1.9+ / JDK 17+
|
|
- `libquicprochat_ffi` built for the target architecture
|
|
- JNI bridge compiled (`jni/dev_quicprochat_NativeBridge.c`)
|
|
|
|
## Building the Native Library
|
|
|
|
```sh
|
|
# Linux (JVM)
|
|
cargo build --release -p quicprochat-ffi
|
|
|
|
# Android (aarch64)
|
|
cargo build --release -p quicprochat-ffi --target aarch64-linux-android
|
|
|
|
# Android (armv7)
|
|
cargo build --release -p quicprochat-ffi --target armv7-linux-androideabi
|
|
```
|
|
|
|
### Compiling the JNI Bridge
|
|
|
|
```sh
|
|
cd jni
|
|
gcc -shared -fPIC -o libquicprochat_jni.so \
|
|
-I"$JAVA_HOME/include" -I"$JAVA_HOME/include/linux" \
|
|
dev_quicprochat_NativeBridge.c \
|
|
-L ../../../../target/release -lquicprochat_ffi
|
|
```
|
|
|
|
## Installation
|
|
|
|
### Gradle
|
|
|
|
```kotlin
|
|
dependencies {
|
|
implementation(files("libs/quicprochat-0.1.0.jar"))
|
|
}
|
|
```
|
|
|
|
Or include as a local project module.
|
|
|
|
## Usage
|
|
|
|
```kotlin
|
|
import dev.quicprochat.QpqClient
|
|
|
|
val client = QpqClient("127.0.0.1:5001", caCertPath = "ca.pem")
|
|
|
|
client.login("alice", "secret")
|
|
client.send("bob", "hello".toByteArray())
|
|
|
|
val messages = client.receive(timeoutMs = 5000)
|
|
messages.forEach { println("Received: $it") }
|
|
|
|
client.close()
|
|
```
|
|
|
|
## API
|
|
|
|
| Method | Description |
|
|
|---|---|
|
|
| `QpqClient(server, caCertPath, serverName)` | Connect to server |
|
|
| `client.login(username, password)` | OPAQUE authentication |
|
|
| `client.send(recipient, message)` | Send message by username |
|
|
| `client.receive(timeoutMs)` | Receive pending messages |
|
|
| `client.close()` / `client.disconnect()` | Disconnect |
|
|
| `client.isConnected` | Connection status |
|
|
|
|
## Error Handling
|
|
|
|
```kotlin
|
|
try {
|
|
client.login("alice", "wrong")
|
|
} catch (e: QpqAuthException) {
|
|
println("Auth failed: ${e.message}")
|
|
} catch (e: QpqTimeoutException) {
|
|
println("Timeout: ${e.message}")
|
|
} catch (e: QpqException) {
|
|
println("Error: ${e.message}")
|
|
}
|
|
```
|
|
|
|
## Structure
|
|
|
|
- `src/main/kotlin/dev/quicprochat/QpqClient.kt` -- High-level client
|
|
- `src/main/kotlin/dev/quicprochat/NativeBridge.kt` -- JNI declarations
|
|
- `src/main/kotlin/dev/quicprochat/QpqError.kt` -- Exception types
|
|
- `jni/dev_quicprochat_NativeBridge.c` -- JNI C bridge to FFI
|
|
|
|
## Android Integration
|
|
|
|
1. Add the native libraries to `src/main/jniLibs/<abi>/`:
|
|
- `arm64-v8a/libquicprochat_ffi.so`
|
|
- `armeabi-v7a/libquicprochat_ffi.so`
|
|
2. Add the JNI bridge library alongside
|
|
3. The `NativeBridge` class loads the library via `System.loadLibrary`
|
|
|
|
## Cross-Compilation
|
|
|
|
```sh
|
|
# Install Android NDK targets
|
|
rustup target add aarch64-linux-android armv7-linux-androideabi
|
|
|
|
# Build with the NDK linker
|
|
CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=aarch64-linux-android21-clang \
|
|
cargo build --release -p quicprochat-ffi --target aarch64-linux-android
|
|
```
|