QMail Object Transfer Status — Group 6, Code 78

Quick reference

Purpose

After a client reconnects following a dropped connection, it does not know which of its earlier object_put_range calls actually landed. object_transfer_status answers that by returning a list of range entries in one of two modes, selected by the request's range_mode:

• range_mode = 1 (received) — entries describing bytes the server already has. The client can skip re-sending these.
• range_mode = 0 (missing) — entries describing gaps still needed to reach total_size. The client uploads exactly these ranges to complete the transfer.

The server returns at most max_ranges entries per call (capped at 256) and never constructs an unbounded response. A transfer with more entries than fit in one response is paginated via cursor/next_cursor; see Cursor pagination below.

Request body

Preamble (48 bytes, offsets 0–47)

Standard QMail preamble. See QMail Overview — Universal preamble.

Common prefix (16 bytes, offsets 48–63)

See object_begin for the shared common-prefix field table. command_header_length must equal 32 for this command.

Status request payload (32 bytes, offsets 64–95)

Response body

Successful response fixed header length: 72 bytes (16-byte common prefix + 56-byte status response), followed by range_count 16-byte range entries.

Status codes

Cursor pagination

The cursor is opaque despite its integer encoding — clients must not interpret or construct it, only return the value the server most recently gave them. A typical drain loop:

cursor = 0
ranges = []
while True:
    resp = transfer_status(transfer_id, cursor, range_mode=0, max_ranges=256)
    ranges.extend(resp.range_entries)
    if resp.next_cursor == 0:
        break
    cursor = resp.next_cursor

The server returns at most 256 entries per call regardless of the requested max_ranges, so a transfer with many small, non-contiguous ranges may require several calls to fully enumerate.

Common mistakes