zip_source_function

Syntaxe

Retour

Les commandes doivent renvoyer -1 en cas d'erreur. ZIP_SOURCE_ERROR sera appelé pour récupérer le code d'erreur. En cas de réussite, les commandes renvoient 0, sauf indication contraire dans la description ci-dessus.

Description

Cette fonction permet de créer une source de données ZIP à partir d'une fonction personnalisée.

Remarques

• Les fonctions zip_source_function() et zip_source_function_create() créent une source zip à partir de la fonction fn fournie par l'utilisateur, devant être du type suivant :

typedef zip_int64_t (*zip_source_callback)(void *userdata, void *data, zip_uint64_t len, zip_source_cmd_t cmd);

archive ou error sont utilisés pour signaler les erreurs et peuvent être NULL.

Lorsqu'il est appelé par la bibliothèque, le premier paramètre est le paramètre userdata fourni à la fonction. Les deux paramètres suivants sont des données tampon de taille len lorsque des données sont transmises ou doivent être renvoyées, ou bien NULL et 0. Le dernier argument, cmd, spécifie l'action que la fonction doit effectuer.

• En fonction des utilisations, il existe trois ensembles de commandes utiles à prendre en charge par un zip_source_callback() :

Ensemble de commandes	Description
source de lecture	Fourniture de données en flux de données (pour les données de fichiers ajoutées aux archives). Doit prendre en charge ZIP_SOURCE_OPEN, ZIP_SOURCE_READ, ZIP_SOURCE_CLOSE, ZIP_SOURCE_STAT et ZIP_SOURCE_ERROR. Si votre source utilise de la mémoire allouée (y compris les données utilisateur), elle doit également implémenter ZIP_SOURCE_FREE pour éviter les fuites de mémoire.
source de lecture recherchable	Identique à la précédente, mais à partir d'une source autorisant la lecture à partir de décalages arbitraires (également pour les archives zip en lecture seule). Doit également prendre en charge ZIP_SOURCE_SEEK, ZIP_SOURCE_TELL et ZIP_SOURCE_SUPPORTS.
source de lecture/écriture	Identique à la précédente, mais autorisant en plus l'écriture (également pour les archives zip inscriptibles). Doit également prendre en charge ZIP_SOURCE_BEGIN_WRITE, ZIP_SOURCE_COMMIT_WRITE, ZIP_SOURCE_ROLLBACK_WRITE, ZIP_SOURCE_SEEK_WRITE, ZIP_SOURCE_TELL_WRITE et ZIP_SOURCE_REMOVE.

En plus de ce qui précède, la prise en charge de la pseudo-commande ZIP_SOURCE_SUPPORTS_REOPEN permet d'appeler à nouveau zip_source_open() après avoir appelé zip_source_close().

Constante	Description
ZIP_SOURCE_ACCEPT_EMPTY	Renvoie 1 si une source vide doit être acceptée comme archive zip valide. Il s'agit de la valeur par défaut si cette commande n'est pas prise en charge par une source. Les sources sauvegardées par le système de fichiers doivent renvoyer 0.
ZIP_SOURCE_BEGIN_WRITE	Préparez la source pour l'écriture. Utilisez ceci pour créer des fichiers temporaires.
ZIP_SOURCE_BEGIN_WRITE_CLONING	Préparez la source pour l'écriture, en conservant les premiers octets du fichier d'origine. N'exécutez cette commande que si elle est plus efficace que la copie des données, et si elle n'écrase pas de manière destructive le fichier d'origine (vous devez toujours pouvoir exécuter ZIP_SOURCE_ROLLBACK_WRITE).

L'écriture suivante doit se produire à un déplacement d'octet offset :

