125 lines
5.0 KiB
Markdown
125 lines
5.0 KiB
Markdown
# 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 `init` requests carrying the same `X-QFT-Upload-Key` resume the matching active upload session; repeated chunk and finish requests are idempotent so a lost response can be retried safely. Chunk completion is recorded only after the positioned write reaches stable storage.
|
||
|
||
## 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 retries with the currently available `Network`; 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.
|
||
|
||
## 6. Android → Android (`QFTPHONE2`, v0.5.0-dev1)
|
||
|
||
The sender starts an authenticated local HTTP service and encodes only session,
|
||
port, sender identity and optional LocalOnlyHotspot credentials in the QR. The
|
||
file queue is fetched after pairing so QR density is independent of queue size:
|
||
|
||
```text
|
||
GET /qft/ping
|
||
GET /qft/phone/manifest
|
||
GET /qft/phone/download/<queue-index>
|
||
Range: bytes=<start>-<end>
|
||
X-QFT-Token: <one-time session>
|
||
```
|
||
|
||
The manifest contains a bounded ordered list of `name`, `size`, `sha256` and a
|
||
server-generated fixed download path. The receiver does not accept arbitrary
|
||
paths from the QR or manifest: entry `N` must use `/qft/phone/download/N`.
|
||
|
||
Android 8+ prefers a system LocalOnlyHotspot. Android 7, or a hotspot failure,
|
||
falls back to literal private IPv4 endpoints on the current LAN. WPA2/WPA3
|
||
credentials are distinguished in `w[2]`. The receiver then reuses the existing
|
||
parallel Range ledger, retries and SHA-256-before-publish behavior for every
|
||
file, processing items in manifest order.
|