Les structures de données
Voici la structures de données de flux de zlib :
- typedef voidpf (*alloc_func)(voidpf opaque, uInt items, uInt size);
- typedef void (*free_func)(voidpf opaque, voidpf address);
-
- struct internal_state;
-
- typedef struct z_stream_s {
- z_const Bytef *next_in; /* octet d'entrée suivant */
- uInt avail_in; /* nombre d'octets disponibles à next_in */
- uLong total_in; /* nombre total d'octets d'entrée lus jusqu'à présent */
-
- Bytef *next_out; /* le prochain octet de sortie ira ici */
- uInt avail_out; /* espace libre restant à next_out */
- uLong total_out; /* nombre total d'octets générés jusqu'à présent */
-
- z_const char *msg; /* dernier message d'erreur, NULL si aucune erreur */
- struct internal_state FAR *state; /* non visible par les applications */
-
- alloc_func zalloc; /* utilisé pour allouer l'état interne */
- free_func zfree; /* utilisé pour libérer l'état interne */
- voidpf opaque; /* objet de données privé transmis à zalloc et zfree */
-
- int data_type; /* meilleure estimation du type de données : binaire ou texte pour deflate, ou l'état de décodage pour inflate */
- uLong adler; /* Valeur Adler-32 ou CRC-32 des données non compressées */
- uLong reserved; /* réservé pour une utilisation future */
- } z_stream;
-
- typedef z_stream FAR *z_streamp;
Voici les informations d'entête gzip transmises vers et depuis les routines zlib. Voir RFC 1952 pour plus de détails sur la signification de ces champs :
- typedef struct gz_header_s {
- int text; /* Vrai si les données compressées sont censées être du texte */
- uLong time; /* Heure de modification */
- int xflags; /* Drapeaux supplémentaires (non utilisés lors de l'écriture d'un fichier gzip) */
- int os; /* Système d'exploitation */
- Bytef *extra; /* Pointeur vers un champ supplémentaire ou Z_NULL si aucun */
- uInt extra_len; /* Longueur de champ supplémentaire (valide si supplémentaire != Z_NULL) */
- uInt extra_max; /* Espace supplémentaire (uniquement lors de la lecture de l'entête) */
- Bytef *name; /* Pointeur vers un nom de fichier terminé par zéro ou Z_NULL */
- uInt name_max; /* Espace au nom (uniquement lors de la lecture de l'entête) */
- Bytef *comment; /* Pointeur vers un commentaire terminé par zéro ou Z_NULL */
- uInt comm_max; /* Espace dans le commentaire (uniquement lors de la lecture de l'entête) */
- int hcrc; /* Vrai s'il y avait ou il y aura un entête CRC */
- int done; /* Vrai lorsque la lecture de l'entête gzip est terminée (non utilisé lors de l'écriture d'un fichier gzip) */
- } gz_header;
-
- typedef gz_header FAR *gz_headerp;
Utilisation des structures
L'application doit mettre à jour next_in et avail_in lorsque avail_in est tombé à zéro. Elle doit mettre à jour next_out et avail_out lorsque avail_out est tombé à zéro. L'application doit initialiser zalloc, zfree et opaque avant d'appeler la fonction init. Tous les autres champs sont définis par la bibliothèque de compression et ne doivent pas être mis à jour par l'application.
La valeur opaque fournie par l'application sera passée comme premier paramètre pour les appels de zalloc et zfree. Cela peut être utile pour la gestion personnalisée de la mémoire. La bibliothèque de compression n'attache aucune signification à la valeur opaque.
zalloc doit renvoyer Z_NULL s'il n'y a pas assez de mémoire pour l'objet. Si zlib est utilisé dans une application multi-processus léger, zalloc et zfree doivent être thread-safe. Dans ce cas, zlib est thread-safe. Lorsque zalloc et zfree sont Z_NULL à l'entrée de la fonction d'initialisation, ils sont définis sur des routines internes utilisant les fonctions de bibliothèque standard malloc() et free().
Sur les systèmes 16 bits, les fonctions zalloc et zfree doivent pouvoir allouer exactement 65536 octets, mais ne seront pas obligées d'en allouer plus si le symbole MAXSEG_64K est défini (voir zconf.h).
Avertissement : Sur MS-DOS, les pointeurs renvoyés par zalloc pour des objets d'exactement 655 36 octets doivent avoir leur décalage normalisé à zéro. La fonction d'allocation par défaut fournie par cette bibliothèque garantit cela (voir zutil.c). Pour réduire les besoins en mémoire et éviter toute allocation d'objets de 64 Ko, au détriment du taux de compression, compilez la bibliothèque avec -DMAX_WBITS=14 (voir zconf.h).
Les champs total_in et total_out peuvent être utilisés pour les statistiques ou les rapports de progression. Après compression, total_in contient la taille totale des données non compressées et peut être enregistré pour être utilisé par le décompresseur (en particulier si le décompresseur souhaite tout décompresser en une seule étape).