Files
QFT/docs/PROTOCOL.md
T
2026-08-11 13:49:27 +08:00

101 lines
3.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# QFT protocol notes — v0.4.7
## 1. Windows → Android optical: QFT2
Active display text:
```text
QFT2:<Base45(binary-frame)>
```
Base45 is used because its alphabet fits QR alphanumeric encoding, while Android can consume a normal ZXing `Result.text`. The receiver also keeps legacy `QFT1:<base64url(...)>` parsing for old senders.
### Binary frame
```text
magic 4 "QFT2"
version 1 2
kind 1 1=MANIFEST / 2=DATA / 3=END
session 8 u64 BE
sequence 4 u32 BE
total 4 u32 BE
payloadLen 2 u16 BE
payload N
crc32 4 u32 BE over everything before crc32
```
### MANIFEST payload
```text
fileSize 8 u64 BE
chunkSize 2 u16 BE
sha256 32
fileNameLen 2 u16 BE
fileName N UTF-8
senderLen 2 u16 BE
senderDevice N UTF-8
```
### Optical parameters in v0.4.7
- one QR per display frame;
- DATA payload: **450 B**;
- QR error correction: L;
- full 4-module quiet zone;
- Windows display target: 5~60 FPS, default 45;
- synthetic representative DATA frame: 722 text chars / QR-L v15;
- theoretical payload at 60 display FPS: 27,000 B/s ≈ 26.4 KiB/s before camera misses/replay.
Sender continuously loops `MANIFEST → DATA 0..N-1 → END`. Android deduplicates by sequence number and reconstructs once all chunks are present. No reverse ACK/network channel exists for this direction.
## 2. Android optical ROI state machine
```text
ACQUIRE
center search
occasional full frame
↓ success
LOCKED
copy Y-plane ROI only
GlobalHistogram every frame
sparse Hybrid fallback
↓ finder points
smooth ROI position/size
↓ misses
expand ROI
↓ sustained misses
REACQUIRE
```
The overlay is derived from the same ROI used by the decoder, so the green/yellow box is not decorative—it reflects the actual analysis area.
## 3. Android → Windows pairing
`QFTPAIR2` remains the active pairing format from v0.3. It contains local-only session/network metadata. Android validates the pairing endpoint as a literal local/private IPv4 and binds subsequent discovery/upload to the selected local `Network`.
Discovery order includes QR hint, UDP `QFTDISC2`, gateway/direct candidates and bounded current-subnet fallback.
## 4. 扫码本地直传(Android ↔ Windows)
Parallel v2 flow:
```text
POST /qft/upload/init
POST /qft/upload/chunk (parallel, offset based)
POST /qft/upload/finish
```
Windows preallocates a `.qftpart`, writes chunks at explicit offsets, verifies SHA-256, then renames to the final file. Uploads target 8 workers per file (bounded by the usable chunks and device capacity); the requested chunk size is derived from the file size and clamped to **64 KiB–16 MiB**. Repeated chunk and finish requests are idempotent so a lost response can be retried safely.
## 5. Windows → Android download
The same QFTPAIR2 local session can declare the download direction. Android discovers and verifies the Windows sender, then downloads `GET /qft/download` with exact single-range requests:
```text
Range: bytes=<start>-<end>
```
The sender returns `206 Partial Content`, the matching `Content-Range`, and the exact requested body length. Android splits the file toward 8 workers with **64 KiB–16 MiB** chunks, stores each completed chunk in a `.qftpart.map` ledger, and resumes only missing chunks after a reconnect. Each range can retry up to five times; the complete partial file must pass SHA-256 before it is published to `Downloads/QFT`.
For both direct-transfer directions, the Windows listener may accept connections non-blockingly for shutdown responsiveness, but each accepted file socket is switched to blocking I/O with explicit timeouts before reading or writing request bodies. This prevents `WSAEWOULDBLOCK (10035)` from turning an in-progress parallel transfer into an HTTP 500 failure.