Constante	Description
ZIP_SOURCE_CLOSE	La lecture est terminée.
ZIP_SOURCE_COMMIT_WRITE	Terminez l'écriture dans la source. Remplacez les données d'origine par les données nouvellement écrites. Nettoyez les fichiers temporaires ou les tampons internes. L'ouverture et la lecture ultérieures à partir de la source devraient renvoyer les données nouvellement écrites.
ZIP_SOURCE_ERROR	Obtenir les informations d'erreur. Les données pointent vers un tableau de deux entiers, devant être remplis avec le code d'erreur de libzip et le code d'erreur système correspondant à l'erreur survenue. Voir zip_errors() pour plus de détails sur les codes d'erreur. Si la source stocke les informations d'erreur dans un zip_error_t, utilisez zip_error_to_data() et renvoyez sa valeur de retour. Sinon, renvoyez 2 * sizeof(int).
ZIP_SOURCE_FREE	Nettoyez et libérez toutes les ressources, y compris les données utilisateur. La fonction de rappel ne sera plus appelée.
ZIP_SOURCE_GET_FILE_ATTRIBUTES	Fournit des informations sur diverses données. Les données doivent ensuite être placées dans l'entrée appropriée dans le paramètre zip_file_attributes_t passé, et la valeur ZIP_FILE_ATTRIBUTES_* appropriée doit être associée au membre valide pour indiquer que les données correspondantes ont été fournies. Une structure zip_file_attributes_t peut être initialisée à l'aide de zip_file_attributes_init() : Catégorie Description Mode ASCII Si un fichier est un fichier texte brut au format ASCII. Peut être utilisé par les outils d'extraction pour convertir automatiquement les fins de ligne (partie des attributs internes du fichier). Membre ascii, indicateur ZIP_FILE_ATTRIBUTES_ASCII. Drapeaux de bits à usage général (limités aux drapeaux de compression) Le drapeau de bits à usage général dans le zip des entêtes de répertoires local et central contient des informations sur la méthode de compression. Membre general_purpose_bit_flags et general_purpose_bit_mask pour indiquer quels membres ont été définis ; indicateur ZIP_FILE_ATTRIBUTES_GENERAL_PURPOSE_BIT_FLAGS. Attributs de fichier externe Les attributs de fichier externe (généralement spécifiques au système d'exploitation). Membre external_file_attributes, indicateur ZIP_FILE_ATTRIBUTES_EXTERNAL_FILE_ATTRIBUTES. Version requise Une version minimale requise est requise pour décompresser cette entrée (au format habituel « majeur * 10 + mineur »). Membre version_needed, indicateur ZIP_FILE_ATTRIBUTES_VERSION_NEEDED. Système d'exploitation L'un des systèmes d'exploitation tels que définis par les variables ZIP_OPSYS_* (voir zip.h). Cette valeur affecte l'interprétation des attributs de fichier externe. Membre host_system, indicateur ZIP_FILE_ATTRIBUTES_HOST_SYSTEM.
ZIP_SOURCE_OPEN	Prépare à la lecture.
ZIP_SOURCE_READ	Lire les données dans le tampon data de taille len. Renvoyer le nombre d'octets placés dans data en cas de succès, et zéro pour la fin du fichier.
ZIP_SOURCE_REMOVE	Supprime le fichier sous-jacent. Cette fonction est appelée si une archive zip est vide lors de sa fermeture.
ZIP_SOURCE_ROLLBACK_WRITE	Interrompre l'écriture dans la source. Supprimer les données écrites. Nettoyer les fichiers temporaires ou les tampons internes. L'ouverture et la lecture ultérieures à partir de la source doivent renvoyer les données d'origine.
ZIP_SOURCE_SEEK	Spécifiez la position à partir de laquelle lire l'octet suivant, comme fseek(). Utilisez ZIP_SOURCE_GET_ARGS(3) pour décoder les paramètres dans la structure suivante : struct zip_source_args_seek {     zip_int64_t offset;     int whence; }; Si la taille des données de la source est connue, utilisez zip_source_seek_compute_offset(3) pour valider les paramètres et calculer le nouveau déplacement.
ZIP_SOURCE_SEEK_WRITE	Spécifie la position à laquelle écrire l'octet suivant, comme fseek(). Voir ZIP_SOURCE_SEEK pour plus de détails.
ZIP_SOURCE_STAT	Obtenir des méta-informations pour les données d'entrée. Les données pointent vers une structure zip_stat allouée, devant être initialisée à l'aide de zip_stat_init() puis renseignée. Pour les données non compressées et non chiffrées, toutes les informations sont facultatives. Cependant, remplissez autant d'informations que possible. Si les données sont compressées, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE et ZIP_STAT_CRC doivent être renseignés. Si les données sont chiffrées, ZIP_STAT_ENCRYPTION_METHOD, ZIP_STAT_COMP_METHOD, ZIP_STAT_SIZE et ZIP_STAT_CRC doivent être renseignés. Les informations disponibles uniquement après la lecture de la source (par exemple, la taille) peuvent être omises lors d'un appel antérieur. REMARQUE : zip_source_function() peut être appelée avec cet argument même après avoir été appelée avec ZIP_SOURCE_CLOSE. Renvoyer sizeof(struct zip_stat) en cas de succès.
ZIP_SOURCE_SUPPORTS	Renvoie une image bitmap spécifiant les commandes prises en charge. Utilisez zip_source_make_command_bitmap(3). Si cette commande n'est pas implémentée, la source est supposée être une source de lecture sans prise en charge de la recherche.
ZIP_SOURCE_TELL	Renvoie le déplacement de lecture actuel dans la source, comme ftell(3).
ZIP_SOURCE_TELL_WRITE	Renvoie le décalage d'écriture actuel dans la source, comme ftell().
ZIP_SOURCE_WRITE	Écrire des données dans la source. Renvoyer le nombre d'octets écrits.
ZIP_SOURCE_SUPPORTS_REOPEN	Cette commande n'est jamais réellement invoquée, sa prise en charge signale la capacité à gérer plusieurs cycles d'ouverture/lecture/fermeture.

