Les fonctions avancées

Les fonctions suivantes ne sont nécessaires que dans certaines applications spéciales.

Il s'agit d'une autre version de deflateInit avec plus d'options de compression. Les champs zalloc, zfree et opaque doivent être initialisés au préalable par l'appelant.

Le paramètre method est la méthode de compression. Il doit être Z_DEFLATED dans cette version de la bibliothèque.

Le paramètre windowBits est le logarithme en base deux de la taille de la fenêtre (la taille du tampon d'historique). Il doit être compris entre 8 et 15 pour cette version de la bibliothèque. Des valeurs plus élevées de ce paramètre entraînent une meilleure compression au détriment de l'utilisation de la mémoire. La valeur par défaut est 15 si deflateInit est utilisé à la place.

Pour l'implémentation actuelle de deflate(), une valeur windowBits de 8 (une taille de fenêtre de 256 octets) n'est pas prise en charge. Par conséquent, une demande de 8 donnera 9 (une fenêtre de 512 octets). Dans ce cas, fournir 8 à inflateInit2() entraînera une erreur lorsque l'entête zlib avec 9 sera vérifié par rapport à l'initialisation de inflate(). Le remède est de ne pas utiliser 8 avec deflateInit2() avec cette initialisation, ou au moins dans ce cas utiliser 9 avec inflateInit2().

windowBits peut également être -8..-15 pour le deflate brut. Dans ce cas, -windowBits détermine la taille de la fenêtre. deflate() génère alors des données deflate brutes sans en-tête ni remorque zlib, et ne calcule pas de valeur de contrôle.

windowBits peut également être supérieur à 15 pour un codage gzip facultatif. Ajoutez 16 à windowBits pour écrire un entête et une remorque gzip simples autour des données compressées au lieu d'un enveloppe zlib. L'entête gzip n'aura pas de nom de fichier, pas de données supplémentaires, pas de commentaire, pas d'heure de modification (définie à zéro), pas de crc d'entête, et le système d'exploitation sera défini sur la valeur appropriée, si le système d'exploitation a été déterminé au moment de la compilation. Si un flux gzip est en cours d'écriture, strm->adler est un CRC-32 au lieu d'un Adler-32.

Pour le codage raw deflate ou gzip, une demande de fenêtre de 256 octets est rejetée comme non valide, car seul l'entête zlib fournit un moyen de transmettre la taille de la fenêtre au décompresseur.

Le paramètre memLevel spécifie la quantité de mémoire à allouer pour l'état de compression interne. memLevel=1 utilise un minimum de mémoire mais est lent et réduit le taux de compression ; memLevel=9 utilise un maximum de mémoire pour une vitesse optimale. La valeur par défaut est 8. Voir zconf.h pour l'utilisation totale de la mémoire en fonction de windowBits et memLevel.

Le paramètre strategy est utilisé pour ajuster l'algorithme de compression. Utilisez la valeur Z_DEFAULT_STRATEGY pour les données normales, Z_FILTERED pour les données produites par un filtre (ou un prédicteur), Z_HUFFMAN_ONLY pour forcer uniquement le codage Huffman (pas de correspondance de chaîne) ou Z_RLE pour limiter les distances de correspondance à une (codage de longueur d'exécution). Les données filtrées se composent principalement de petites valeurs avec une distribution quelque peu aléatoire. Dans ce cas, l'algorithme de compression est réglé pour mieux les compresser. L'effet de Z_FILTERED est de forcer plus de codage Huffman et moins de correspondance de chaîne; il est quelque peu intermédiaire entre Z_DEFAULT_STRATEGY et Z_HUFFMAN_ONLY. Z_RLE est conçu pour être presque aussi rapide que Z_HUFFMAN_ONLY, mais offre une meilleure compression pour les données d'image PNG. Le paramètre strategy n'affecte que le taux de compression mais pas l'exactitude de la sortie compressée même s'il n'est pas défini de manière appropriée. Z_FIXED empêche l'utilisation de codes Huffman dynamiques, permettant un décodeur plus simple pour des applications spéciales.

deflateInit2 renvoie Z_OK en cas de succès, Z_MEM_ERROR s'il n'y avait pas assez de mémoire, Z_STREAM_ERROR si un paramètre n'est pas valide (comme une méthode non valide), ou Z_VERSION_ERROR si la version de la bibliothèque zlib (zlib_version) est incompatible avec la version supposée par l'appelant (ZLIB_VERSION). msg est défini sur null s'il n'y a pas de message d'erreur. deflateInit2 n'effectue aucune compression : celle-ci sera effectuée par deflate().

