# QFT protocol notes — v0.4.7 ## 1. Windows → Android optical: QFT2 Active display text: ```text QFT2: ``` 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:` 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=- ``` 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.