Files
QFT/docs/PROTOCOL.md
T
2026-08-10 15:45:04 +08:00

2.5 KiB

QFT protocol overview · v0.3.0-rc3

QFT1 — Windows → Android optical stream

Wire text:

QFT1:<base64url(binary frame)>

Binary frame fields:

  • magic QFT1
  • protocol version
  • frame kind: MANIFEST / DATA / END
  • session id
  • sequence index
  • total chunks
  • payload length
  • payload
  • CRC32

MANIFEST contains file name, file size, chunk size, total chunks, SHA-256 and Windows sender-device name. DATA frames are replayed cyclically; Android de-duplicates chunks and waits for missing chunks in later rounds. No Android→Windows feedback channel is used in optical mode.

v0.3 defaults: 900-byte DATA payload, 4 QR/page, target up to 60 pages/s.

QFTPAIR2 — Android → Windows pairing

Text:

QFTPAIR2:<base64url(compact JSON)>

Compact JSON keys:

  • v: 2
  • s: one-time session token
  • n: Windows device name
  • p: receiver TCP port
  • e: local HTTP endpoint hints; Direct AP normally carries one short hint
  • w: optional [ssid, passphrase] for QFT Direct

QFTPAIR1 remains parser-compatible for older QR payloads.

Android treats pairing QR as untrusted. HTTP endpoint hints must be literal private/local IPv4 addresses on the advertised port. Every /qft/* request must carry the one-time X-QFT-Token session value.

Receiver discovery

UDP request to port 39392:

QFTDISC2:<session>

Windows response:

QFTHERE2:<session>:<tcp_port>

Android combines UDP result with QR hint, the actual connected Wi-Fi gateway, common Windows local addresses and a bounded current-subnet fallback scan.

Parallel v2 upload

Ping

GET /qft/ping

Headers include X-QFT-Token and encoded Android device name.

Init

POST /qft/upload/init

Headers include file name, file size and desired chunk size. Android requests 4/8/16 MiB depending on file size; Windows clamps accepted chunks to 1~16 MiB.

Response includes upload_id, accepted chunk_size, and total_chunks.

Chunk

POST /qft/upload/chunk/<upload_id>/<index>

Body is exactly that file range. Up to eight Android workers send distinct chunks concurrently. Windows writes each accepted chunk to the preallocated .qftpart file at its deterministic offset.

Finish

POST /qft/upload/finish/<upload_id>

Windows rejects finish while chunks are missing. Once complete it computes SHA-256, renames the temporary file to its final unique name, and returns success.

Compatibility

POST /qft/upload remains the single-stream fallback for old clients or content providers that cannot sustain seekable parallel reads.