Initialise le dictionnaire de compression à partir de la séquence d'octets donnée sans produire de sortie compressée. Cette fonction doit être appelée immédiatement après deflateInit, deflateInit2 ou deflateReset, avant tout appel de deflate. Le compresseur et le décompresseur doivent utiliser exactement le même dictionnaire (voir inflateSetDictionary). sans produire de sortie compressée. Lorsque vous utilisez le format zlib, cette fonction doit être appelée immédiatement après deflateInit, deflateInit2 ou deflateReset, et avant tout appel de deflate. Lorsque vous effectuez un deflate brut, cette fonction doit être appelée soit avant tout appel de deflate, soit immédiatement après la fin d'un bloc deflate, c'est-à-dire après que toutes les entrées ont été consommées et que toutes les sorties ont été délivrées lors de l'utilisation de l'une des options de vidage Z_BLOCK, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH ou Z_FULL_FLUSH. Le compresseur et le décompresseur doivent utiliser exactement le même dictionnaire (voir inflateSetDictionary).

Le dictionnaire doit être constitué de chaînes (séquences d'octets) susceptibles d'être rencontrées plus tard dans les données à compresser, les chaînes de caractères les plus couramment utilisées étant placées de préférence vers la fin du dictionnaire. L'utilisation d'un dictionnaire est particulièrement utile lorsque les données à compresser sont courtes et peuvent être prédites avec une bonne précision; les données peuvent alors être compressées mieux qu'avec le dictionnaire vide par défaut.

Selon la taille des structures de données de compression sélectionnées par deflateInit ou deflateInit2, une partie du dictionnaire peut en effet être supprimée, par exemple si le dictionnaire est plus grand que la taille de la fenêtre dans deflateInit ou deflateInit2. Ainsi, les chaînes les plus susceptibles d'être utiles doivent être placées à la fin du dictionnaire, et non au début. De plus, l'implémentation actuelle de deflate utilisera au maximum la taille de la fenêtre moins 262 octets du dictionnaire fourni.

Au retour de cette fonction, strm->adler est défini sur la valeur Adler-32 du dictionnaire; le décompresseur peut ensuite utiliser cette valeur pour déterminer quel dictionnaire a été utilisé par le compresseur. (La valeur Adler-32 s'applique à l'ensemble du dictionnaire même si seul un sous-ensemble du dictionnaire est réellement utilisé par le compresseur.) Si un deflate brut a été demandé, la valeur Adler-32 n'est pas calculée et strm->adler n'est pas défini.

deflateSetDictionary renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si un paramètre n'est pas valide (comme un dictionnaire NULL) ou si l'état du flux est incohérent (par exemple si deflate a déjà été appelé pour ce flux ou s'il n'est pas à une limite de bloc pour le deflate brut). deflateSetDictionary n'effectue aucune compression : cela sera fait par deflate().

Renvoie le dictionnaire glissant maintenu par deflate. dictLength est défini sur le nombre d'octets dans le dictionnaire, et ce nombre d'octets est copié dans le dictionnaire. Le dictionnaire doit avoir suffisamment d'espace, où 32768 octets sont toujours suffisants. Si deflateGetDictionary() est appelé avec un dictionnaire égal à Z_NULL, seule la longueur du dictionnaire est renvoyée et rien n'est copié. De même, si dictLength est Z_NULL, il n'est pas défini.

deflateGetDictionary() peut renvoyer une longueur inférieure à la taille de la fenêtre, même si une taille supérieure à la taille de la fenêtre en entrée a été fournie. Il peut renvoyer jusqu'à 258 octets de moins dans ce cas, en raison de la façon dont l'implémentation de deflate de zlib gère la fenêtre glissante et l'anticipation des correspondances, où les correspondances peuvent atteindre 258 octets de long. Si l'application a besoin des derniers octets de taille de fenêtre en entrée, ceux-ci doivent être enregistrés par l'application en dehors de zlib.

deflateGetDictionary renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux est incohérent.

Définit le flux de destination comme une copie complète du flux source.

Cette fonction peut être utile lorsque plusieurs stratégies de compression doivent être essayées, par exemple lorsqu'il existe plusieurs façons de prétraiter les données d'entrée avec un filtre. Les flux étant rejetés doivent ensuite être libérés en appelant deflateEnd. Notez que deflateCopy duplique l'état de compression interne pouvant être assez volumineux, donc cette stratégie est lente et peut consommer beaucoup de mémoire.

deflateCopy renvoie Z_OK en cas de succès, Z_MEM_ERROR s'il n'y avait pas assez de mémoire, Z_STREAM_ERROR si l'état du flux source était incohérent (comme zalloc étant NULL). msg reste inchangé à la fois dans la source et la destination.

Cette fonction est équivalente à deflateEnd suivie de deflateInit, mais ne libère pas et ne réalloue pas l'état de compression interne. Le flux laissera le niveau de compression et tous les autres attributs qui auraient pu être définis inchangés. total_in, total_out, adler et msg sont initialisés.

deflateReset renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux source était incohérent (par exemple, zalloc ou l'état étant NULL).

Mettre à jour dynamiquement le niveau de compression et la stratégie de compression. L'interprétation du niveau et de la stratégie est la même que dans deflateInit2(). Cela peut être utilisé pour basculer entre la compression et la copie directe des données d'entrée, ou pour basculer vers un autre type de données d'entrée nécessitant une stratégie différente. Si l'approche de compression (étant une fonction du niveau) ou la stratégie est modifiée, et s'il y a eu des appels deflate() depuis l'initialisation ou la réinitialisation de l'état, alors l'entrée disponible jusqu'à présent est compressée avec l'ancien niveau et la stratégie en utilisant deflate(strm, Z_BLOCK). Il existe trois approches pour les niveaux de compression 0, 1..3 et 4..9 respectivement. Le nouveau niveau et la nouvelle stratégie prendront effet au prochain appel de deflate().

Si un deflate(strm, Z_BLOCK) est exécuté par deflateParams(), et qu'il n'a pas assez d'espace de sortie pour terminer, alors le changement de paramètre ne prendra pas effet. Dans ce cas, deflateParams() peut être appelé à nouveau avec les mêmes paramètres et plus d'espace de sortie pour réessayer.

Afin de garantir un changement des paramètres dès le premier essai, le flux deflate doit être vidé à l'aide de deflate() avec Z_BLOCK ou une autre requête de vidage jusqu'à ce que strm.avail_out ne soit pas nul, avant d'appeler deflateParams(). Ensuite, aucune autre donnée d'entrée ne doit être fournie avant l'appel deflateParams(). Si cela est fait, l'ancien niveau et la nouvelle stratégie seront appliqués aux données compressées avant deflateParams(), et le nouveau niveau et la nouvelle stratégie seront appliqués aux données compressées après deflateParams().

deflateParams renvoie Z_OK en cas de succès, Z_STREAM_ERROR si l'état du flux source était incohérent ou si un paramètre était invalide, ou Z_BUF_ERROR s'il n'y avait pas assez d'espace de sortie pour terminer la compression des données d'entrée disponibles avant un changement de stratégie ou d'approche. Notez que dans le cas d'un Z_BUF_ERROR, les paramètres ne sont pas modifiés. Une valeur de retour de Z_BUF_ERROR n'est pas fatale, auquel cas deflateParams() peut être réessayé avec plus d'espace de sortie.

Ajustez les paramètres de compression internes de deflate. Cela ne doit être utilisé que par quelqu'un qui comprend l'algorithme utilisé par deflate de zlib pour rechercher la meilleure chaîne correspondante, et même dans ce cas, uniquement par l'optimiseur le plus fanatique essayant d'extraire le dernier bit compressé pour ses données d'entrée spécifiques. Lisez le code source deflate.c pour connaître la signification des paramètres max_lazy, good_length, nice_length et max_chain.

deflateTune() peut être appelé après deflateInit() ou deflateInit2(), et renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR pour un flux deflate non valide.

deflateBound() renvoie une limite supérieure sur la taille compressée après dégonflage de sourceLen octets. Elle doit être appelée après deflateInit() ou deflateInit2(). Elle serait utilisée pour allouer un tampon de sortie pour le dégonflage en un seul passage, et serait donc appelée avant deflate(). Si ce premier appel deflate() reçoit les octets d'entrée sourceLen, un tampon de sortie alloué à la taille renvoyée par deflateBound() et la valeur de vidage Z_FINISH, alors deflate() est assuré de renvoyer Z_STREAM_END. Notez qu'il est possible que la taille compressée soit supérieure à la valeur renvoyée par deflateBound() si des options de vidage autres que Z_FINISH ou Z_NO_FLUSH sont utilisées.

deflatePending() renvoie le nombre d'octets et de bits de sortie ayant été générés, mais qui ne sont pas encore fournis dans la sortie disponible. Les octets non fournis seraient dus à l'espace de sortie disponible consommé. Le nombre de bits de sortie non fournis est compris entre 0 et 7, où ils attendent que davantage de bits les rejoignent afin de remplir un octet complet. Si les bits en attente sont Z_NULL, ces valeurs ne sont pas définies.

deflatePending renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux source était incohérent.

deflatePrime() insère des bits dans le flux de sortie deflate. L'objectif est que cette fonction soit utilisée pour démarrer la sortie deflate avec les bits restants d'un flux deflate précédent lors de l'ajout à celui-ci. En tant que telle, cette fonction ne peut être utilisée que pour le deflate brut et doit être utilisée avant le premier appel deflate() après un deflateInit2() ou deflateReset(). bits doit être inférieur ou égal à 16, et que la plupart des bits de valeur les moins significatifs seront insérés dans la sortie.

deflatePrime renvoie Z_OK en cas de succès, Z_BUF_ERROR s'il n'y avait pas assez de place dans le tampon interne pour insérer les bits, ou Z_STREAM_ERROR si l'état du flux source était incohérent.

deflateSetHeader() fournit des informations d'entête gzip lorsqu'un flux gzip est demandé par deflateInit2(). deflateSetHeader() peut être appelé après deflateInit2() ou deflateReset() et avant le premier appel de deflate(). Les informations de texte, d'heure, d'os, de champ supplémentaire, de nom et de commentaire dans la structure gz_header fournie sont écrites dans l'entête gzip (xflag est ignoré - les indicateurs supplémentaires sont définis en fonction du niveau de compression). L'appelant doit s'assurer que, si ce n'est pas Z_NULL, le nom et le commentaire se terminent par un octet zéro, et que si extra n'est pas Z_NULL, que des octets extra_len y sont disponibles. Si hcrc est vrai, un crc d'entête gzip est inclus. Notez que les versions actuelles de la version en ligne de commande de gzip (jusqu'à la version 1.3.x) ne prennent pas en charge les crc d'entête et signaleront qu'il s'agit d'un "multi-part gzip file" et abandonneront.

Si deflateSetHeader n'est pas utilisé, l'entête gzip par défaut contient le texte false, l'heure définie sur zéro et os défini sur le système d'exploitation actuel, sans champs supplémentaires, nom ou commentaire. L'entête gzip est renvoyé à l'état par défaut par deflateReset().

deflateSetHeader renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux source était incohérent.

Il s'agit d'une autre version de inflateInit avec un paramètre supplémentaire. Les champs next_in, avail_in, zalloc, zfree et opaque doivent être initialisés au préalable par l'appelant.

Le paramètre windowBits est le logarithme en base deux de la taille maximale de la fenêtre (la taille du tampon d'historique). Il doit être compris entre 8 et 15 pour cette version de la bibliothèque. La valeur par défaut est 15 si inflateInit est utilisé à la place. windowBits doit être supérieur ou égal à la valeur windowBits fournie à deflateInit2() lors de la compression, ou il doit être égal à 15 si deflateInit2() n'a pas été utilisé. Si un flux compressé avec une taille de fenêtre plus grande est donné en entrée, inflate() renverra le code d'erreur Z_DATA_ERROR au lieu d'essayer d'allouer une fenêtre plus grande.

windowBits peut également être nul pour demander à inflate d'utiliser la taille de fenêtre dans l'entête zlib du flux compressé.

windowBits peut également être de -8..-15 pour les données brutes inflate. Dans ce cas, -windowBits détermine la taille de la fenêtre. inflate() traitera alors les données brutes deflate, sans rechercher d'entête zlib ou gzip, sans générer de valeur de contrôle et sans rechercher de valeurs de contrôle pour comparaison à la fin du flux. Ceci est à utiliser avec d'autres formats qui utilisent le format de données compressées deflate tels que zip. Ces formats fournissent leurs propres valeurs de contrôle. Si un format personnalisé est développé en utilisant le format brut deflate pour les données compressées, il est recommandé d'appliquer une valeur de contrôle telle qu'un Adler-32 ou un CRC-32 aux données non compressées comme cela se fait dans les formats zlib, gzip et zip. Pour la plupart des applications, le format zlib doit être utilisé tel quel. Notez que les commentaires ci-dessus sur l'utilisation dans deflateInit2() s'appliquent à la grandeur de windowBits.

windowBits peut également être supérieur à 15 pour un décodage gzip facultatif. Ajoutez 32 à windowBits pour activer le décodage zlib et gzip avec détection automatique des en-têtes, ou ajoutez 16 pour décoder uniquement le format gzip (le format zlib renverra une Z_DATA_ERROR). Si un flux gzip est en cours de décodage, strm->adler est un CRC-32 au lieu d'un Adler-32. Contrairement à l'utilitaire gunzip et à gzread() (voir ci-dessous), inflate() ne décodera pas automatiquement les membres gzip concaténés. inflate() renverra Z_STREAM_END à la fin du membre gzip. L'état devra être réinitialisé pour continuer à décoder un membre gzip ultérieur. Cela doit être fait s'il y a plus de données après un membre gzip, afin que la décompression soit conforme à la norme gzip (RFC 1952).

inflateInit2 renvoie Z_OK en cas de succès, Z_MEM_ERROR s'il n'y avait pas assez de mémoire, Z_VERSION_ERROR si la version de la bibliothèque zlib est incompatible avec la version supposée par l'appelant, Z_STREAM_ERROR si un paramètre n'est pas valide, comme un pointeur nul vers la structure. msg est défini sur null s'il n'y a pas de message d'erreur. inflateInit2 n'effectue aucune décompression en dehors de la lecture de l'entête zlib s'il est présent : la décompression réelle est effectuée par inflate(). (Ainsi, next_in et avail_in peuvent être modifiés, mais next_out et avail_out sont inutilisés et inchangés.) L'implémentation actuelle de inflateInit2() ne traite aucune information d'entête, étant différée jusqu'à ce que inflate() soit appelé.

Initialise le dictionnaire de décompression à partir de la séquence d'octets non compressée donnée. Cette fonction doit être appelée immédiatement après un appel à inflate, si cet appel a renvoyé Z_NEED_DICT. Le dictionnaire choisi par le compresseur peut être déterminé à partir de la valeur Adler-32 renvoyée par cet appel à inflate. Le compresseur et le décompresseur doivent utiliser exactement le même dictionnaire (voir deflateSetDictionary). Pour un inflate brut, cette fonction peut être appelée à tout moment pour définir le dictionnaire. Si le dictionnaire fourni est plus petit que la fenêtre et qu'il y a déjà des données dans la fenêtre, alors le dictionnaire fourni modifiera ce qui s'y trouve. L'application doit s'assurer que le dictionnaire ayant été utilisé pour la compression est fourni.

inflateSetDictionary renvoie Z_OK en cas de succès, Z_STREAM_ERROR si un paramètre n'est pas valide (comme un dictionnaire NULL) ou si l'état du flux est incohérent, Z_DATA_ERROR si le dictionnaire donné ne correspond pas à celui attendu (valeur Adler-32 incorrecte). inflateSetDictionary n'effectue aucune décompression : celle-ci sera effectuée par les appels ultérieurs de inflate().

Renvoie le dictionnaire glissant maintenu par inflate. dictLength est défini sur le nombre d'octets dans le dictionnaire, et ce nombre d'octets est copié dans le dictionnaire. Le dictionnaire doit avoir suffisamment d'espace, où 32 768 octets sont toujours suffisants. Si inflateGetDictionary() est appelé avec un dictionnaire égal à Z_NULL, seule la longueur du dictionnaire est renvoyée et rien n'est copié. De même, si dictLength est i, il n'est pas défini.

inflateGetDictionary renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux est incohérent.

Ignore les données compressées non valides jusqu'à ce qu'un point de vidage complet possible (voir ci-dessus pour la description de deflate avec Z_FULL_FLUSH) puisse être trouvé, ou jusqu'à ce que toutes les entrées disponibles soient ignorées. Aucune sortie n'est fournie.

inflateSync recherche un modèle 00 00 FF FF dans les données compressées. Tous les points de vidage complet ont ce modèle, mais toutes les occurrences de ce modèle ne sont pas des points de vidage complet.

inflateSync renvoie Z_OK si un point de vidage complet possible a été trouvé, Z_BUF_ERROR si aucune autre entrée n'a été fournie, Z_DATA_ERROR si aucun point de vidage n'a été trouvé, ou Z_STREAM_ERROR si la structure du flux était incohérente. En cas de réussite, l'application peut enregistrer la valeur actuelle de total_in indiquant où des données compressées valides ont été trouvées. En cas d'erreur, l'application peut appeler inflateSync à plusieurs reprises, en fournissant plus d'entrées à chaque fois, jusqu'à la réussite ou la fin des données d'entrée.

Définit le flux de destination comme une copie complète du flux source.

Cette fonction peut être utile lors d'un accès aléatoire à un flux volumineux. Le premier passage dans le flux peut enregistrer périodiquement l'état d'inflate, ce permettant de redémarrer inflate à ces points lors d'un accès aléatoire au flux.

inflateCopy renvoie Z_OK en cas de succès, Z_MEM_ERROR s'il n'y avait pas assez de mémoire, Z_STREAM_ERROR si l'état du flux source était incohérent (par exemple, zalloc étant NULL). msg reste inchangé à la fois dans la source et la destination.

Cette fonction est équivalente à inflateEnd suivie de inflateInit, mais ne libère pas et ne réalloue pas l'état de décompression interne. Le flux conservera les attributs ayant pu être définis par inflateInit2. total_in, total_out, adler et msg sont initialisés.

inflateReset renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux source était incohérent (par exemple, zalloc ou l'état étant NULL).

Cette fonction est la même que inflateReset, mais elle permet également de modifier les requêtes de taille de fenêtre et de retour à la ligne. Le paramètre windowBits est interprété de la même manière que pour inflateInit2. Si la taille de la fenêtre est modifiée, la mémoire allouée à la fenêtre est libérée et la fenêtre sera réallouée par inflate() si nécessaire.

inflateReset2 renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux source était incohérent (comme zalloc ou l'état étant Z_NULL), ou si le paramètre windowBits n'est pas valide.

Cette fonction insère des bits dans le flux d'entrée inflate. L'objectif est que cette fonction soit utilisée pour démarrer l'inflation à une position de bit au milieu d'un octet. Les bits fournis seront utilisés avant que les octets ne soient utilisés à partir de next_in. Cette fonction ne doit être utilisée qu'avec inflate brut et doit être utilisée avant le premier appel inflate() après inflateInit2() ou inflateReset(). bits doit être inférieur ou égal à 16 et que la plupart des bits de valeur les moins significatifs seront insérés dans l'entrée.

Si bits est négatif, le tampon de bits du flux d'entrée est vidé. Ensuite, inflatePrime() peut être appelé à nouveau pour mettre des bits dans le tampon. Ceci est utilisé pour effacer les bits restants après avoir fourni à inflate une description de bloc avant d'alimenter les codes inflate.

inflatePrime renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux source était incohérent.

Cette fonction renvoie deux valeurs, l'une dans les 16 bits inférieurs de la valeur de retour, et l'autre dans les bits supérieurs restants, obtenues en décalant la valeur de retour de 16 bits vers le bas. Si la valeur supérieure est -1 et la valeur inférieure est zéro, alors inflate() décode actuellement des informations en dehors d'un bloc. Si la valeur supérieure est -1 et la valeur inférieure est différente de zéro, alors inflate se trouve au milieu d'un bloc entreposé, la valeur inférieure étant égale au nombre d'octets de l'entrée restant à copier. Si la valeur supérieure n'est pas -1, alors il s'agit du nombre de bits en arrière de la position de bit actuelle dans l'entrée du code (littéral ou paire longueur/distance) en cours de traitement. Dans ce cas, la valeur inférieure est le nombre d'octets déjà émis pour ce code.

Un code est en cours de traitement si inflate attend plus d'entrées pour terminer le décodage du code, ou s'il a terminé le décodage mais attend plus d'espace de sortie pour écrire les données littérales ou de correspondance.

inflateMark() est utilisé pour marquer les emplacements dans les données d'entrée pour un accès aléatoire, pouvant être à des positions de bits, et pour noter les cas où la sortie d'un code peut s'étendre sur les limites des blocs d'accès aléatoire. L'emplacement actuel dans le flux d'entrée peut être déterminé à partir de avail_in et data_type comme indiqué dans la description du paramètre de vidage Z_BLOCK pour inflate.

inflateMark renvoie la valeur indiquée ci-dessus ou -65536 si l'état du flux source fourni était incohérent.

inflateGetHeader() demande que les informations d'entête gzip soient entreposées dans la structure gz_header fournie. inflateGetHeader() peut être appelé après inflateInit2() ou inflateReset(), et avant le premier appel de inflate(). Lorsque inflate() traite le flux gzip, head-&hg;done est égal à zéro jusqu'à ce que l'entête soit terminé, moment auquel head->done est défini sur un. Si un flux zlib est en cours de décodage, head->done est défini sur -1 pour indiquer qu'aucune information d'entête gzip ne sera fournie. Notez que Z_BLOCK peut être utilisé pour forcer inflate() à revenir immédiatement après la fin du traitement de l'entête et avant que les données réelles ne soient décompressées.

Les champs texte, heure, xflags et os sont remplis avec le contenu de l'entête gzip. hcrc est défini sur true s'il existe un CRC d'entête. (Le CRC de l'entête était valide si done est défini sur un.) Si extra n'est pas Z_NULL, alors extra_max contient le nombre maximal d'octets à écrire dans extra. Une fois done est vrai, extra_len contient la longueur réelle du champ extra, et extra contient le champ extra, ou ce champ tronqué si extra_max est inférieur à extra_len. Si name n'est pas Z_NULL, alors jusqu'à name_max caractères y sont écrits, terminés par un zéro sauf si la longueur est supérieure à name_max. Si comment n'est pas Z_NULL, alors jusqu'à comm_max caractères y sont écrits, terminés par un zéro sauf si la longueur est supérieure à comm_max. Lorsque l'un des extra, name ou comment n'est pas Z_NULL et que le champ respectif n'est pas présent dans l'entête, alors ce champ est défini sur Z_NULL pour signaler son absence. Cela permet l'utilisation de deflateSetHeader() avec la structure renvoyée pour dupliquer l'entête. Cependant, si ces champs sont définis sur la mémoire allouée, l'application devra alors enregistrer ces pointeurs ailleurs afin qu'ils puissent être libérés ultérieurement.

Si inflateGetHeader n'est pas utilisé, les informations d'entête sont simplement ignorées. La validité de l'entête est toujours vérifiée, y compris le CRC de l'entête s'il est présent. inflateReset() réinitialisera le processus pour ignorer les informations d'en-tête. L'application devra appeler à nouveau inflateGetHeader() pour récupérer l'en-tête du prochain flux gzip.

inflateGetHeader renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux source était incohérent.

Initialisez l'état du flux interne pour la décompression à l'aide d'appels inflateBack(). Les champs zalloc, zfree et opaque dans strm doivent être initialisés avant l'appel. Si zalloc et zfree sont Z_NULL, alors les routines d'allocation de mémoire par défaut dérivées de la bibliothèque sont utilisées. windowBits est le logarithme en base deux de la taille de la fenêtre, dans l'intervalle 8..15. window est un tampon fourni par l'appelant de cette taille. Sauf pour les applications spéciales où il est assuré que deflate a été utilisé avec de petites tailles de fenêtre, windowBits doit être 15 et une fenêtre de 32 Ko doit être fournie pour pouvoir décompresser les flux deflate généraux.

Voir inflateBack() pour l'utilisation de ces routines.

inflateBackInit renverra Z_OK en cas de succès, Z_STREAM_ERROR si l'un des paramètres n'est pas valide, Z_MEM_ERROR si l'état interne n'a pas pu être alloué ou Z_VERSION_ERROR si la version de la bibliothèque ne correspond pas à la version du fichier d'entête.

inflateBack() effectue un gonflement brut avec un seul appel en utilisant une interface de rappel pour l'entrée et la sortie. Ceci est potentiellement plus efficace que inflate() pour les applications d'entrées/sorties de fichiers, dans la mesure où cela évite la copie entre la sortie et la fenêtre glissante en faisant simplement de la fenêtre elle-même le tampon de sortie. inflate() peut être plus rapide sur les processeurs modernes lorsqu'il est utilisé avec des tampons volumineux. inflateBack() fait confiance à l'application pour ne pas modifier le tampon de sortie transmis par la fonction de sortie, au moins jusqu'au retour de inflateBack().

inflateBackInit() doit être appelé en premier pour allouer l'état interne et pour initialiser l'état avec le tampon de fenêtre fourni par l'utilisateur. inflateBack() peut ensuite être utilisé plusieurs fois pour gonfler un flux de dégonflage brut complet à chaque appel. inflateBackEnd() est ensuite appelé pour libérer l'état alloué.

Un flux de dégonflage brut est un flux sans entête ou remorque zlib ou gzip. Cette routine serait normalement utilisée dans un utilitaire lisant les fichiers zip ou gzip et écrit les fichiers non compressés. L'utilitaire décoderait l'entête et traiterait la fin de la procédure par lui-même, c'est pourquoi cette routine s'attend à ce que seul le flux deflate brut soit décompressé. Ceci est différent du comportement par défaut de inflate(), attendant un entête et une fin de procédure zlib autour du flux deflate.

inflateBack() utilise deux sous-routines fournies par l'appelant étant ensuite appelées par inflateBack() pour l'entrée et la sortie. inflateBack() appelle ces routines jusqu'à ce qu'il lise un flux deflate complet et écrive toutes les données non compressées, ou jusqu'à ce qu'il rencontre une erreur. Les paramètres et les types de retour de la fonction sont définis ci-dessus dans les définitions de type in_func et out_func. inflateBack() appellera in(in_desc, &buf) devant renvoyer le nombre d'octets d'entrée fournis et un pointeur vers cette entrée dans buf. Si aucune entrée n'est disponible, in() doit renvoyer zéro (buf est ignoré dans ce cas) et inflateBack() renvoie une erreur de tampon. inflateBack() appelle out(out_desc, buf, len) pour écrire les données non compressées buf[0..len-1]. out() doit renvoyer zéro en cas de succès, ou une valeur différente de zéro en cas d'échec. Si out() renvoie une valeur différente de zéro, inflateBack() renvoie une erreur. Ni in() ni out() ne sont autorisés à modifier le contenu de la fenêtre fournie à inflateBackInit(), étant également le tampon que out() utilise pour écrire. La longueur écrite par out() sera au plus égale à la taille de la fenêtre. Toute quantité d'entrée différente de zéro peut être fournie par in().

Pour plus de commodité, inflateBack() peut être fourni en entrée lors du premier appel en définissant strm->next_in et strm->avail_in. Si cette entrée est épuisée, in() sera alors appelé. Par conséquent, strm->next_in doit être initialisé avant d'appeler inflateBack(). Si strm->next_in est Z_NULL, alors in() sera appelé immédiatement pour l'entrée. Si strm->next_in n'est pas Z_NULL, alors strm->avail_in doit également être initialisé, et si strm->avail_in n'est pas nul, l'entrée sera initialement extraite de strm->next_in[0 .. strm->avail_in - 1].

Les paramètres in_desc et out_desc de inflateBack() sont passés comme premier paramètre de in() et out() respectivement lorsqu'ils sont appelés. Ces descripteurs peuvent être utilisés en option pour transmettre toute information dont les fonctions in() et out() fournies par l'appelant ont besoin pour faire leur travail.

En retour, inflateBack() définit strm->next_in et strm->avail_in pour renvoyer toute entrée inutilisée fournie par le dernier appel in(). Les valeurs de retour de inflateBack() peuvent être Z_STREAM_END en cas de succès, Z_BUF_ERROR si in() ou out() a renvoyé une erreur, Z_DATA_ERROR s'il y avait une erreur de format dans le flux deflate (auquel cas strm->msg est défini pour indiquer la nature de l'erreur), ou Z_STREAM_ERROR si le flux n'a pas été correctement initialisé. Dans le cas de Z_BUF_ERROR, une erreur d'entrée ou de sortie peut être distinguée en utilisant strm->next_in étant Z_NULL uniquement si in() a renvoyé une erreur. Si strm->next_in n'est pas Z_NULL, alors Z_BUF_ERROR était dû au fait que out() a renvoyé une valeur différente de zéro. (in() sera toujours appelé avant out(), donc strm->next_in est assuré d'être défini si out() renvoie une valeur différente de zéro.) Notez que inflateBack() ne peut pas renvoyer Z_OK.

Toute la mémoire allouée par inflateBackInit() est libérée.

inflateBackEnd() renvoie Z_OK en cas de succès, ou Z_STREAM_ERROR si l'état du flux était incohérent.

Drapeaux de retour indiquant les options de compilation.

Tailles de type, deux bits chacune, 00 = 16 bits, 01 = 32, 10 = 64, 11 = autre :

• 1.0 : taille de uInt
• 3.2 : taille de uLong
• 5.4 : taille de voidpf (pointeur)
• 7.6 : taille de z_off_t

Options du compilateur, de l'assembleur et de débogage :

• 8 : ZLIB_DEBUG
• 9 : ASMV ou ASMINF : utiliser le code ASM
• 10 : ZLIB_WINAPI : les fonctions exportées utilisent la convention d'appel WINAPI
• 11 : 0 (réservé)

Création de table à usage unique (code plus petit, mais non thread-safe si vrai) :

• 12 : BUILDFIXED : créer des tables de décodage de blocs statiques si nécessaire
• 13 : DYNAMIC_CRC_TABLE : créer des tables de calcul CRC si nécessaire
• 14,15 : 0 (réservé)

Contenu de la bibliothèque (indique une fonctionnalité manquante) :

• 16 : NO_GZCOMPRESS : les fonctions gz* ne peuvent pas compresser (pour éviter de lier le code deflate lorsqu'il n'est pas nécessaire)
• 17 : NO_GZIP : deflate ne peut pas écrire de flux gzip et inflate ne peut pas détecter et décoder les flux gzip (pour éviter de lier le code deflate lorsqu'il n'est pas nécessaire) crc code)
• 18-19 : 0 (réservé)

Variantes d'opération (changements dans les fonctionnalités de la bibliothèque) :

• 20 : PKZIP_BUG_WORKAROUND - gonflage légèrement plus permissif
• 21 : FASTEST - algorithme de dégonflage avec un seul niveau de compression le plus bas
• 22,23 : 0 (réservé)

La variante sprintf utilisée par gzprintf (zéro est le meilleur) :

• 24 : 0 = vs*, 1 = s* - 1 signifie limité à 20 arguments après le format
• 25 : 0 = *nprintf, 1 = *printf - 1 signifie que gzprintf() n'est pas sécurisé !
• 26 : 0 = renvoie une valeur, 1 = void - 1 signifie que la longueur de chaîne déduite est renvoyée

Reste :

• 27-31 : 0 (réservé)