Formato contenitore HCC2DF
HCC2DF è il formato contenitore binario usato per impostazione predefinita dall'API (passa structured: false per evitarlo). Avvolge il payload originale con un nome file e, se utile, con compressione zlib.
← Torna alla documentazione API
Layout binario
Tutti i campi multibyte sono in big-endian. Il contenitore è una sequenza piatta di byte, senza padding.
| Offset | Dimensione (byte) | Campo | Descrizione |
|---|---|---|---|
| 0 | 6 | magic | Stringa ASCII HCC2DF. È sempre presente e serve al decoder per riconoscere il formato. |
| 6 | 1 | version | Versione del formato. Attualmente sempre 0x01. |
| 7 | 1 | compression | Flag di compressione. 0x00 = non compresso, 0x01 = compresso con zlib-deflate. |
| 8 | 1 | nameLen | Lunghezza in byte del nome file UTF-8 che segue. Intervallo valido: 1–127. |
| 9 | nameLen | name | Nome file UTF-8, senza separatori di percorso e senza byte nulli. |
| 9 + nameLen | restante | content | Byte del contenuto. Se compression == 0x01, decomprimere con inflate / zlib.decompress. |
Regole di compressione
L'encoder tenta la compressione zlib su ogni payload. La compressione viene applicata solo quando l'output compresso è inferiore al 90% della dimensione originale.
Vincoli sul nome file
- Da 1 a 127 byte UTF-8.
- Nessun separatore di percorso (/ o \).
- Nessun byte nullo (0x00).
Sono vincoli imposti dal formato. L'API normalizza i valori inputName non conformi prima di passarli all'encoder.
Esempio — dump esadecimale
Contenitore che racchiude la stringa ASCII Hello salvata come note.txt, non compressa:
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"
Vedi anche
Documentazione API — come generare codici a barre tramite l'API REST.
Esempi di codice — snippet pronti per JavaScript, Python, Java e PHP.