Conventions d'appel

La bibliothèque émettra toujours ZIP_SOURCE_OPEN avant d'émettre ZIP_SOURCE_READ, ZIP_SOURCE_SEEK ou ZIP_SOURCE_TELL. Lorsqu'elle ne souhaite plus lire à partir de cette source, elle émettra ZIP_SOURCE_CLOSE. Si la bibliothèque souhaite relire les données, elle émettra ZIP_SOURCE_OPEN une deuxième fois. Si la fonction n'est pas en mesure de fournir à nouveau les données, elle doit renvoyer -1.

ZIP_SOURCE_BEGIN_WRITE ou ZIP_SOURCE_BEGIN_WRITE_CLONING sera appelé avant ZIP_SOURCE_WRITE, ZIP_SOURCE_SEEK_WRITE ou ZIP_SOURCE_TELL_WRITE. Une fois l'écriture terminée, ZIP_SOURCE_COMMIT_WRITE ou ZIP_SOURCE_ROLLBACK_WRITE sera appelé.

ZIP_SOURCE_ACCEPT_EMPTY, ZIP_SOURCE_GET_FILE_ATTRIBUTES et ZIP_SOURCE_STAT peuvent être émis à tout moment.

ZIP_SOURCE_ERROR ne sera émis qu'en réponse à la fonction renvoyant -1.

ZIP_SOURCE_FREE sera la dernière commande émise ; si ZIP_SOURCE_OPEN a été appelé et a réussi, ZIP_SOURCE_CLOSE sera appelé avant ZIP_SOURCE_FREE, et de même pour ZIP_SOURCE_BEGIN_WRITE ou ZIP_SOURCE_BEGIN_WRITE_CLONING et ZIP_SOURCE_COMMIT_WRITE ou ZIP_SOURCE_ROLLBACK_WRITE.

Valeurs de retour

Une fois l'opération terminée avec succès, la source créée est renvoyée. Sinon, NULL est renvoyé et le code d'erreur dans archive ou error est défini pour indiquer l'erreur (sauf s'il est NULL).

Erreurs

zip_source_function() échoue si :

Historique

zip_source_function() et zip_source_function_create() ont été ajoutés dans libzip 1.0.

Voir également

libzip(), zip_file_add(), zip_file_attributes_init(), zip_file_replace(), zip_source(), zip_stat_init().