# 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-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/ 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 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.