HCC2DF Container Format
HCC2DF is the binary container format used by default when calling the API (pass structured: false to skip it). It wraps the raw payload with a filename and optional zlib compression so that the decoder can reconstruct the original file faithfully.
Binary layout
All multi-byte fields are big-endian. The container is a flat byte sequence with no padding.
| Offset | Size (bytes) | Field | Description |
|---|---|---|---|
| 0 | 6 | magic | ASCII string HCC2DF. Always present and used by the decoder to recognise the format. |
| 6 | 1 | version | Format version. Currently always 0x01. |
| 7 | 1 | compression | Compression flag. 0x00 = uncompressed, 0x01 = zlib-deflate compressed. |
| 8 | 1 | nameLen | Length in bytes of the UTF-8 filename that follows. Valid range: 1–127. |
| 9 | nameLen | name | UTF-8 encoded filename without path separators and without null bytes. |
| 9 + nameLen | remainder | content | Payload bytes. If compression == 0x01, decompress with inflate / zlib.decompress. |
Compression rules
The encoder attempts zlib compression on every payload. Compression is applied only when the compressed output is smaller than 90% of the original size; otherwise the raw bytes are stored.
Filename constraints
- 1–127 UTF-8 bytes.
- No path separators (/ or \).
- No null bytes (0x00).
These are format-level constraints enforced by the encoder. The API normalises invalid inputName values before passing them to the encoder.
Example — hex dump
Container wrapping the ASCII string Hello stored as note.txt, uncompressed:
48 43 43 32 44 46 — magic "HCC2DF" 01 — version 1 00 — uncompressed 08 — filename length: 8 bytes 6e 6f 74 65 2e 74 78 74 — "note.txt" 48 65 6c 6c 6f — content: "Hello"
See also
API documentation — how to generate barcodes using the REST API.
Code examples — ready-to-run snippets in JavaScript, Python, Java, and PHP.