zip_source_function |
ZIP : Fonction source |
|---|---|
| libzip | |
Syntaxe
| zip_source_t * zip_source_function(zip_t *archive, zip_source_callback fn, void *userdata); |
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 :
- En fonction des utilisations, il existe trois ensembles de commandes utiles à prendre en charge par un zip_source_callback() :
| 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.
| 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() :
|
||||||||||||
| 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 :
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 :
| Constante | Description |
|---|---|
| ZIP_ER_MEMORY | La mémoire requise n'a pas pu être allouée. |
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().