Formato contenedor HCC2DF
HCC2DF es el formato binario contenedor que la API utiliza por defecto (pase structured: false para omitirlo). Envuelve el contenido original con un nombre de archivo y, si conviene, con compresión zlib.
← Volver a la documentación de la API
Diseño binario
Todos los campos multibyte usan big-endian. El contenedor es una secuencia plana de bytes, sin relleno.
| Desplazamiento | Tamaño (bytes) | Campo | Descripción |
|---|---|---|---|
| 0 | 6 | magic | Cadena ASCII HCC2DF. Siempre está presente y permite al decodificador reconocer el formato. |
| 6 | 1 | version | Versión del formato. Actualmente siempre 0x01. |
| 7 | 1 | compression | Indicador de compresión. 0x00 = sin comprimir, 0x01 = comprimido con zlib-deflate. |
| 8 | 1 | nameLen | Longitud en bytes del nombre de archivo UTF-8 que sigue. Rango válido: 1–127. |
| 9 | nameLen | name | Nombre de archivo UTF-8, sin separadores de ruta ni bytes nulos. |
| 9 + nameLen | resto | content | Bytes del contenido. Si compression == 0x01, descomprímalo con inflate / zlib.decompress. |
Reglas de compresión
El codificador intenta comprimir con zlib cada contenido. Solo aplica la compresión cuando el resultado ocupa menos del 90% del tamaño original.
Restricciones del nombre de archivo
- Entre 1 y 127 bytes UTF-8.
- Sin separadores de ruta (/ o \).
- Sin bytes nulos (0x00).
Se trata de restricciones del propio formato. La API normaliza los valores inputName no válidos antes de pasarlos al codificador.
Ejemplo — volcado hexadecimal
Contenedor que envuelve la cadena ASCII Hello guardada como note.txt, sin compresión:
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"
Véase también
Documentación de la API — cómo generar códigos mediante la API REST.
Ejemplos de código — fragmentos listos para JavaScript, Python, Java y PHP.