# 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. ## 6. Android → Android (`QFTPHONE2`, v0.5.0-dev4) The sender starts an authenticated local HTTP service and encodes only session, port, sender identity and optional dedicated-network 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/ Range: bytes=- X-QFT-Token: ``` 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 prefers a 2.4 GHz WPA2 Wi-Fi Direct group-owner AP that accepts legacy Wi-Fi stations. An OEM P2P failure falls back to LocalOnlyHotspot, then literal private IPv4 endpoints on the current LAN. WPA2/WPA3 credentials are distinguished in `w[2]`. The receiver reuses the existing Range ledger, retries and SHA-256-before-publish behavior for every file, processing items in manifest order. Phone senders use one deterministic Range worker to avoid concurrent-read corruption in older Android document providers; desktop senders retain up to eight workers.